@diveflo/matterbridge-mova 0.1.18

package/dist/module.js

@@ -0,0 +1,2 @@
+export { default } from './index.js';
+export { MovaPlatform } from './platform.js';

package/dist/mova.d.ts

@@ -0,0 +1,13 @@
+import { RoboticVacuumCleaner } from 'matterbridge/devices';
+import type { MovaPlatform } from './platform.js';
+import type { MovaCloudProtocol } from './movaCloud.js';
+import type { MovaDevice, DeviceStatus, RoomInfo } from './types.js';
+export interface MovaVacuumDevice {
+    did: string;
+    name: string;
+    model: string;
+    device: RoboticVacuumCleaner;
+    updateStatus: (status: DeviceStatus) => void;
+    updateRooms: (rooms: RoomInfo[]) => void;
+}
+export declare function discoverAndRegisterDevices(platform: MovaPlatform, cloud: MovaCloudProtocol, device: MovaDevice, rooms: RoomInfo[], initialStatus: DeviceStatus | null): Promise<MovaVacuumDevice | null>;

package/dist/mova.js

@@ -0,0 +1,384 @@
+import { RoboticVacuumCleaner } from 'matterbridge/devices';
+import { MovaState, MovaStatus, MovaCleaningMode, MovaFanSpeed } from './types.js';
+import { getOperationalStateFromMova, getOperationalErrorFromMova } from './constants.js';
+const BatChargeState = {
+    Unknown: 0,
+    IsCharging: 1,
+    IsAtFullCharge: 2,
+    IsNotCharging: 3,
+};
+const RvcRunModeTag = {
+    Idle: 16384,
+    Cleaning: 16385,
+    Mapping: 16386,
+};
+const RvcCleanModeTag = {
+    Vacuum: 16385,
+    Mop: 16386,
+};
+const RvcOperationalStateValue = {
+    Stopped: 0x00,
+    Running: 0x01,
+    Paused: 0x02,
+    Error: 0x03,
+    SeekingCharger: 0x40,
+    Charging: 0x41,
+    Docked: 0x42,
+};
+const ServiceAreaType = {
+    Room: 0,
+};
+const RVC_RUN_MODES = [
+    { label: 'Idle', mode: 0, modeTags: [{ value: RvcRunModeTag.Idle }] },
+    { label: 'Cleaning', mode: 1, modeTags: [{ value: RvcRunModeTag.Cleaning }] },
+    { label: 'Mapping', mode: 2, modeTags: [{ value: RvcRunModeTag.Mapping }] },
+];
+const RVC_CLEAN_MODES = [
+    { label: 'Vacuum', mode: 0, modeTags: [{ value: RvcCleanModeTag.Vacuum }] },
+    { label: 'Vacuum & Mop', mode: 1, modeTags: [{ value: RvcCleanModeTag.Vacuum }, { value: RvcCleanModeTag.Mop }] },
+    { label: 'Mop Only', mode: 2, modeTags: [{ value: RvcCleanModeTag.Mop }] },
+];
+const RVC_OPERATIONAL_STATES = [
+    { operationalStateId: RvcOperationalStateValue.Stopped },
+    { operationalStateId: RvcOperationalStateValue.Running },
+    { operationalStateId: RvcOperationalStateValue.Paused },
+    { operationalStateId: RvcOperationalStateValue.Error },
+    { operationalStateId: RvcOperationalStateValue.SeekingCharger },
+    { operationalStateId: RvcOperationalStateValue.Charging },
+    { operationalStateId: RvcOperationalStateValue.Docked },
+];
+const CONFIG_SUCTION_LEVELS = {
+    quiet: MovaFanSpeed.Quiet,
+    standard: MovaFanSpeed.Standard,
+    strong: MovaFanSpeed.Strong,
+    turbo: MovaFanSpeed.Turbo,
+};
+function configuredSuctionLevel(value) {
+    if (typeof value === 'string' && value in CONFIG_SUCTION_LEVELS) {
+        return CONFIG_SUCTION_LEVELS[value];
+    }
+    return MovaFanSpeed.Standard;
+}
+function configuredVacuumAndMopMode(value) {
+    return value === 'vac-then-mop' ? 'vac-then-mop' : 'vac-mop';
+}
+function rvcToMovaCleanMode(rvcMode, vacuumAndMopMode) {
+    if (rvcMode === 0)
+        return MovaCleaningMode.SweepingAndMopping;
+    if (rvcMode === 1)
+        return vacuumAndMopMode === 'vac-then-mop' ? MovaCleaningMode.MoppingAfterSweeping : MovaCleaningMode.Sweeping;
+    if (rvcMode === 2)
+        return MovaCleaningMode.Mopping;
+    return undefined;
+}
+function movaToRvcCleanMode(cleaningMode) {
+    if (cleaningMode === MovaCleaningMode.SweepingAndMopping)
+        return 0;
+    if (cleaningMode === MovaCleaningMode.Mopping)
+        return 2;
+    return 1;
+}
+export async function discoverAndRegisterDevices(platform, cloud, device, rooms, initialStatus) {
+    const { log } = platform;
+    const suctionLevel = configuredSuctionLevel(platform.config.suctionLevel);
+    const vacuumAndMopMode = configuredVacuumAndMopMode(platform.config.vacuumAndMopMode);
+    log.info(`Creating Matter RVC device for ${device.name} (${device.model})`);
+    const supportedAreas = rooms.length > 0
+        ? rooms.map((room) => ({
+            areaId: room.id,
+            mapId: null,
+            areaInfo: {
+                locationInfo: {
+                    locationName: room.name,
+                    floorNumber: room.floorId ?? null,
+                    areaType: ServiceAreaType.Room,
+                },
+                landmarkInfo: null,
+            },
+        }))
+        : [
+            {
+                areaId: 1,
+                mapId: null,
+                areaInfo: {
+                    locationInfo: {
+                        locationName: 'Home',
+                        floorNumber: null,
+                        areaType: ServiceAreaType.Room,
+                    },
+                    landmarkInfo: null,
+                },
+            },
+        ];
+    let supportedAreaIds = supportedAreas.map((area) => area.areaId);
+    const initialSelectedAreas = [...supportedAreaIds];
+    const initialOperationalState = initialStatus ? getOperationalStateFromMova(initialStatus.state, initialStatus.status) : RvcOperationalStateValue.Docked;
+    const definitiveDockedStatuses = [MovaStatus.Charging, MovaStatus.ChargingComplete, MovaStatus.Sleeping, MovaStatus.Standby, MovaStatus.Idle];
+    let initialRunMode = 0;
+    if (initialStatus && !definitiveDockedStatuses.includes(initialStatus.status)) {
+        const activeCleaningStates = [MovaState.Cleaning, MovaState.Mopping, MovaState.ManualCleaning, MovaState.ZonedCleaning, MovaState.SpotCleaning, MovaState.CruiseRunning];
+        const activeCleaningStatuses = [
+            MovaStatus.Sweeping,
+            MovaStatus.Mopping,
+            MovaStatus.SweepingAndMopping,
+            MovaStatus.SegmentCleaning,
+            MovaStatus.ZoneCleaning,
+            MovaStatus.SpotCleaning,
+        ];
+        if (activeCleaningStates.includes(initialStatus.state) || activeCleaningStatuses.includes(initialStatus.status)) {
+            initialRunMode = 1;
+        }
+        else if (initialStatus.state === MovaState.FastMapping || initialStatus.status === MovaStatus.FastMapping) {
+            initialRunMode = 2;
+        }
+    }
+    const rvc = new RoboticVacuumCleaner(device.name, device.did, 'server', initialRunMode, RVC_RUN_MODES, 0, RVC_CLEAN_MODES, null, null, initialOperationalState, RVC_OPERATIONAL_STATES, supportedAreas, initialSelectedAreas, null, []);
+    rvc.uniqueId = device.did;
+    let trackedRunMode = initialRunMode;
+    let trackedCleanMode = 0;
+    let trackedOperationalState = initialOperationalState;
+    let trackedError = undefined;
+    let selectedAreas = [...initialSelectedAreas];
+    function normalizeSelectedAreas(areas) {
+        if (!areas) {
+            return [...supportedAreaIds];
+        }
+        if (areas.length === 0) {
+            return [...supportedAreaIds];
+        }
+        return Array.from(new Set(areas));
+    }
+    function isWholeHomeSelection(areas) {
+        return supportedAreaIds.length > 0 && areas.length === supportedAreaIds.length && supportedAreaIds.every((id) => areas.includes(id));
+    }
+    rvc.addCommandHandler('identify', async () => {
+        log.info(`Identify command for ${device.name}`);
+        await cloud.locate(device.did);
+    });
+    rvc.addCommandHandler('changeToMode', async (data) => {
+        const newMode = data.request?.newMode ?? data.newMode;
+        const clusterName = data.cluster;
+        log.debug(`changeToMode: cluster=${clusterName}, newMode=${newMode}`);
+        if (newMode === undefined) {
+            log.warn(`changeToMode: newMode is undefined, cannot process command`);
+            return;
+        }
+        const isRunMode = clusterName === 'rvcRunMode' || clusterName === undefined;
+        const isCleanMode = clusterName === 'rvcCleanMode';
+        if (isRunMode) {
+            log.info(`RvcRunMode.changeToMode for ${device.name}: mode=${newMode}`);
+            if (newMode === 0) {
+                const success = await cloud.stopCleaning(device.did);
+                if (success) {
+                    trackedRunMode = 0;
+                    rvc.setAttribute('RvcRunMode', 'currentMode', trackedRunMode, log);
+                    rvc.setAttribute('ServiceArea', 'currentArea', null, log);
+                }
+            }
+            else if (newMode === 1) {
+                const movaCleanMode = rvcToMovaCleanMode(trackedCleanMode, vacuumAndMopMode) ?? MovaCleaningMode.SweepingAndMopping;
+                const cleanWholeHome = isWholeHomeSelection(selectedAreas);
+                log.info(`Starting ${cleanWholeHome ? 'cleaning' : `rooms ${selectedAreas.join(', ')}`} with mode=${trackedCleanMode}, suction=${suctionLevel}`);
+                const success = !cleanWholeHome
+                    ? await cloud.cleanRooms(device.did, selectedAreas, 1, movaCleanMode, suctionLevel)
+                    : await cloud.startCleaning(device.did, movaCleanMode, suctionLevel);
+                if (success) {
+                    trackedRunMode = 1;
+                    rvc.setAttribute('RvcRunMode', 'currentMode', trackedRunMode, log);
+                    trackedOperationalState = RvcOperationalStateValue.Running;
+                    rvc.setAttribute('RvcOperationalState', 'operationalState', trackedOperationalState, log);
+                }
+            }
+            else if (newMode === 2) {
+                log.warn(`Mapping mode (2) cannot be started via Matter - use the Mova app to initiate mapping`);
+            }
+        }
+        else if (isCleanMode) {
+            log.info(`RvcCleanMode.changeToMode for ${device.name}: mode=${newMode}`);
+            if (rvcToMovaCleanMode(newMode, vacuumAndMopMode) === undefined) {
+                log.warn(`Unsupported clean mode ${newMode}`);
+                return;
+            }
+            if (trackedOperationalState === RvcOperationalStateValue.Running) {
+                log.warn(`Cannot change clean mode while actively cleaning - pause or stop first`);
+                return;
+            }
+            trackedCleanMode = newMode;
+            rvc.setAttribute('RvcCleanMode', 'currentMode', trackedCleanMode, log);
+        }
+    });
+    rvc.addCommandHandler('pause', async () => {
+        log.info(`Pause command for ${device.name}`);
+        const success = await cloud.pauseCleaning(device.did);
+        if (success) {
+            trackedRunMode = 0;
+            rvc.setAttribute('RvcRunMode', 'currentMode', trackedRunMode, log);
+            trackedOperationalState = RvcOperationalStateValue.Paused;
+            rvc.setAttribute('RvcOperationalState', 'operationalState', trackedOperationalState, log);
+        }
+    });
+    rvc.addCommandHandler('resume', async () => {
+        log.info(`Resume command for ${device.name}`);
+        const success = await cloud.resumeCleaning(device.did);
+        if (success) {
+            trackedRunMode = 1;
+            rvc.setAttribute('RvcRunMode', 'currentMode', trackedRunMode, log);
+            trackedOperationalState = RvcOperationalStateValue.Running;
+            rvc.setAttribute('RvcOperationalState', 'operationalState', trackedOperationalState, log);
+        }
+    });
+    rvc.addCommandHandler('goHome', async () => {
+        log.info(`GoHome command for ${device.name} - stopping cleaning and returning to dock`);
+        await cloud.stopCleaning(device.did);
+        const success = await cloud.goHome(device.did);
+        if (success) {
+            trackedRunMode = 0;
+            rvc.setAttribute('RvcRunMode', 'currentMode', trackedRunMode, log);
+            trackedOperationalState = RvcOperationalStateValue.SeekingCharger;
+            rvc.setAttribute('RvcOperationalState', 'operationalState', trackedOperationalState, log);
+            rvc.setAttribute('ServiceArea', 'currentArea', null, log);
+        }
+    });
+    rvc.addCommandHandler('selectAreas', async (data) => {
+        const areas = data.request?.newAreas ?? data.newAreas;
+        const nextAreas = normalizeSelectedAreas(areas);
+        selectedAreas = nextAreas;
+        log.info(`SelectAreas command for ${device.name}: ${isWholeHomeSelection(selectedAreas) ? 'all rooms' : selectedAreas.join(', ')}`);
+        rvc.setAttribute('ServiceArea', 'selectedAreas', selectedAreas, log);
+    });
+    function updateStatus(status) {
+        const newOperationalState = getOperationalStateFromMova(status.state, status.status);
+        if (newOperationalState !== trackedOperationalState) {
+            log.info(`Operational state: ${trackedOperationalState} -> ${newOperationalState} (state=${status.state}, status=${status.status})`);
+            trackedOperationalState = newOperationalState;
+            rvc.setAttribute('RvcOperationalState', 'operationalState', trackedOperationalState, log);
+        }
+        let newRunMode = 0;
+        const definitiveDockedStatuses = [MovaStatus.Charging, MovaStatus.ChargingComplete, MovaStatus.Sleeping, MovaStatus.Standby, MovaStatus.Idle];
+        if (!definitiveDockedStatuses.includes(status.status)) {
+            const activeCleaningStates = [MovaState.Cleaning, MovaState.Mopping, MovaState.ManualCleaning, MovaState.ZonedCleaning, MovaState.SpotCleaning, MovaState.CruiseRunning];
+            const activeCleaningStatuses = [
+                MovaStatus.Sweeping,
+                MovaStatus.Mopping,
+                MovaStatus.SweepingAndMopping,
+                MovaStatus.SegmentCleaning,
+                MovaStatus.ZoneCleaning,
+                MovaStatus.SpotCleaning,
+            ];
+            if (activeCleaningStates.includes(status.state) || activeCleaningStatuses.includes(status.status)) {
+                newRunMode = 1;
+            }
+            else if (status.state === MovaState.FastMapping || status.status === MovaStatus.FastMapping) {
+                newRunMode = 2;
+            }
+        }
+        if (newRunMode !== trackedRunMode) {
+            log.info(`Run mode: ${trackedRunMode} -> ${newRunMode} (state=${status.state}, status=${status.status})`);
+            trackedRunMode = newRunMode;
+            rvc.setAttribute('RvcRunMode', 'currentMode', trackedRunMode, log);
+        }
+        const newError = getOperationalErrorFromMova(status.errorCode);
+        if (newError !== trackedError) {
+            trackedError = newError;
+            const errorStateId = trackedError ?? 0;
+            rvc.setAttribute('RvcOperationalState', 'operationalError', { errorStateId }, log);
+        }
+        if (status.battery > 0) {
+            try {
+                rvc.setAttribute('PowerSource', 'batPercentRemaining', status.battery * 2, log);
+                let chargeState = BatChargeState.Unknown;
+                const isCharging = status.state === MovaState.Charging || status.status === MovaStatus.Charging;
+                const isChargingComplete = status.status === MovaStatus.ChargingComplete;
+                if (isCharging || isChargingComplete) {
+                    chargeState = status.battery >= 100 ? BatChargeState.IsAtFullCharge : BatChargeState.IsCharging;
+                }
+                else if ((status.state === MovaState.Idle || status.state === MovaState.Dormant || status.state === MovaState.Sleeping) && status.battery >= 100) {
+                    chargeState = BatChargeState.IsAtFullCharge;
+                }
+                else {
+                    chargeState = BatChargeState.IsNotCharging;
+                }
+                rvc.setAttribute('PowerSource', 'batChargeState', chargeState, log);
+                log.debug(`Battery: ${status.battery}%, state: ${status.state}, status: ${status.status}, chargeState: ${chargeState}`);
+            }
+            catch {
+            }
+        }
+        if (status.cleaningMode !== undefined) {
+            const newCleanMode = movaToRvcCleanMode(status.cleaningMode);
+            if (newCleanMode !== trackedCleanMode) {
+                trackedCleanMode = newCleanMode;
+                rvc.setAttribute('RvcCleanMode', 'currentMode', trackedCleanMode, log);
+            }
+        }
+        else if (trackedCleanMode === undefined) {
+            trackedCleanMode = 0;
+            rvc.setAttribute('RvcCleanMode', 'currentMode', trackedCleanMode, log);
+        }
+        try {
+            rvc.setAttribute('ServiceArea', 'currentArea', status.currentArea ?? null, log);
+        }
+        catch {
+        }
+    }
+    function updateRooms(newRooms) {
+        if (newRooms.length === 0) {
+            return;
+        }
+        log.info(`Updating ServiceArea with ${newRooms.length} rooms: ${newRooms.map((r) => r.name).join(', ')}`);
+        const newSupportedAreas = newRooms.map((room) => ({
+            areaId: room.id,
+            mapId: null,
+            areaInfo: {
+                locationInfo: {
+                    locationName: room.name,
+                    floorNumber: room.floorId ?? null,
+                    areaType: ServiceAreaType.Room,
+                },
+                landmarkInfo: null,
+            },
+        }));
+        supportedAreaIds = newSupportedAreas.map((area) => area.areaId);
+        if (selectedAreas.length > 0) {
+            selectedAreas = selectedAreas.filter((areaId) => supportedAreaIds.includes(areaId));
+        }
+        else {
+            selectedAreas = [...supportedAreaIds];
+        }
+        try {
+            rvc.setAttribute('ServiceArea', 'supportedAreas', newSupportedAreas, log);
+            rvc.setAttribute('ServiceArea', 'selectedAreas', selectedAreas, log);
+            log.info(`ServiceArea updated successfully with ${newRooms.length} rooms`);
+        }
+        catch (error) {
+            log.error(`Failed to update ServiceArea: ${error}`);
+        }
+    }
+    try {
+        await platform.registerDevice(rvc);
+        log.info(`Registered ${device.name} as Matter RVC device with full cluster support`);
+        rvc.setAttribute('RvcOperationalState', 'operationalState', initialOperationalState, log);
+        log.info(`Set initial operational state to ${initialOperationalState} (0=Stopped, 1=Running, 2=Paused, 3=Error, 64=SeekingCharger, 65=Charging, 66=Docked)`);
+        rvc.setAttribute('RvcRunMode', 'currentMode', initialRunMode, log);
+        log.info(`Set initial run mode to ${initialRunMode} (0=Idle, 1=Cleaning, 2=Mapping)`);
+        rvc.setAttribute('RvcCleanMode', 'currentMode', trackedCleanMode, log);
+        log.info(`Set initial clean mode to ${trackedCleanMode} (0=Vacuum, 1=Vacuum&Mop, 2=MopOnly)`);
+        const initialError = initialStatus ? getOperationalErrorFromMova(initialStatus.errorCode) : null;
+        rvc.setAttribute('RvcOperationalState', 'operationalError', { errorStateId: initialError ?? 0 }, log);
+        if (initialStatus) {
+            updateStatus(initialStatus);
+        }
+        return {
+            did: device.did,
+            name: device.name,
+            model: device.model,
+            device: rvc,
+            updateStatus,
+            updateRooms,
+        };
+    }
+    catch (error) {
+        log.error(`Failed to register device ${device.name}: ${error}`);
+        return null;
+    }
+}

package/dist/movaCloud.d.ts

@@ -0,0 +1,54 @@
+import { AnsiLogger } from 'matterbridge/logger';
+import { type AuthResult, type MovaDevice, type DeviceStatus, type MovaCountry, type RoomInfo, MovaFanSpeed, MovaCleaningMode } from './types.js';
+export declare class MovaCloudProtocol {
+    private log;
+    private session;
+    private mqttClients;
+    private messageId;
+    private pendingRequests;
+    private deviceStatusCallbacks;
+    private deviceOwnerIds;
+    private deviceModels;
+    private deviceBindDomains;
+    private loginCredentials;
+    private isRefreshing;
+    constructor(log: AnsiLogger);
+    private ensureValidToken;
+    private refreshToken;
+    login(username: string, password: string, country: MovaCountry): Promise<AuthResult>;
+    private apiCall;
+    getDevices(): Promise<MovaDevice[]>;
+    getDeviceProperties(did: string): Promise<DeviceStatus | null>;
+    getRoomInfo(did: string): Promise<RoomInfo[]>;
+    private decodeMapPayload;
+    private decodeRismPayload;
+    private parseRoomsFromMapData;
+    private static readonly ROOM_TYPE_NAMES;
+    private parseSegInf;
+    tryFetchMapOnStartup(did: string): Promise<boolean>;
+    private fetchMapFromCloudStorage;
+    connectMqtt(device: MovaDevice): Promise<boolean>;
+    private requestMapDataViaMqtt;
+    private handleMqttMessage;
+    private roomUpdateCallbacks;
+    onRoomUpdate(did: string, callback: (rooms: RoomInfo[]) => void): void;
+    private cachedRooms;
+    private cachedStatus;
+    getCachedRooms(did: string): RoomInfo[];
+    private parseStatusFromMqtt;
+    sendCommand(did: string, method: string, params?: unknown[]): Promise<unknown>;
+    private sendCloudCommand;
+    onDeviceStatus(did: string, callback: (status: DeviceStatus) => void): void;
+    private confirmCommandSuccess;
+    startCleaning(did: string, cleaningMode?: MovaCleaningMode, fanSpeed?: MovaFanSpeed, confirm?: boolean): Promise<boolean>;
+    stopCleaning(did: string, confirm?: boolean): Promise<boolean>;
+    pauseCleaning(did: string, confirm?: boolean): Promise<boolean>;
+    resumeCleaning(did: string, confirm?: boolean): Promise<boolean>;
+    goHome(did: string, confirm?: boolean): Promise<boolean>;
+    locate(did: string): Promise<boolean>;
+    cleanRooms(did: string, roomIds: number[], repeat?: number, cleaningMode?: MovaCleaningMode, fanSpeed?: MovaFanSpeed): Promise<boolean>;
+    setCleaningMode(did: string, cleaningMode: MovaCleaningMode): Promise<void>;
+    private roomWaterLevelForCleaningMode;
+    setSuctionLevel(did: string, fanSpeed: MovaFanSpeed): Promise<void>;
+    disconnect(): Promise<void>;
+}