@switchbot/homebridge-switchbot 5.0.0-beta.30 → 5.0.0-beta.32

package/README.md

@@ -52,16 +52,13 @@
 ## Troubleshooting
 
 - ### If using Linux / Raspberry Pi OS
-
   1. `bluetoothctl` must be installed on the device, otherwise it cannot communicate via Bluetooth. Enable it with `sudo bluetoothctl power on`.
 
   2. If errors occur, while enabling it, restart the process:
-
      - `rfkill block bluetooth`
      - `rfkill unblock bluetooth`
 
   3. Also make sure, that the computer can discover the SwitchBot device:
-
      - `sudo bluetoothctl`
      - `scan on`
 
@@ -218,6 +215,29 @@
     - Supports Fan Device Type
   - Allows for On/Off Controls
 
+## Matter Platform
+
+### Batched refresh and API load control
+
+By default, the Matter platform uses a single batched refresh to update device status. You can tune or override this behavior with the following options under `options`:
+
+- `matterBatchEnabled` (boolean, default true): enable/disable platform-level batched refresh. Devices with a per-device `refreshRate` still run their own timers.
+- `matterBatchRefreshRate` (number, seconds): batch interval (falls back to `options.refreshRate`, then 300 if not set).
+- `matterBatchConcurrency` (number): limit of parallel OpenAPI status calls during a batch (default 5).
+- `matterBatchJitter` (number, seconds): random startup delay before the first batch to reduce synchronized spikes.
+
+Device-level override:
+
+- If a device sets `refreshRate` in its config, it uses a per-device timer and is excluded from the platform batch.
+
+Reliability and rate-limiting:
+
+- Each device status call retries with exponential backoff on non-success responses.
+- After exhausting retries, the device enters a short cooldown before being retried; cooldowns are persisted across restarts.
+- The batch worklist is randomized every cycle to further distribute API load.
+
+These controls keep API usage smooth and predictable while preserving per-device control when needed.
+
 ## SwitchBot APIs
 
 - [OpenWonderLabs/node-switchbot](https://github.com/OpenWonderLabs/node-switchbot)

package/config.schema.json

@@ -52,6 +52,18 @@
             "placeholder": 5,
             "description": "Maximum number of parallel OpenAPI status calls during a batch refresh."
           },
+          "matterBatchEnabled": {
+            "title": "Enable Matter Batch Refresh",
+            "type": "boolean",
+            "default": true,
+            "description": "When true (default), the platform runs a single batched refresh timer. Devices with a per-device refreshRate still use their own timers."
+          },
+          "matterBatchJitter": {
+            "title": "Matter Batch Start Jitter (seconds)",
+            "type": "number",
+            "placeholder": 30,
+            "description": "Random delay added before starting the platform-level batch timer to reduce synchronized spikes."
+          },
           "devices": {
             "type": "array",
             "items": {
@@ -14834,6 +14846,22 @@
         "options.mqttPubOptions",
         "options.maxRetries",
         "options.delayBetweenRetries",
+        {
+          "key": "options.matterBatchRefreshRate",
+          "description": "<em class='primary-text'>Specifies the interval, in seconds, for retrieving the latest device status from the SwitchBot API when batching Matter requests.</em>"
+        },
+        {
+          "key": "options.matterBatchConcurrency",
+          "description": "<em class='primary-text'>Specifies the maximum number of Matter requests to process concurrently.</em>"
+        },
+        {
+          "key": "options.matterBatchEnabled",
+          "description": "<em class='primary-text'>If true, enables batching of Matter requests to optimize performance. Default: false.</em>"
+        },
+        {
+          "key": "options.matterBatchJitter",
+          "description": "<em class='primary-text'>Specifies the maximum random jitter, in seconds, to add to the batch processing interval to prevent synchronization issues. Default: 0.</em>"
+        },
         {
           "key": "options.refreshRate",
           "description": "<em class='primary-text'>Specifies the interval, in seconds, for retrieving the latest device status from the SwitchBot API.</em>"

package/dist/platform-matter.d.ts

@@ -13,6 +13,8 @@ export declare class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     private refreshTimers;
     private platformRefreshTimer?;
     private deviceStatusCache;
+    private backoffCooldowns;
+    private backoffFilePath?;
     private perDeviceRefreshSet;
     private bleEventHandler;
     private mqttClient;

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

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

package/dist/platform-matter.js

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import asyncmqtt from 'async-mqtt';
 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';
@@ -25,6 +27,9 @@ export class SwitchBotMatterPlatform {
     platformRefreshTimer;
     // Device status cache from last refresh
     deviceStatusCache = new Map();
+    // Backoff cooldowns persisted across restarts: normalized deviceId -> nextAllowedAt(ms)
+    backoffCooldowns = new Map();
+    backoffFilePath;
     // Devices that have explicit per-device refresh timers (normalized deviceId)
     perDeviceRefreshSet = new Set();
     // BLE event handlers keyed by device MAC (formatted)
@@ -236,6 +241,22 @@ export class SwitchBotMatterPlatform {
                     catch (e) {
                         this.debugLog(`Failed to stop BLE scanning: ${e?.message ?? e}`);
                     }
+                    // Persist backoff cooldowns to disk
+                    try {
+                        if (this.backoffFilePath) {
+                            const obj = {};
+                            for (const [k, v] of this.backoffCooldowns.entries()) {
+                                if (Number.isFinite(v)) {
+                                    obj[k] = v;
+                                }
+                            }
+                            writeFileSync(this.backoffFilePath, JSON.stringify(obj, null, 2));
+                            this.debugLog(`Saved ${Object.keys(obj).length} backoff cooldown entries`);
+                        }
+                    }
+                    catch (e) {
+                        this.debugLog(`Failed to save backoff state: ${e?.message ?? e}`);
+                    }
                 }
                 catch (e) {
                     this.debugLog('Shutdown cleanup failed: %s', e?.message ?? e);
@@ -268,6 +289,32 @@ export class SwitchBotMatterPlatform {
         catch (e) {
             this.errorLog(`Setup Webhook, Error Message: ${e?.message ?? e}, Submit Bugs Here: ` + 'https://tinyurl.com/SwitchBotBug');
         }
+        // Initialize backoff persistence file path and load any saved cooldowns
+        try {
+            const storagePath = this.api.user.storagePath();
+            this.backoffFilePath = join(storagePath, `${PLUGIN_NAME.replace('@', '').replace('/', '-')}-matter-backoff.json`);
+            if (existsSync(this.backoffFilePath)) {
+                try {
+                    const raw = readFileSync(this.backoffFilePath, 'utf8');
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed === 'object') {
+                        for (const [k, v] of Object.entries(parsed)) {
+                            const ts = Number(v);
+                            if (Number.isFinite(ts)) {
+                                this.backoffCooldowns.set(String(k), ts);
+                            }
+                        }
+                        this.debugLog(`Loaded ${this.backoffCooldowns.size} backoff cooldown entries`);
+                    }
+                }
+                catch (e) {
+                    this.debugLog(`Failed to load backoff state: ${e?.message ?? e}`);
+                }
+            }
+        }
+        catch (e) {
+            this.debugLog(`Failed to initialize backoff persistence: ${e?.message ?? e}`);
+        }
     }
     /**
      * Normalize a deviceId for matching (uppercase alphanumerics only)
@@ -946,6 +993,12 @@ export class SwitchBotMatterPlatform {
                     this.perDeviceRefreshSet.add(nid);
                     const timer = setInterval(async () => {
                         try {
+                            // Skip if device is under cooldown
+                            const now = Date.now();
+                            const nextAllowed = this.backoffCooldowns.get(nid) ?? 0;
+                            if (now < nextAllowed) {
+                                return;
+                            }
                             await this.refreshSingleDeviceWithRetry(dev);
                         }
                         catch (e) {
@@ -1234,11 +1287,35 @@ export class SwitchBotMatterPlatform {
         // Helper to safely call instance methods or fallback to api.matter.updateAccessoryState
         const safeUpdate = async (cluster, attributes, methodName) => {
             try {
+                // Special-case: powerSource cluster is optional on many devices (e.g., Curtains/Blinds).
+                // To avoid noisy Matter server errors ("Behavior ID powerSource does not exist"),
+                // always use the direct updateAccessoryState path wrapped in a guard for this cluster,
+                // even when an accessory instance is present.
+                const powerClusterName = (this.api.matter?.clusterNames && this.api.matter.clusterNames.PowerSource)
+                    ? this.api.matter.clusterNames.PowerSource
+                    : 'powerSource';
+                const isPowerSourceCluster = cluster === powerClusterName || cluster === 'powerSource';
+                // If the accessory instance declares supported clusters, skip updates for clusters
+                // not present to avoid triggering Matter server errors and logs.
+                let clusterSupported = true;
+                if (instance && instance.clusters) {
+                    const declared = instance.clusters;
+                    if (Array.isArray(declared)) {
+                        clusterSupported = declared.includes(cluster);
+                    }
+                    else if (typeof declared === 'object') {
+                        clusterSupported = Object.prototype.hasOwnProperty.call(declared, cluster);
+                    }
+                    if (!clusterSupported) {
+                        this.debugLog(`Cluster ${cluster} not declared on accessory for ${dev.deviceId}, skipping update`);
+                        return;
+                    }
+                }
                 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') {
+                else if (!isPowerSourceCluster && instance && typeof instance.updateState === 'function') {
                     // some accessories expose updateState that accepts cluster and attributes
                     await instance.updateState(cluster, attributes);
                 }
@@ -1708,7 +1785,7 @@ export class SwitchBotMatterPlatform {
             return;
         }
         // If no discovered devices are available, do not register example/demo accessories.
-        this.infoLog('No discovered SwitchBot devices found; not registering example Matter accessories by default.');
+        this.infoLog('No discovered SwitchBot devices found.');
         this.debugLog('═'.repeat(80));
         this.debugLog('Finished registering Matter accessories');
         this.debugLog('═'.repeat(80));
@@ -2009,10 +2086,26 @@ export class SwitchBotMatterPlatform {
         if (this.platformRefreshTimer) {
             return;
         }
-        this.debugLog(`Starting platform-level refresh timer with interval ${refreshRateSec}s`);
-        this.platformRefreshTimer = setInterval(async () => {
-            await this.batchRefreshAllDevices();
-        }, Number(refreshRateSec) * 1000);
+        // Respect user toggle
+        if (this.config.options?.matterBatchEnabled === false) {
+            this.infoLog('Matter batch refresh is disabled by configuration');
+            return;
+        }
+        const jitterSec = Number(this.config.options?.matterBatchJitter ?? 0);
+        const intervalMs = Number(refreshRateSec) * 1000;
+        const jitterMs = Number.isFinite(jitterSec) && jitterSec > 0 ? Math.floor(Math.random() * jitterSec * 1000) : 0;
+        // Start after optional jitter, then schedule recurring interval
+        setTimeout(async () => {
+            try {
+                await this.batchRefreshAllDevices();
+            }
+            catch (e) {
+                this.debugLog(`Initial batch refresh failed: ${e?.message ?? e}`);
+            }
+            this.platformRefreshTimer = setInterval(async () => {
+                await this.batchRefreshAllDevices();
+            }, intervalMs);
+        }, jitterMs);
     }
     /**
      * Batch refresh all devices - still makes individual API calls but batches them together
@@ -2032,7 +2125,10 @@ export class SwitchBotMatterPlatform {
                     continue;
                 }
                 const dev = this.discoveredDevices.find(d => this.normalizeDeviceId(d.deviceId) === nid);
-                if (dev && !this.perDeviceRefreshSet.has(nid)) {
+                // Skip devices with per-device timers and those in cooldown
+                const now = Date.now();
+                const nextAllowed = this.backoffCooldowns.get(nid) ?? 0;
+                if (dev && !this.perDeviceRefreshSet.has(nid) && now >= nextAllowed) {
                     devicesToRefresh.push({ uuid, dev });
                 }
             }
@@ -2046,6 +2142,11 @@ export class SwitchBotMatterPlatform {
             return;
         }
         this.debugLog(`Refreshing ${devicesToRefresh.length} devices in parallel batch`);
+        // Randomize order to reduce synchronized spikes
+        for (let i = devicesToRefresh.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [devicesToRefresh[i], devicesToRefresh[j]] = [devicesToRefresh[j], devicesToRefresh[i]];
+        }
         const concurrency = Number(this.config.options?.matterBatchConcurrency ?? 5);
         await this.runWithConcurrency(devicesToRefresh, async ({ uuid, dev }) => {
             try {
@@ -2088,6 +2189,14 @@ export class SwitchBotMatterPlatform {
                 await sleep(delay);
             }
         }
+        // Set a cooldown after exhausting retries to avoid hammering problematic devices
+        try {
+            const nid = this.normalizeDeviceId(deviceId);
+            const cooldownMs = Math.max(60_000, baseDelayMs * (2 ** retries) * 10);
+            this.backoffCooldowns.set(nid, Date.now() + cooldownMs);
+            this.debugLog(`Applied cooldown for ${deviceId}: ${Math.round(cooldownMs / 1000)}s`);
+        }
+        catch { }
         return null;
     }
     /** Simple concurrency limiter for an array of items */