@cecnic1989/homebridge-roborock-mower 0.1.1 → 0.2.1

package/README.md

@@ -9,15 +9,31 @@
 
 Homebridge plugin for Roborock RockMow robot lawn mowers. Exposes your mower to Apple Home.
 
-> **Early development.** The plugin installs and loads, but does not yet talk to any mower. Device support is in progress.
+> **Early development.** Status sensors and battery work (tested on a RockMow Z1 / X120H). Controls are next.
 
 ## Features
 
-Planned:
+- **State sensors** for Home-app automations: Docked, Leaving, Mowing, Returning (each a contact sensor, live via Roborock's cloud push)
+- **Battery** level, charging state, low-battery flag
+- **Fault indicator** on every sensor when the mower reports an error
 
-- **Mower status** - mowing, docked, charging, paused, error
-- **Start / pause / return to dock** controls
-- **Battery level** and charging state
+Planned: start / pause / return-to-dock controls.
+
+## Automations
+
+Each state is a contact sensor so the Home app can trigger on it ("A Sensor Detects Something"):
+
+| Sensor | Opens when | Closes when |
+|---|---|---|
+| **Docked** | it leaves the dock | it is back on the dock (charging or charged) |
+| **Leaving** | a job starts (initializing / undocking) | it begins cutting |
+| **Mowing** | it starts cutting or driving to a zone | cutting stops |
+| **Returning** | it heads back to the dock | it reaches the dock |
+
+Example for a dock inside a garage: *Leaving opens → open garage*, *Mowing opens → close garage*, *Returning opens → open garage*, *Docked closes → close garage*.
+Note: the mower starts driving ~1.5 s after "Leaving" opens, so for the outbound trip pair it with a time-based automation on the mowing schedule if the door needs longer.
+
+Sensors flip only after a state holds for `sensorDebounceSeconds` (default 3 s); faults and battery update immediately. While the cloud connection is down, sensors show as inactive rather than stale.
 
 ## Requirements
 
@@ -31,26 +47,22 @@ Homebridge UI: **Plugins** → search `@cecnic1989/homebridge-roborock-mower`.
 
 ## Configuration
 
-Minimal config:
+1. Homebridge UI → **Plugins** → **Roborock Mower** → **Settings**.
+2. Enter your Roborock account email and press **Send code**.
+3. Enter the verification code Roborock emails you and press **Verify & save**.
+4. Restart Homebridge.
 
-```json
-{
-  "platforms": [
-    {
-      "platform": "RoborockMower",
-      "name": "Roborock Mower"
-    }
-  ]
-}
-```
+Sign-in stores the cloud token in `<homebridge storage>/roborock-mower/session.json` (owner-only permissions); treat it like a password. Use **Sign out** in the settings page to remove it.
 
-Everything else is optional:
+Optional fields:
 
 | Field | Default | Description |
 |---|---|---|
-| `pollInterval` | `60` | How often to check the mower, in seconds (min 15, max 3600) |
-
-The easiest way to set all of this is the Homebridge UI's settings form for the plugin, which lists every option with descriptions.
+| `exposeDocked`, `exposeLeaving`, `exposeMowing`, `exposeReturning` | `true` | Which state sensors to create |
+| `exposeBattery` | `true` | Battery service |
+| `faultIndicator` | `true` | Set StatusFault on the sensors when the mower reports an error |
+| `sensorDebounceSeconds` | `3` | How long a state must hold before its sensor flips (0–60) |
+| `pollInterval` | `3600` | Cloud re-sync interval in seconds (min 900). Live state comes by push; Roborock rate-limits this call, so keep it high |
 
 ## Support
 

package/config.schema.json

@@ -3,27 +3,82 @@
   "pluginType": "platform",
   "singular": true,
   "strictValidation": false,
+  "customUi": true,
   "headerDisplay": "Homebridge plugin for Roborock RockMow robot lawn mowers.",
   "schema": {
     "type": "object",
     "properties": {
-      "name": {
-        "title": "Name",
-        "type": "string",
-        "default": "Roborock Mower"
-      },
       "pollInterval": {
-        "title": "Poll Interval (seconds)",
+        "title": "Cloud refresh interval (seconds)",
+        "type": "integer",
+        "default": 3600,
+        "minimum": 900,
+        "maximum": 86400,
+        "description": "Live state arrives by push; this only re-syncs with the Roborock cloud as a safety net. Roborock limits this call, keep it at an hour or more."
+      },
+      "exposeDocked": {
+        "title": "Docked sensor",
+        "type": "boolean",
+        "default": true
+      },
+      "exposeLeaving": {
+        "title": "Leaving sensor",
+        "type": "boolean",
+        "default": true
+      },
+      "exposeMowing": {
+        "title": "Mowing sensor",
+        "type": "boolean",
+        "default": true
+      },
+      "exposeReturning": {
+        "title": "Returning sensor",
+        "type": "boolean",
+        "default": true
+      },
+      "exposeBattery": {
+        "title": "Battery",
+        "type": "boolean",
+        "default": true
+      },
+      "faultIndicator": {
+        "title": "Fault indicator",
+        "type": "boolean",
+        "default": true
+      },
+      "sensorDebounceSeconds": {
+        "title": "Sensor debounce (seconds)",
         "type": "integer",
-        "default": 60,
-        "minimum": 15,
-        "maximum": 3600,
-        "description": "How often to poll mower status"
+        "default": 3,
+        "minimum": 0,
+        "maximum": 60,
+        "description": "How long a state must hold before its sensor flips. Faults and battery are reported immediately."
       }
     }
   },
   "layout": [
-    "name",
-    "pollInterval"
+    {
+      "type": "fieldset",
+      "title": "HomeKit sensors",
+      "expandable": false,
+      "items": [
+        "exposeDocked",
+        "exposeLeaving",
+        "exposeMowing",
+        "exposeReturning",
+        "exposeBattery",
+        "faultIndicator",
+        "sensorDebounceSeconds"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "pollInterval"
+      ]
+    }
   ]
 }

package/dist/mower/accessory.d.ts

@@ -0,0 +1,37 @@
+import type { API, Logging, PlatformAccessory } from 'homebridge';
+import type { DerivedState } from './state.js';
+export interface SensorOptions {
+    docked: boolean;
+    leaving: boolean;
+    mowing: boolean;
+    returning: boolean;
+    battery: boolean;
+    faultIndicator: boolean;
+    debounceSeconds: number;
+}
+export interface DeviceInformation {
+    model: string;
+    serial?: string;
+    firmware?: string;
+}
+type Hap = Pick<API['hap'], 'Service' | 'Characteristic'>;
+export declare class MowerAccessory {
+    private readonly hap;
+    readonly accessory: PlatformAccessory;
+    private readonly log;
+    private readonly options;
+    private readonly sensors;
+    private readonly battery?;
+    private readonly applied;
+    private readonly pending;
+    private last;
+    constructor(hap: Hap, accessory: PlatformAccessory, log: Logging, options: SensorOptions);
+    setInformation(info: DeviceInformation): void;
+    update(state: DerivedState): void;
+    setOnline(online: boolean): void;
+    private schedule;
+    private apply;
+    private pushFault;
+    private pushBattery;
+}
+export {};

package/dist/mower/accessory.js

@@ -0,0 +1,134 @@
+const SENSOR_LABELS = { docked: 'Docked', leaving: 'Leaving', mowing: 'Mowing', returning: 'Returning' };
+const SENSOR_KEYS = Object.keys(SENSOR_LABELS);
+// Home-app automations trigger on "opens"/"closes". Docked closes when the mower is home;
+// the activity sensors open when their activity starts, so "Leaving opens → open the garage" reads naturally.
+function contactValue(key, active, c) {
+    const detected = c.ContactSensorState.CONTACT_DETECTED;
+    const notDetected = c.ContactSensorState.CONTACT_NOT_DETECTED;
+    if (key === 'docked') {
+        return active ? detected : notDetected;
+    }
+    return active ? notDetected : detected;
+}
+export class MowerAccessory {
+    hap;
+    accessory;
+    log;
+    options;
+    sensors = new Map();
+    battery;
+    applied = new Map();
+    pending = new Map();
+    last = {};
+    constructor(hap, accessory, log, options) {
+        this.hap = hap;
+        this.accessory = accessory;
+        this.log = log;
+        this.options = options;
+        const { Service, Characteristic } = hap;
+        if (!accessory.getService(Service.AccessoryInformation)) {
+            accessory.addService(Service.AccessoryInformation);
+        }
+        for (const key of SENSOR_KEYS) {
+            const existing = accessory.getServiceById(Service.ContactSensor, key);
+            if (!options[key]) {
+                if (existing) {
+                    accessory.removeService(existing);
+                }
+                continue;
+            }
+            const name = `${accessory.displayName} ${SENSOR_LABELS[key]}`;
+            const service = existing ?? accessory.addService(Service.ContactSensor, name, key);
+            service.setCharacteristic(Characteristic.Name, name);
+            service.setCharacteristic(Characteristic.ConfiguredName, name);
+            this.sensors.set(key, service);
+        }
+        const existingBattery = accessory.getService(Service.Battery);
+        if (options.battery) {
+            this.battery = existingBattery ?? accessory.addService(Service.Battery, `${accessory.displayName} Battery`);
+        }
+        else if (existingBattery) {
+            accessory.removeService(existingBattery);
+        }
+    }
+    setInformation(info) {
+        const { Service, Characteristic } = this.hap;
+        this.accessory.getService(Service.AccessoryInformation)
+            ?.setCharacteristic(Characteristic.Manufacturer, 'Roborock')
+            .setCharacteristic(Characteristic.Model, info.model)
+            .setCharacteristic(Characteristic.SerialNumber, info.serial ?? this.accessory.UUID)
+            .setCharacteristic(Characteristic.FirmwareRevision, info.firmware ?? '0');
+    }
+    update(state) {
+        for (const key of this.sensors.keys()) {
+            this.schedule(key, state[key]);
+        }
+        this.pushFault(state.fault);
+        this.pushBattery(state);
+    }
+    setOnline(online) {
+        for (const service of this.sensors.values()) {
+            service.updateCharacteristic(this.hap.Characteristic.StatusActive, online);
+        }
+    }
+    // Activity flags must hold for debounceSeconds before HomeKit sees them; the first value is applied immediately.
+    schedule(key, value) {
+        const pending = this.pending.get(key);
+        if (this.applied.get(key) === value) {
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pending.delete(key);
+            }
+            return;
+        }
+        if (pending?.value === value) {
+            return;
+        }
+        if (pending) {
+            clearTimeout(pending.timer);
+        }
+        if (!this.applied.has(key) || this.options.debounceSeconds <= 0) {
+            this.apply(key, value);
+            return;
+        }
+        const timer = setTimeout(() => {
+            this.pending.delete(key);
+            this.apply(key, value);
+        }, this.options.debounceSeconds * 1000);
+        this.pending.set(key, { value, timer });
+    }
+    apply(key, value) {
+        this.applied.set(key, value);
+        this.sensors.get(key)?.updateCharacteristic(this.hap.Characteristic.ContactSensorState, contactValue(key, value, this.hap.Characteristic));
+        this.log.debug(`${this.accessory.displayName}: ${SENSOR_LABELS[key]} ${value ? 'on' : 'off'}`);
+    }
+    pushFault(fault) {
+        if (!this.options.faultIndicator || this.last.fault === fault) {
+            return;
+        }
+        this.last.fault = fault;
+        const c = this.hap.Characteristic;
+        for (const service of this.sensors.values()) {
+            service.updateCharacteristic(c.StatusFault, fault ? c.StatusFault.GENERAL_FAULT : c.StatusFault.NO_FAULT);
+        }
+    }
+    pushBattery(state) {
+        if (!this.battery) {
+            return;
+        }
+        const c = this.hap.Characteristic;
+        if (state.battery !== undefined && state.battery !== this.last.battery) {
+            this.last.battery = state.battery;
+            this.battery.updateCharacteristic(c.BatteryLevel, state.battery);
+        }
+        if (state.lowBattery !== this.last.lowBattery) {
+            this.last.lowBattery = state.lowBattery;
+            this.battery.updateCharacteristic(c.StatusLowBattery, state.lowBattery ? c.StatusLowBattery.BATTERY_LEVEL_LOW : c.StatusLowBattery.BATTERY_LEVEL_NORMAL);
+        }
+        if (state.charging !== this.last.charging) {
+            this.last.charging = state.charging;
+            this.battery.updateCharacteristic(c.ChargingState, state.charging ? c.ChargingState.CHARGING : c.ChargingState.NOT_CHARGING);
+        }
+    }
+}
+//# sourceMappingURL=accessory.js.map

package/dist/mower/accessory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessory.js","sourceRoot":"","sources":["../../src/mower/accessory.ts"],"names":[],"mappings":"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"}

package/dist/mower/state.d.ts

@@ -0,0 +1,29 @@
+export declare const DPS: {
+    readonly ERROR_CODE: 120;
+    readonly BATTERY: 121;
+    readonly MOW_TYPE: 122;
+    readonly MOW_STATE: 123;
+    readonly CHARGE_STATE: 127;
+    readonly DOCK_STATE: 128;
+    readonly CHARGE_TYPE: 129;
+    readonly MOW_START_TYPE: 132;
+    readonly MOW_PROGRESS: 139;
+    readonly OFF_DOCK_NO_TASK_STATUS: 143;
+};
+export declare const MOW_STATE_NAMES: Record<number, string>;
+export interface DerivedState {
+    docked: boolean;
+    leaving: boolean;
+    mowing: boolean;
+    returning: boolean;
+    charging: boolean;
+    paused: boolean;
+    fault: boolean;
+    battery?: number;
+    lowBattery: boolean;
+    mowState?: number;
+    errorCode: number;
+}
+export type Dps = Record<number, unknown>;
+export declare function deriveMowerState(dps: Dps): DerivedState;
+export declare function describeMowState(code: number | undefined): string;

package/dist/mower/state.js

@@ -0,0 +1,73 @@
+// DPS ids and state codes from python-roborock (RoborockMowerDataProtocol / RoborockMowerStateCode),
+// cross-checked against a RockMow a282 capture (test/fixtures/dps-sequence.json).
+export const DPS = {
+    ERROR_CODE: 120,
+    BATTERY: 121,
+    MOW_TYPE: 122,
+    MOW_STATE: 123,
+    CHARGE_STATE: 127,
+    DOCK_STATE: 128,
+    CHARGE_TYPE: 129,
+    MOW_START_TYPE: 132,
+    MOW_PROGRESS: 139,
+    OFF_DOCK_NO_TASK_STATUS: 143,
+};
+export const MOW_STATE_NAMES = {
+    0: 'idle',
+    1: 'map_initializing', 2: 'map_undocking', 3: 'map_undock_fault', 4: 'map_locating', 5: 'map_prepare_boundary',
+    6: 'map_prepare_island', 7: 'map_prepare_path', 8: 'map_boundary', 9: 'map_island', 10: 'map_path',
+    11: 'map_boundary_auto', 12: 'map_erasing', 13: 'map_save', 14: 'map_wait', 15: 'map_recoverable_fault',
+    16: 'map_fault', 17: 'map_emergency_stop', 18: 'map_waiting_fault',
+    51: 'mow_initializing', 52: 'mow_undocking', 53: 'mow_locating', 54: 'mow_adjust_cutter', 55: 'mow_zig_zag',
+    56: 'mow_edge', 57: 'mow_goto', 58: 'mow_suspend', 59: 'mow_recoverable_fault', 60: 'mow_fault',
+    61: 'mow_docked_rainfall', 62: 'mow_docked_do_not_disturb', 63: 'mow_docked_low_battery', 64: 'mow_wait',
+    65: 'mow_prepare_remote', 66: 'mow_remote', 67: 'mow_emergency_stop', 68: 'mow_docked_manual', 69: 'mow_dock_fault',
+    70: 'mow_remote_undocking', 71: 'mow_to_dock_initializing', 72: 'mow_to_dock_locating', 73: 'mow_to_dock_recoverable_fault',
+    74: 'mow_to_dock_fault', 75: 'mow_to_dock_emergency_stop', 76: 'mow_to_dock_charging', 77: 'mow_to_dock_charge_completed',
+    101: 'free', 102: 'free_initializing', 103: 'free_locating', 104: 'free_docked_manual', 105: 'free_docked_mow_end',
+    106: 'free_docked_plan_end', 107: 'free_emergency_stop', 108: 'free_recoverable_fault', 109: 'free_fault',
+    151: 'charge_charging', 152: 'charge_completed', 153: 'charge_waiting', 154: 'charge_fault',
+};
+const LEAVING_STATES = new Set([51, 52, 53, 54]);
+const MOWING_STATES = new Set([55, 56, 57, 64, 65, 66, 70]);
+const RETURNING_STATES = new Set([71, 72, 73, 74, 75]);
+// Bare idle (0) is deliberately not here: the mower reports 0 off the dock between a task ending and 143 being set.
+const DOCKED_STATES = new Set([61, 62, 63, 68, 76, 77, 104, 105, 106, 151, 152, 153]);
+const CHARGING_STATES = new Set([76, 151]);
+const PAUSED_STATES = new Set([17, 58, 67, 75, 107]);
+const FAULT_STATES = new Set([3, 15, 16, 59, 60, 69, 73, 74, 108, 109, 154]);
+const CHARGE_STATE_ON_DOCK = new Set([1, 2, 3]); // charging, completed, waiting
+const LOW_BATTERY_PERCENT = 20;
+function num(value) {
+    const n = typeof value === 'number' ? value : Number(value);
+    return value === undefined || value === null || Number.isNaN(n) ? undefined : n;
+}
+export function deriveMowerState(dps) {
+    const mowState = num(dps[DPS.MOW_STATE]);
+    const chargeState = num(dps[DPS.CHARGE_STATE]);
+    const offDock = num(dps[DPS.OFF_DOCK_NO_TASK_STATUS]) ?? 0;
+    const battery = num(dps[DPS.BATTERY]);
+    const errorCode = num(dps[DPS.ERROR_CODE]) ?? 0;
+    const state = mowState ?? -1;
+    const docked = (chargeState !== undefined && CHARGE_STATE_ON_DOCK.has(chargeState)) || DOCKED_STATES.has(state);
+    return {
+        docked,
+        leaving: LEAVING_STATES.has(state),
+        mowing: MOWING_STATES.has(state),
+        returning: !docked && (RETURNING_STATES.has(state) || offDock !== 0),
+        charging: chargeState === 1 || CHARGING_STATES.has(state),
+        paused: PAUSED_STATES.has(state),
+        fault: errorCode !== 0 || FAULT_STATES.has(state),
+        battery,
+        lowBattery: battery !== undefined && battery <= LOW_BATTERY_PERCENT,
+        mowState,
+        errorCode,
+    };
+}
+export function describeMowState(code) {
+    if (code === undefined) {
+        return 'unknown';
+    }
+    return MOW_STATE_NAMES[code] ?? `unknown(${code})`;
+}
+//# sourceMappingURL=state.js.map

package/dist/mower/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/mower/state.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,kFAAkF;AAClF,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,UAAU,EAAE,GAAG;IACf,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,SAAS,EAAE,GAAG;IACd,YAAY,EAAE,GAAG;IACjB,UAAU,EAAE,GAAG;IACf,WAAW,EAAE,GAAG;IAChB,cAAc,EAAE,GAAG;IACnB,YAAY,EAAE,GAAG;IACjB,uBAAuB,EAAE,GAAG;CACpB,CAAC;AAEX,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,sBAAsB;IAC9G,CAAC,EAAE,oBAAoB,EAAE,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,UAAU;IAClG,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,uBAAuB;IACvG,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE,mBAAmB;IAClE,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,aAAa;IAC3G,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,uBAAuB,EAAE,EAAE,EAAE,WAAW;IAC/F,EAAE,EAAE,qBAAqB,EAAE,EAAE,EAAE,2BAA2B,EAAE,EAAE,EAAE,wBAAwB,EAAE,EAAE,EAAE,UAAU;IACxG,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,oBAAoB,EAAE,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,gBAAgB;IACnH,EAAE,EAAE,sBAAsB,EAAE,EAAE,EAAE,0BAA0B,EAAE,EAAE,EAAE,sBAAsB,EAAE,EAAE,EAAE,+BAA+B;IAC3H,EAAE,EAAE,mBAAmB,EAAE,EAAE,EAAE,4BAA4B,EAAE,EAAE,EAAE,sBAAsB,EAAE,EAAE,EAAE,8BAA8B;IACzH,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,EAAE,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,oBAAoB,EAAE,GAAG,EAAE,qBAAqB;IAClH,GAAG,EAAE,sBAAsB,EAAE,GAAG,EAAE,qBAAqB,EAAE,GAAG,EAAE,wBAAwB,EAAE,GAAG,EAAE,YAAY;IACzG,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,cAAc;CAC5F,CAAC;AAEF,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AACjD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAC5D,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AACvD,oHAAoH;AACpH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AACtF,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;AAC3C,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;AACrD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7E,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,+BAA+B;AAChF,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAkB/B,SAAS,GAAG,CAAC,KAAc;IACzB,MAAM,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAQ;IACvC,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,QAAQ,IAAI,CAAC,CAAC,CAAC;IAE7B,MAAM,MAAM,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,oBAAoB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAChH,OAAO;QACL,MAAM;QACN,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC;QAClC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;QAChC,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC;QACpE,QAAQ,EAAE,WAAW,KAAK,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC;QACzD,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;QAChC,KAAK,EAAE,SAAS,KAAK,CAAC,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC;QACjD,OAAO;QACP,UAAU,EAAE,OAAO,KAAK,SAAS,IAAI,OAAO,IAAI,mBAAmB;QACnE,QAAQ;QACR,SAAS;KACV,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAwB;IACvD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,WAAW,IAAI,GAAG,CAAC;AACrD,CAAC"}

package/dist/platform.d.ts

@@ -1,16 +1,46 @@
 import type { API, Characteristic, DynamicPlatformPlugin, Logging, PlatformAccessory, PlatformConfig, Service } from 'homebridge';
+import type mqtt from 'mqtt';
+import type { StoredSession } from './roborock/types.js';
 export interface RoborockMowerConfig extends PlatformConfig {
     pollInterval?: number;
+    exposeDocked?: boolean;
+    exposeLeaving?: boolean;
+    exposeMowing?: boolean;
+    exposeReturning?: boolean;
+    exposeBattery?: boolean;
+    faultIndicator?: boolean;
+    sensorDebounceSeconds?: number;
+}
+export interface PlatformDeps {
+    fetch?: typeof globalThis.fetch;
+    readSession?: (storagePath: string) => Promise<StoredSession | undefined>;
+    connectMqtt?: typeof mqtt.connect;
+    now?: () => number;
 }
 export declare class RoborockMowerPlatform implements DynamicPlatformPlugin {
     readonly log: Logging;
     readonly config: PlatformConfig;
     readonly api: API;
+    private readonly deps;
     readonly Service: typeof Service;
     readonly Characteristic: typeof Characteristic;
     readonly accessories: Map<string, PlatformAccessory>;
     readonly pluginConfig: RoborockMowerConfig;
-    constructor(log: Logging, config: PlatformConfig, api: API);
+    private webApi?;
+    private mqtt?;
+    private homeId?;
+    private session?;
+    private reconcileTimer?;
+    private readonly mowers;
+    constructor(log: Logging, config: PlatformConfig, api: API, deps?: PlatformDeps);
     configureAccessory(accessory: PlatformAccessory): void;
-    private discoverDevices;
+    private sensorOptions;
+    private start;
+    private stop;
+    private syncMowers;
+    private applyDps;
+    private startMqtt;
+    private pollSeconds;
+    private scheduleReconcile;
+    private reconcile;
 }