@switchbot/homebridge-switchbot 5.0.0-beta.17 → 5.0.0-beta.19

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/)
 
+## [Unreleased]
+
+### What's Changed
+- Matter platform: register only devices discovered via the SwitchBot OpenAPI by default. Per-device config overrides (by deviceId) are correctly merged into discovered devices.
+- Add `options.allowConfigOnlyDevices` (boolean) to opt-in to registering devices that exist only in config (not discovered).
+- Add unit tests for per-device merging and config-only behavior.
+
 ## [4.3.1](https://github.com/OpenWonderLabs/homebridge-switchbot/releases/tag/v4.3.1) (2025-03-04)
 
 # *No New Releases During Lent*

package/config.schema.json

@@ -13077,6 +13077,11 @@
               }
             ]
           },
+          "allowConfigOnlyDevices": {
+            "title": "Allow Config-only Devices",
+            "type": "boolean",
+            "description": "If true, devices declared in options.devices that are not discovered by the SwitchBot OpenAPI will still be included (config-only devices). Default: false."
+          },
           "allowInvalidCharacters": {
             "title": "Allow Invalid Characters",
             "type": "boolean",
@@ -14822,8 +14827,18 @@
           "key": "options.pushRate",
           "description": "<em class='primary-text'>Specifies the interval, in seconds, between pushes to the SwitchBot API.</em>"
         },
-        "options.logging",
-        "options.allowInvalidCharacters"
+        {
+          "key": "options.logging",
+          "description": "<em class='primary-text'>Specifies the logging level for the plugin. Default: info.</em>"
+        },
+        {
+          "key": "options.allowConfigOnlyDevices",
+          "description": "<em class='primary-text'>If true, devices declared in options.devices that are not discovered by the SwitchBot OpenAPI will still be included (config-only devices). Default: false.</em>"
+        },
+        {
+          "key": "options.allowInvalidCharacters",
+          "description": "<em class='primary-text'>Allows device names with characters that are normally invalid in HomeKit. Use with caution, as this may lead to unexpected behavior.</em>"
+        }
       ]
     }
   ]

package/dist/platform-matter.d.ts

@@ -1,12 +1,6 @@
 import type { API, DynamicPlatformPlugin, Logging, SerializedMatterAccessory } from 'homebridge';
 import type { bodyChange, device } from 'node-switchbot';
 import type { SwitchBotPlatformConfig } from './settings.js';
-/**
- * MatterPlatform
- * Demonstrates all available Matter device types in Homebridge
- *
- * Organized by official Matter Specification v1.4.1 categories
- */
 export declare class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     readonly log: Logging;
     readonly config: SwitchBotPlatformConfig;
@@ -15,6 +9,8 @@ export declare class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     private switchBotAPI?;
     private switchBotBLE?;
     private discoveredDevices;
+    private accessoryInstances;
+    private refreshTimers;
     private bleEventHandler;
     private platformLogging?;
     infoLog: (...args: any[]) => void;
@@ -68,6 +64,12 @@ export declare class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
      * Returns null when serviceData is falsy or parsing fails.
      */
     private parseAdvertisementForDevice;
+    /**
+     * Central helper to apply a SwitchBot status object to a Matter accessory.
+     * Tries to call accessory instance update helpers when available, otherwise
+     * falls back to calling api.matter.updateAccessoryState directly.
+     */
+    private applyStatusToAccessory;
     /**
      * Required for DynamicPlatformPlugin
      * Called when homebridge restores cached accessories from disk at startup

package/dist/platform-matter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-matter.d.ts","sourceRoot":"","sources":["../src/platform-matter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,GAAG,EACH,qBAAqB,EACrB,OAAO,EAEP,yBAAyB,EAC1B,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAExD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AA8B5D;;;;;GAKG;AACH,qBAAa,uBAAwB,YAAW,qBAAqB;aA8BjD,GAAG,EAAE,OAAO;aACZ,MAAM,EAAE,uBAAuB;aAC/B,GAAG,EAAE,GAAG;IA1B1B,SAAgB,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAY;IAErF,OAAO,CAAC,YAAY,CAAC,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAC,CAAc;IAEnC,OAAO,CAAC,iBAAiB,CAAe;IAExC,OAAO,CAAC,eAAe,CAA8C;IAErE,OAAO,CAAC,eAAe,CAAC,CAAS;IAGjC,OAAO,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAClC,UAAU,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACrC,eAAe,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC1C,OAAO,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAClC,YAAY,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACvC,QAAQ,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACnC,aAAa,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACxC,QAAQ,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACnC,cAAc,EAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACvC,uBAAuB,EAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;gBAG9B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,uBAAuB,EAC/B,GAAG,EAAE,GAAG;IAwH1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAOvB;;;OAGG;YACW,sBAAsB;IAsCpC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;OAGG;YACW,yBAAyB;IAiXvC;;OAEG;YACW,eAAe;IAwB7B;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,SAAI,EAAE,mBAAmB,SAAO,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,GAAG,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IA0BzJ;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAwDnC;;;OAGG;IACH,kBAAkB;IAMlB;;;;;OAKG;IACH,wBAAwB,CAAC,SAAS,EAAE,yBAAyB;IAK7D;;OAEG;YACW,yBAAyB;IAwFvC;;OAEG;YACW,yBAAyB;IAqCvC;;OAEG;YACW,wBAAwB;IA8CtC;;OAEG;YACW,0BAA0B;IAsBxC;;OAEG;YACW,wBAAwB;IAsBtC;;OAEG;YACW,uBAAuB;IA0DrC;;OAEG;YACW,uBAAuB;IAkCrC;;OAEG;YACW,oBAAoB;IA4BlC;;;;;OAKG;YACW,wBAAwB;IAsBtC;;;;;;OAMG;YACW,qBAAqB;CAqBpC"}
+{"version":3,"file":"platform-matter.d.ts","sourceRoot":"","sources":["../src/platform-matter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,GAAG,EACH,qBAAqB,EACrB,OAAO,EAEP,yBAAyB,EAC1B,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAExD,OAAO,KAAK,EAAiB,uBAAuB,EAAE,MAAM,eAAe,CAAA;AA8B3E,qBAAa,uBAAwB,YAAW,qBAAqB;aAkCjD,GAAG,EAAE,OAAO;aACZ,MAAM,EAAE,uBAAuB;aAC/B,GAAG,EAAE,GAAG;IA9B1B,SAAgB,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAY;IAErF,OAAO,CAAC,YAAY,CAAC,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAC,CAAc;IAEnC,OAAO,CAAC,iBAAiB,CAAe;IAExC,OAAO,CAAC,kBAAkB,CAA8B;IAExD,OAAO,CAAC,aAAa,CAAyC;IAE9D,OAAO,CAAC,eAAe,CAA8C;IAErE,OAAO,CAAC,eAAe,CAAC,CAAS;IAGjC,OAAO,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAClC,UAAU,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACrC,eAAe,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC1C,OAAO,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAClC,YAAY,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACvC,QAAQ,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACnC,aAAa,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACxC,QAAQ,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACnC,cAAc,EAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACvC,uBAAuB,EAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;gBAG9B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,uBAAuB,EAC/B,GAAG,EAAE,GAAG;IAwH1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;OAGG;YACW,sBAAsB;IAuCpC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;OAGG;YACW,yBAAyB;IA2gBvC;;OAEG;YACW,eAAe;IAwB7B;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,SAAI,EAAE,mBAAmB,SAAO,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,GAAG,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IA0BzJ;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAwDnC;;;;OAIG;YACW,sBAAsB;IA6LpC;;;OAGG;IACH,kBAAkB;IAMlB;;;;;OAKG;IACH,wBAAwB,CAAC,SAAS,EAAE,yBAAyB;IAK7D;;OAEG;YACW,yBAAyB;IAwFvC;;OAEG;YACW,yBAAyB;IAqCvC;;OAEG;YACW,wBAAwB;IA8CtC;;OAEG;YACW,0BAA0B;IAsBxC;;OAEG;YACW,wBAAwB;IAsBtC;;OAEG;YACW,uBAAuB;IA0DrC;;OAEG;YACW,uBAAuB;IAkCrC;;OAEG;YACW,oBAAoB;IA4BlC;;;;;OAKG;YACW,wBAAwB;IAsBtC;;;;;;OAMG;YACW,qBAAqB;CAqBpC"}

package/dist/platform-matter.js

@@ -2,12 +2,6 @@ import { SwitchBotBLE, SwitchBotOpenAPI } from 'node-switchbot';
 import { ColorLightAccessory, ColorTemperatureLightAccessory, ContactSensorAccessory, DimmableLightAccessory, DoorLockAccessory, ExtendedColorLightAccessory, FanAccessory, HumiditySensorAccessory, LeakSensorAccessory, LightSensorAccessory, OccupancySensorAccessory, OnOffLightAccessory, OnOffOutletAccessory, OnOffSwitchAccessory, PowerStripAccessory, RoboticVacuumAccessory, SmokeCOAlarmAccessory, TemperatureSensorAccessory, ThermostatAccessory, VenetianBlindAccessory, WindowBlindAccessory, } from './devices-matter/index.js';
 import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js';
 import { cleanDeviceConfig, createPlatformLogger, formatDeviceIdAsMac, hs2rgb, makeBLESender, makeOpenAPISender, rgb2hs, sleep } from './utils.js';
-/**
- * MatterPlatform
- * Demonstrates all available Matter device types in Homebridge
- *
- * Organized by official Matter Specification v1.4.1 categories
- */
 export class SwitchBotMatterPlatform {
     log;
     config;
@@ -22,6 +16,10 @@ export class SwitchBotMatterPlatform {
     switchBotBLE;
     // discovered devices cache
     discoveredDevices = [];
+    // Registry of created accessory instances keyed by normalized deviceId
+    accessoryInstances = new Map();
+    // Refresh timers keyed by normalized deviceId
+    refreshTimers = new Map();
     // BLE event handlers keyed by device MAC (formatted)
     bleEventHandler = {};
     // Platform logging toggle (can be controlled via UI or config)
@@ -170,10 +168,20 @@ export class SwitchBotMatterPlatform {
      * find matching item in a2 (discovered devices) and merge them with user overrides last.
      */
     mergeByDeviceId(a1, a2) {
-        return a1.map((itm) => {
-            const matchingItem = a2.find(item => this.normalizeDeviceId(item.deviceId) === this.normalizeDeviceId(itm.deviceId));
-            return Object.assign({}, matchingItem, itm);
-        });
+        const allowConfigOnly = Boolean(this.config.options?.allowConfigOnlyDevices);
+        const result = [];
+        for (const itm of (a1 || [])) {
+            const matchingItem = (a2 || []).find(item => this.normalizeDeviceId(item.deviceId) === this.normalizeDeviceId(itm.deviceId));
+            if (matchingItem) {
+                result.push(Object.assign({}, matchingItem, itm));
+            }
+            else if (allowConfigOnly) {
+                // include config-only device as-is when explicitly allowed
+                result.push(Object.assign({}, itm));
+            }
+            // otherwise skip config-only entries
+        }
+        return result;
     }
     /**
      * Merge discovered devices with deviceConfig (per deviceType) and per-device overrides
@@ -198,7 +206,8 @@ export class SwitchBotMatterPlatform {
         // For any entries in merged (which are based on config.options.devices), ensure final per-device merges include deviceId-specific config
         const final = [];
         for (const device of merged) {
-            const deviceIdConfig = this.config.options?.devices?.[device.deviceId] || {};
+            // Find per-device config entry by deviceId (config.options.devices is an array)
+            const deviceIdConfig = (this.config.options?.devices || []).find((d) => this.normalizeDeviceId(d.deviceId) === this.normalizeDeviceId(device.deviceId)) || {};
             const deviceWithConfig = Object.assign({}, device, deviceIdConfig);
             final.push(deviceWithConfig);
         }
@@ -234,7 +243,7 @@ export class SwitchBotMatterPlatform {
         const displayName = dev.deviceName ?? dev.deviceId ?? 'SwitchBot Device';
         const serial = dev.deviceId ?? 'unknown';
         const manufacturer = 'SwitchBot';
-        const model = dev.deviceType ?? 'SwitchBot';
+        const model = dev.model ?? dev.deviceType ?? 'SwitchBot';
         const firmware = dev.firmware ?? dev.version ?? '0.0.0';
         // Helper to build a default opts object consumed by the matter device classes
         const baseOpts = {
@@ -492,6 +501,15 @@ export class SwitchBotMatterPlatform {
         const opts = Object.assign({}, baseOpts, { handlers });
         // Instantiate the device class and return its serialized accessory
         const instance = new Ctor(this.api, this.log, opts);
+        // Save instance in registry so platform can call device-specific update methods if needed
+        try {
+            if (dev?.deviceId) {
+                this.accessoryInstances.set(this.normalizeDeviceId(dev.deviceId), instance);
+            }
+        }
+        catch (e) {
+            this.debugLog('Failed to register accessory instance: %s', e?.message ?? e);
+        }
         try {
             this.infoLog(`Initialized Matter accessory: ${displayName} (type=${dev.deviceType ?? 'Unknown'}) id=${dev.deviceId}`);
         }
@@ -523,6 +541,134 @@ export class SwitchBotMatterPlatform {
                             const [h, s] = rgb2hs(r, g, b);
                             await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) });
                         }
+                        // Battery -> powerSource cluster (common mapping)
+                        if (parsed.battery !== undefined) {
+                            try {
+                                const percentage = Number(parsed.battery);
+                                const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)));
+                                let batChargeLevel = 0;
+                                if (percentage < 20) {
+                                    batChargeLevel = 2;
+                                }
+                                else if (percentage < 40) {
+                                    batChargeLevel = 1;
+                                }
+                                await this.api.matter.updateAccessoryState(uuidLocal, 'powerSource', { batPercentRemaining, batChargeLevel });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update battery state for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        // Temperature -> temperatureMeasurement
+                        if (parsed.temperature !== undefined) {
+                            try {
+                                const c = Number(parsed.temperature);
+                                const measured = Math.round(c * 100);
+                                await this.api.matter.updateAccessoryState(uuidLocal, 'temperatureMeasurement', { measuredValue: measured });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update temperature for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        // Humidity -> relativeHumidityMeasurement
+                        if (parsed.humidity !== undefined) {
+                            try {
+                                const percent = Number(parsed.humidity);
+                                const measured = Math.round(percent * 100);
+                                await this.api.matter.updateAccessoryState(uuidLocal, 'relativeHumidityMeasurement', { measuredValue: measured });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update humidity for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        // Contact / Leak -> BooleanState
+                        if (parsed.contact !== undefined || parsed.leak !== undefined) {
+                            try {
+                                // Some devices report contact as true=open; ContactSensor expects inverted value
+                                const isContactOpen = parsed.contact === undefined ? undefined : Boolean(parsed.contact);
+                                const leakDetected = parsed.leak === undefined ? undefined : Boolean(parsed.leak);
+                                if (isContactOpen !== undefined) {
+                                    // If this is a contact sensor device type, invert; otherwise set conservatively
+                                    if ((dev.deviceType || '').includes('Contact')) {
+                                        await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.BooleanState, { stateValue: !isContactOpen });
+                                    }
+                                    else {
+                                        await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.BooleanState, { stateValue: isContactOpen });
+                                    }
+                                }
+                                if (leakDetected !== undefined) {
+                                    await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.BooleanState, { stateValue: leakDetected });
+                                }
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update contact/leak for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        // Motion -> occupancy
+                        if (parsed.motion !== undefined) {
+                            try {
+                                await this.api.matter.updateAccessoryState(uuidLocal, 'occupancySensing', { occupancy: { occupied: Boolean(parsed.motion) } });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update occupancy for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        // Lock state -> doorLock
+                        if (parsed.lock !== undefined) {
+                            try {
+                                const s = String(parsed.lock).toLowerCase();
+                                let lockState = 0;
+                                if (s === 'locked' || s === '1' || s === 'true') {
+                                    lockState = 1;
+                                }
+                                else if (s === 'unlocked' || s === '0' || s === 'false') {
+                                    lockState = 2;
+                                }
+                                await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.DoorLock, { lockState });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update lock for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        // Position / Cover -> WindowCovering (convert open percent to closed*100)
+                        if (parsed.position !== undefined) {
+                            try {
+                                const openPercent = Number(parsed.position);
+                                const closedPercent = 100 - Math.max(0, Math.min(100, openPercent));
+                                const value = Math.round(closedPercent * 100);
+                                await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.WindowCovering, { currentPositionLiftPercent100ths: value, targetPositionLiftPercent100ths: value });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update cover position for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        // Fan speed -> FanControl
+                        if (parsed.fanSpeed !== undefined) {
+                            try {
+                                const percent = Number(parsed.fanSpeed);
+                                await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.FanControl, { percentSetting: percent, percentCurrent: percent });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update fan speed for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        // Robot vacuum fields (battery already handled) - update run/operational/clean modes when present
+                        if (parsed.rvcRunMode !== undefined) {
+                            try {
+                                await this.api.matter.updateAccessoryState(uuidLocal, 'rvcRunMode', { currentMode: Number(parsed.rvcRunMode) });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update rvcRunMode for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
+                        if (parsed.rvcOperationalState !== undefined) {
+                            try {
+                                await this.api.matter.updateAccessoryState(uuidLocal, 'rvcOperationalState', { operationalState: Number(parsed.rvcOperationalState) });
+                            }
+                            catch (e) {
+                                this.debugLog(`Failed to update rvcOperationalState for ${dev.deviceId}: ${e?.message ?? e}`);
+                            }
+                        }
                         // If we parsed something from serviceData prefer it and return early
                         if (serviceData) {
                             return;
@@ -544,35 +690,8 @@ export class SwitchBotMatterPlatform {
                     const respAny = response;
                     const body = respAny?.body ?? respAny;
                     const status = body?.status ?? body;
-                    // On/Off
-                    if (status?.power !== undefined) {
-                        const on = (String(status.power).toLowerCase() === 'on' || Number(status.power) === 1);
-                        await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.OnOff, { onOff: on });
-                    }
-                    // Brightness
-                    if (status?.brightness !== undefined) {
-                        const level = Math.round((Number(status.brightness) / 100) * 254);
-                        await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.LevelControl, { currentLevel: level });
-                    }
-                    // Color
-                    if (status?.color !== undefined) {
-                        const color = String(status.color);
-                        let r = 0;
-                        let g = 0;
-                        let b = 0;
-                        if (color.includes(':')) {
-                            const parts = color.split(':').map(Number);
-                            [r, g, b] = parts;
-                        }
-                        else if (color.startsWith('#')) {
-                            const hex = color.replace('#', '');
-                            r = Number.parseInt(hex.substring(0, 2), 16);
-                            g = Number.parseInt(hex.substring(2, 4), 16);
-                            b = Number.parseInt(hex.substring(4, 6), 16);
-                        }
-                        const [h, s] = rgb2hs(r, g, b);
-                        await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) });
-                    }
+                    // Use centralized mapper which prefers accessory instance update helpers
+                    await this.applyStatusToAccessory(uuidLocal, dev, status);
                 }
                 catch (e) {
                     this.debugLog(`BLE push handler failed for ${dev.deviceId}: ${e?.message ?? e}`);
@@ -582,6 +701,53 @@ export class SwitchBotMatterPlatform {
         catch (e) {
             this.debugLog(`Failed to register BLE handler for ${dev.deviceId}: ${e?.message ?? e}`);
         }
+        // Schedule periodic OpenAPI refreshes for this device (if OpenAPI is configured)
+        try {
+            const nid = this.normalizeDeviceId(dev.deviceId);
+            // Clear any existing timer for this device
+            const existing = this.refreshTimers.get(nid);
+            if (existing) {
+                clearInterval(existing);
+                this.refreshTimers.delete(nid);
+            }
+            const refreshRateSec = dev.refreshRate ?? this.config.options?.refreshRate ?? 300;
+            if (this.switchBotAPI && refreshRateSec && Number(refreshRateSec) > 0) {
+                // Immediate one-shot to populate initial state
+                ;
+                (async () => {
+                    try {
+                        const { response, statusCode } = await this.switchBotAPI.getDeviceStatus(dev.deviceId, this.config.credentials?.token, this.config.credentials?.secret);
+                        if (statusCode === 100 || statusCode === 200) {
+                            const respAny = response;
+                            const body = respAny?.body ?? respAny;
+                            const status = body?.status ?? body;
+                            await this.applyStatusToAccessory(uuid, dev, status);
+                        }
+                    }
+                    catch (e) {
+                        this.debugLog(`Initial OpenAPI refresh failed for ${dev.deviceId}: ${e?.message ?? e}`);
+                    }
+                })();
+                const timer = setInterval(async () => {
+                    try {
+                        const { response, statusCode } = await this.switchBotAPI.getDeviceStatus(dev.deviceId, this.config.credentials?.token, this.config.credentials?.secret);
+                        if (statusCode === 100 || statusCode === 200) {
+                            const respAny = response;
+                            const body = respAny?.body ?? respAny;
+                            const status = body?.status ?? body;
+                            await this.applyStatusToAccessory(uuid, dev, status);
+                        }
+                    }
+                    catch (e) {
+                        this.debugLog(`Periodic OpenAPI refresh failed for ${dev.deviceId}: ${e?.message ?? e}`);
+                    }
+                }, Number(refreshRateSec) * 1000);
+                this.refreshTimers.set(nid, timer);
+            }
+        }
+        catch (e) {
+            this.debugLog(`Failed to schedule refresh for ${dev.deviceId}: ${e?.message ?? e}`);
+        }
         return instance.toAccessory();
     }
     /**
@@ -689,6 +855,203 @@ export class SwitchBotMatterPlatform {
             return null;
         }
     }
+    /**
+     * Central helper to apply a SwitchBot status object to a Matter accessory.
+     * Tries to call accessory instance update helpers when available, otherwise
+     * falls back to calling api.matter.updateAccessoryState directly.
+     */
+    async applyStatusToAccessory(uuidLocal, dev, status) {
+        if (!status) {
+            return;
+        }
+        const instance = dev?.deviceId ? this.accessoryInstances.get(this.normalizeDeviceId(dev.deviceId)) : undefined;
+        // Helper to safely call instance methods or fallback to api.matter.updateAccessoryState
+        const safeUpdate = async (cluster, attributes, methodName) => {
+            try {
+                if (instance && methodName && typeof instance[methodName] === 'function') {
+                    // prefer device-specific update helpers when available
+                    await instance[methodName](...(Object.values(attributes)));
+                }
+                else if (instance && typeof instance.updateState === 'function') {
+                    // some accessories expose updateState that accepts cluster and attributes
+                    await instance.updateState(cluster, attributes);
+                }
+                else {
+                    await this.api.matter.updateAccessoryState(uuidLocal, cluster, attributes);
+                }
+            }
+            catch (e) {
+                this.debugLog(`safeUpdate failed for ${dev.deviceId} cluster=${cluster}: ${e?.message ?? e}`);
+            }
+        };
+        try {
+            // On/Off
+            if (status?.power !== undefined) {
+                const on = (String(status.power).toLowerCase() === 'on' || Number(status.power) === 1 || Boolean(status.power) === true);
+                await safeUpdate(this.api.matter.clusterNames.OnOff, { onOff: on }, 'updateOnOffState');
+            }
+            // Brightness
+            if (status?.brightness !== undefined) {
+                const level = Math.round((Number(status.brightness) / 100) * 254);
+                await safeUpdate(this.api.matter.clusterNames.LevelControl, { currentLevel: level }, 'updateBrightness');
+            }
+            // Color
+            if (status?.color !== undefined) {
+                const color = String(status.color);
+                let r = 0;
+                let g = 0;
+                let b = 0;
+                if (color.includes(':')) {
+                    const parts = color.split(':').map(Number);
+                    [r, g, b] = parts;
+                }
+                else if (color.startsWith('#')) {
+                    const hex = color.replace('#', '');
+                    r = Number.parseInt(hex.substring(0, 2), 16);
+                    g = Number.parseInt(hex.substring(2, 4), 16);
+                    b = Number.parseInt(hex.substring(4, 6), 16);
+                }
+                const [h, s] = rgb2hs(r, g, b);
+                await safeUpdate(this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) }, 'updateHueSaturation');
+            }
+            // Battery/powerSource
+            if (status?.battery !== undefined || status?.batt !== undefined) {
+                try {
+                    const percentage = Number(status?.battery ?? status?.batt);
+                    const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)));
+                    let batChargeLevel = 0;
+                    if (percentage < 20) {
+                        batChargeLevel = 2;
+                    }
+                    else if (percentage < 40) {
+                        batChargeLevel = 1;
+                    }
+                    await safeUpdate('powerSource', { batPercentRemaining, batChargeLevel }, 'updateBatteryPercentage');
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply battery status for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            // Temperature + thermostat
+            if (status?.temperature !== undefined || status?.temp !== undefined) {
+                try {
+                    const c = Number(status?.temperature ?? status?.temp);
+                    const measured = Math.round(c * 100);
+                    await safeUpdate('temperatureMeasurement', { measuredValue: measured }, 'updateTemperature');
+                    // Thermostat-specific mapping
+                    if (status?.targetTemp !== undefined || status?.targetTemperature !== undefined || status?.heatingSetpoint !== undefined) {
+                        const target = Number(status?.targetTemp ?? status?.targetTemperature ?? status?.heatingSetpoint);
+                        const val = Math.round(target * 100);
+                        await safeUpdate('thermostat', { occupiedHeatingSetpoint: val }, 'updateHeatingSetpoint');
+                    }
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply temperature for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            // Humidity
+            if (status?.humidity !== undefined || status?.h !== undefined) {
+                try {
+                    const percent = Number(status?.humidity ?? status?.h);
+                    const measured = Math.round(percent * 100);
+                    await safeUpdate('relativeHumidityMeasurement', { measuredValue: measured }, 'updateHumidity');
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply humidity for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            // Contact / Leak -> BooleanState
+            if (status?.contact !== undefined || status?.open !== undefined || status?.leak !== undefined || status?.water !== undefined) {
+                try {
+                    const isContactOpen = status?.contact ?? status?.open;
+                    if (isContactOpen !== undefined) {
+                        if ((dev.deviceType || '').includes('Contact')) {
+                            await safeUpdate(this.api.matter.clusterNames.BooleanState, { stateValue: !(String(isContactOpen).toLowerCase() === 'true' || Number(isContactOpen) === 1) }, 'updateContactState');
+                        }
+                        else {
+                            await safeUpdate(this.api.matter.clusterNames.BooleanState, { stateValue: (String(isContactOpen).toLowerCase() === 'true' || Number(isContactOpen) === 1) }, 'updateContactState');
+                        }
+                    }
+                    const leakDetected = status?.leak ?? status?.water;
+                    if (leakDetected !== undefined) {
+                        await safeUpdate(this.api.matter.clusterNames.BooleanState, { stateValue: Boolean(leakDetected) }, 'updateLeakState');
+                    }
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply contact/leak for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            // Motion -> occupancy
+            if (status?.motion !== undefined || status?.m !== undefined) {
+                try {
+                    const detected = Boolean(status?.motion ?? status?.m);
+                    await safeUpdate('occupancySensing', { occupancy: { occupied: detected } }, 'updateOccupancy');
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply motion for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            // Lock state
+            if (status?.lock !== undefined) {
+                try {
+                    const s = String(status.lock).toLowerCase();
+                    let lockState = 0;
+                    if (s === 'locked' || s === '1' || s === 'true') {
+                        lockState = 1;
+                    }
+                    else if (s === 'unlocked' || s === '0' || s === 'false') {
+                        lockState = 2;
+                    }
+                    await safeUpdate(this.api.matter.clusterNames.DoorLock, { lockState }, 'updateLockState');
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply lock for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            // Cover position
+            if (status?.position !== undefined || status?.percent !== undefined) {
+                try {
+                    const openPercent = Number(status?.position ?? status?.percent);
+                    const closedPercent = 100 - Math.max(0, Math.min(100, openPercent));
+                    const value = Math.round(closedPercent * 100);
+                    await safeUpdate(this.api.matter.clusterNames.WindowCovering, { currentPositionLiftPercent100ths: value, targetPositionLiftPercent100ths: value }, 'updateLiftPosition');
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply cover position for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            // Fan
+            if (status?.fanSpeed !== undefined || status?.speed !== undefined) {
+                try {
+                    const percent = Number(status?.fanSpeed ?? status?.speed);
+                    await safeUpdate(this.api.matter.clusterNames.FanControl, { percentSetting: percent, percentCurrent: percent }, 'updateFanSpeed');
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply fan speed for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            // Robot vacuum: run/operational/clean modes
+            if (status?.rvcRunMode !== undefined) {
+                try {
+                    await safeUpdate('rvcRunMode', { currentMode: Number(status.rvcRunMode) }, 'updateRunMode');
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply rvcRunMode for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+            if (status?.rvcOperationalState !== undefined) {
+                try {
+                    await safeUpdate('rvcOperationalState', { operationalState: Number(status.rvcOperationalState) }, 'updateOperationalState');
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply rvcOperationalState for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
+        }
+        catch (e) {
+            this.debugLog(`applyStatusToAccessory top-level failure for ${dev.deviceId}: ${e?.message ?? e}`);
+        }
+    }
     /**
      * Required for DynamicPlatformPlugin
      * Called when homebridge restores cached accessories from disk at startup