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

package/docs/index.html

@@ -373,6 +373,24 @@ Without this step, then you will receive the following error when the swichbot p
 </ul>
 </li>
 </ul>
+<h2 id="matter-platform" class="tsd-anchor-link">Matter Platform<a href="#matter-platform" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><h3 id="batched-refresh-and-api-load-control" class="tsd-anchor-link">Batched refresh and API load control<a href="#batched-refresh-and-api-load-control" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>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 <code>options</code>:</p>
+<ul>
+<li><code>matterBatchEnabled</code> (boolean, default true): enable/disable platform-level batched refresh. Devices with a per-device <code>refreshRate</code> still run their own timers.</li>
+<li><code>matterBatchRefreshRate</code> (number, seconds): batch interval (falls back to <code>options.refreshRate</code>, then 300 if not set).</li>
+<li><code>matterBatchConcurrency</code> (number): limit of parallel OpenAPI status calls during a batch (default 5).</li>
+<li><code>matterBatchJitter</code> (number, seconds): random startup delay before the first batch to reduce synchronized spikes.</li>
+</ul>
+<p>Device-level override:</p>
+<ul>
+<li>If a device sets <code>refreshRate</code> in its config, it uses a per-device timer and is excluded from the platform batch.</li>
+</ul>
+<p>Reliability and rate-limiting:</p>
+<ul>
+<li>Each device status call retries with exponential backoff on non-success responses.</li>
+<li>After exhausting retries, the device enters a short cooldown before being retried; cooldowns are persisted across restarts.</li>
+<li>The batch worklist is randomized every cycle to further distribute API load.</li>
+</ul>
+<p>These controls keep API usage smooth and predictable while preserving per-device control when needed.</p>
 <h2 id="switchbot-apis" class="tsd-anchor-link">SwitchBot APIs<a href="#switchbot-apis" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
 <li><a href="https://github.com/OpenWonderLabs/node-switchbot">OpenWonderLabs/node-switchbot</a>
 <ul>
@@ -386,4 +404,4 @@ Without this step, then you will receive the following error when the swichbot p
 <li><a href="https://www.facebook.com/SwitchBotRobot/">Facebook @SwitchBotRobot</a></li>
 <li><a href="https://twitter.com/switchbot">Twitter @SwitchBot</a></li>
 </ul>
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#switchbothomebridge-switchbot"><span>@switchbot/homebridge-<wbr/>switchbot</span></a><ul><li><a href="#installation"><span>Installation</span></a></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#if-using-openapi-connection"><span>If using <wbr/>Open<wbr/>API <wbr/>Connection</span></a></li><li><a href="#if-using-ble-connection"><span>If using <wbr/>BLE <wbr/>Connection</span></a></li></ul></li><li><a href="#troubleshooting"><span>Troubleshooting</span></a></li><li><ul><li><a href="#if-using-linux-raspberry-pi-os"><span>If using <wbr/>Linux / <wbr/>Raspberry <wbr/>Pi <wbr/>OS</span></a></li><li><a href="#if-using-macos"><span>If using <wbr/>Mac<wbr/>OS</span></a></li></ul></li><li><a href="#supported-switchbot-devices"><span>Supported <wbr/>Switch<wbr/>Bot <wbr/>Devices</span></a></li><li><a href="#supported-ir-devices"><span>Supported <wbr/>IR <wbr/>Devices</span></a></li><li><ul><li><a href="#all-ir-devices-require-switchbot-hub-2-switchbot-hub-3-or-hub-mini"><span>(<wbr/>All <wbr/>IR <wbr/>Devices require <wbr/>Switch<wbr/>Bot <wbr/>Hub 2, <wbr/>Switch<wbr/>Bot <wbr/>Hub 3, or <wbr/>Hub <wbr/>Mini)</span></a></li></ul></li><li><a href="#switchbot-apis"><span>Switch<wbr/>Bot <wbr/>AP<wbr/>Is</span></a></li><li><a href="#community"><span>Community</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">@switchbot/homebridge-switchbot</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#switchbothomebridge-switchbot"><span>@switchbot/homebridge-<wbr/>switchbot</span></a><ul><li><a href="#installation"><span>Installation</span></a></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#if-using-openapi-connection"><span>If using <wbr/>Open<wbr/>API <wbr/>Connection</span></a></li><li><a href="#if-using-ble-connection"><span>If using <wbr/>BLE <wbr/>Connection</span></a></li></ul></li><li><a href="#troubleshooting"><span>Troubleshooting</span></a></li><li><ul><li><a href="#if-using-linux-raspberry-pi-os"><span>If using <wbr/>Linux / <wbr/>Raspberry <wbr/>Pi <wbr/>OS</span></a></li><li><a href="#if-using-macos"><span>If using <wbr/>Mac<wbr/>OS</span></a></li></ul></li><li><a href="#supported-switchbot-devices"><span>Supported <wbr/>Switch<wbr/>Bot <wbr/>Devices</span></a></li><li><a href="#supported-ir-devices"><span>Supported <wbr/>IR <wbr/>Devices</span></a></li><li><ul><li><a href="#all-ir-devices-require-switchbot-hub-2-switchbot-hub-3-or-hub-mini"><span>(<wbr/>All <wbr/>IR <wbr/>Devices require <wbr/>Switch<wbr/>Bot <wbr/>Hub 2, <wbr/>Switch<wbr/>Bot <wbr/>Hub 3, or <wbr/>Hub <wbr/>Mini)</span></a></li></ul></li><li><a href="#matter-platform"><span>Matter <wbr/>Platform</span></a></li><li><ul><li><a href="#batched-refresh-and-api-load-control"><span>Batched refresh and <wbr/>API load control</span></a></li></ul></li><li><a href="#switchbot-apis"><span>Switch<wbr/>Bot <wbr/>AP<wbr/>Is</span></a></li><li><a href="#community"><span>Community</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html">@switchbot/homebridge-switchbot</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>

package/docs/variables/default.html

@@ -1 +1 @@
-<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>default | @switchbot/homebridge-switchbot</title><meta name="description" content="Documentation for @switchbot/homebridge-switchbot"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">@switchbot/homebridge-switchbot</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">default</a></li></ul><h1>Variable default</h1></div><div class="tsd-signature"><span class="tsd-kind-variable">default</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">api</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">API</span><span class="tsd-signature-symbol">)</span> <span class="tsd-signature-symbol">=&gt;</span> <span class="tsd-signature-type">void</span></div><div class="tsd-type-declaration"><h4>Type Declaration</h4><ul class="tsd-parameters"><li class="tsd-parameter-signature"><ul class="tsd-signatures"><li class="tsd-signature" id="__type"><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">api</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">API</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">void</span></li><li class="tsd-description"><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">api</span>: <span class="tsd-signature-type">API</span></span></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4></li></ul></li></ul></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/OpenWonderLabs/homebridge-switchbot/blob/7ef570a83c474096eb9ab1d68acdbf9681c65204/src/index.ts#L13">index.ts:13</a></li></ul></aside></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">@switchbot/homebridge-switchbot</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>
+<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>default | @switchbot/homebridge-switchbot</title><meta name="description" content="Documentation for @switchbot/homebridge-switchbot"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">@switchbot/homebridge-switchbot</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">default</a></li></ul><h1>Variable default</h1></div><div class="tsd-signature"><span class="tsd-kind-variable">default</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">api</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">API</span><span class="tsd-signature-symbol">)</span> <span class="tsd-signature-symbol">=&gt;</span> <span class="tsd-signature-type">void</span></div><div class="tsd-type-declaration"><h4>Type Declaration</h4><ul class="tsd-parameters"><li class="tsd-parameter-signature"><ul class="tsd-signatures"><li class="tsd-signature" id="__type"><span class="tsd-signature-symbol">(</span><span class="tsd-kind-parameter">api</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">API</span><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">void</span></li><li class="tsd-description"><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">api</span>: <span class="tsd-signature-type">API</span></span></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">void</span></h4></li></ul></li></ul></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/OpenWonderLabs/homebridge-switchbot/blob/43cdf5e76dd30e281e39cf30d76122f4297960db/src/index.ts#L13">index.ts:13</a></li></ul></aside></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">@switchbot/homebridge-switchbot</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>

package/package.json

@@ -2,7 +2,7 @@
   "name": "@switchbot/homebridge-switchbot",
   "displayName": "SwitchBot",
   "type": "module",
-  "version": "5.0.0-beta.30",
+  "version": "5.0.0-beta.31",
   "description": "The SwitchBot plugin allows you to access your SwitchBot device(s) from HomeKit.",
   "author": "SwitchBot <support@wondertechlabs.com> (https://github.com/SwitchBot)",
   "contributors": [
@@ -94,7 +94,7 @@
     "@types/node": "^24.9.2",
     "@types/semver": "^7.7.1",
     "@types/source-map-support": "^0.5.10",
-    "@vitest/coverage-v8": "^4.0.5",
+    "@vitest/coverage-v8": "^4.0.6",
     "eslint": "^9.38.0",
     "eslint-plugin-format": "^1.0.2",
     "eslint-plugin-import": "^2.32.0",
@@ -105,7 +105,7 @@
     "ts-node": "^10.9.2",
     "typedoc": "^0.28.14",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.5"
+    "vitest": "^4.0.6"
   },
   "directories": {
     "doc": "docs"

package/src/platform-matter.ts

@@ -12,6 +12,9 @@ import type { bodyChange, device } from 'node-switchbot'
 
 import type { devicesConfig, SwitchBotPlatformConfig } from './settings.js'
 
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
 import asyncmqtt from 'async-mqtt'
 import { SwitchBotBLE, SwitchBotOpenAPI } from 'node-switchbot'
 
@@ -61,6 +64,9 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
   private platformRefreshTimer?: NodeJS.Timeout
   // Device status cache from last refresh
   private deviceStatusCache: Map<string, any> = new Map()
+  // Backoff cooldowns persisted across restarts: normalized deviceId -> nextAllowedAt(ms)
+  private backoffCooldowns: Map<string, number> = new Map()
+  private backoffFilePath?: string
   // Devices that have explicit per-device refresh timers (normalized deviceId)
   private perDeviceRefreshSet: Set<string> = new Set()
   // BLE event handlers keyed by device MAC (formatted)
@@ -279,6 +285,22 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
           } catch (e: any) {
             this.debugLog(`Failed to stop BLE scanning: ${e?.message ?? e}`)
           }
+
+          // Persist backoff cooldowns to disk
+          try {
+            if (this.backoffFilePath) {
+              const obj: Record<string, number> = {}
+              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: any) {
+            this.debugLog(`Failed to save backoff state: ${e?.message ?? e}`)
+          }
         } catch (e: any) {
           this.debugLog('Shutdown cleanup failed: %s', e?.message ?? e)
         }
@@ -314,6 +336,31 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     } catch (e: any) {
       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 as Record<string, unknown>)) {
+              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: any) {
+          this.debugLog(`Failed to load backoff state: ${e?.message ?? e}`)
+        }
+      }
+    } catch (e: any) {
+      this.debugLog(`Failed to initialize backoff persistence: ${e?.message ?? e}`)
+    }
   }
 
   /**
@@ -1006,6 +1053,12 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
           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: any) {
               this.debugLog(`Per-device refresh failed for ${dev.deviceId}: ${e?.message ?? e}`)
@@ -1315,12 +1368,37 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     // Helper to safely call instance methods or fallback to api.matter.updateAccessoryState
     const safeUpdate = async (cluster: string, attributes: Record<string, unknown>, methodName?: string) => {
       try {
-        if (instance && methodName && typeof instance[methodName] === 'function') {
+        // 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 as any).PowerSource)
+          ? (this.api.matter.clusterNames as any).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 as any).clusters) {
+          const declared = (instance as any).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 as any)[methodName] === 'function') {
           // prefer device-specific update helpers when available
-          await instance[methodName](...(Object.values(attributes)))
-        } else if (instance && typeof instance.updateState === 'function') {
+          await (instance as any)[methodName](...(Object.values(attributes)))
+        } else if (!isPowerSourceCluster && instance && typeof (instance as any).updateState === 'function') {
           // some accessories expose updateState that accepts cluster and attributes
-          await instance.updateState(cluster, attributes)
+          await (instance as any).updateState(cluster, attributes)
         } else {
           try {
             await this.api.matter.updateAccessoryState(uuidLocal, cluster, attributes)
@@ -1784,7 +1862,7 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     }
 
     // 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')
@@ -2133,11 +2211,25 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     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: any) {
+        this.debugLog(`Initial batch refresh failed: ${e?.message ?? e}`)
+      }
+      this.platformRefreshTimer = setInterval(async () => {
+        await this.batchRefreshAllDevices()
+      }, intervalMs)
+    }, jitterMs)
   }
 
   /**
@@ -2160,7 +2252,10 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
           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 })
         }
       }
@@ -2176,6 +2271,11 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
 
     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 {
@@ -2217,6 +2317,13 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         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
   }
 

package/src/settings.ts

@@ -64,6 +64,8 @@ export interface options {
   // Matter platform batch refresh options
   matterBatchRefreshRate?: number
   matterBatchConcurrency?: number
+  matterBatchEnabled?: boolean
+  matterBatchJitter?: number
 };
 
 export type devicesConfig = botConfig | relaySwitch1Config | relaySwitch1PMConfig | meterConfig | meterProConfig | indoorOutdoorSensorConfig | humidifierConfig | curtainConfig | blindTiltConfig | contactConfig | motionConfig | waterDetectorConfig | plugConfig | colorBulbConfig | stripLightConfig | ceilingLightConfig | lockConfig | hubConfig

package/src/test/hap/platform-hap.logging.test.ts

@@ -0,0 +1,36 @@
+/* eslint-disable import/first */
+import { describe, expect, it, vi } from 'vitest'
+// Mock modules used by the HAP platform constructor to avoid requiring a real Homebridge API
+vi.mock('fakegato-history', () => ({ default: () => ({}) }))
+vi.mock('homebridge-lib/EveHomeKitTypes', () => ({ EveHomeKitTypes: class { constructor() {} } }))
+
+import { SwitchBotHAPPlatform } from '../../platform-hap.js'
+import { makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * Verifies that HAP platform debug logger includes the accessory displayName
+ * when loading an accessory from the cache.
+ */
+describe('platform-hap logging', () => {
+  it('prints accessory name when loading HAP cached accessory', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    const accessory: any = { displayName: 'Test HAP Device' }
+    await (platform as any).configureAccessory(accessory)
+
+    // Allow async logger to flush
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    const calls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = calls.some(args => String(args[0]).includes('Loading accessory from cache: Test HAP Device'))
+    expect(hasLine).toBe(true)
+  })
+})

package/src/test/hap/platform-hap.test.ts

@@ -0,0 +1,70 @@
+/* eslint-disable import/first */
+import { describe, expect, it, vi } from 'vitest'
+// Mock modules used by the HAP platform constructor to avoid requiring a real Homebridge API
+vi.mock('fakegato-history', () => ({ default: () => ({}) }))
+vi.mock('homebridge-lib/EveHomeKitTypes', () => ({ EveHomeKitTypes: class { constructor() {} } }))
+
+import { SwitchBotHAPPlatform } from '../../platform-hap.js'
+import { makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * High-level smoke tests for the HAP platform to ensure it initializes,
+ * subscribes to lifecycle events, and handles cached accessories.
+ */
+describe('platform-hap (smoke)', () => {
+  it('initializes and subscribes to didFinishLaunching', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    // Enable debug so debug* logs print via our shared logger
+    // Construct the platform (smoke)
+    new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    // Should register didFinishLaunching handler
+    expect(api.on).toHaveBeenCalled()
+    const calledWithDL = (api.on as any).mock.calls.some((args: any[]) => args[0] === 'didFinishLaunching' && typeof args[1] === 'function')
+    expect(calledWithDL).toBe(true)
+
+    // Should log effective platform logging at startup
+    const debugCalls = (log.debug as any).mock.calls as Array<string[]>
+    const hasStartupLine = debugCalls.some(args => String(args[0]).includes('[SwitchBot HAP] effective platformLogging='))
+    expect(hasStartupLine).toBe(true)
+
+    // Missing credentials results in a debug error log
+    // Allow async platform logger to flush
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const errorCalls = (log.error as any).mock.calls as Array<string[]>
+    const hasMissingCreds = errorCalls.some(args => String(args[0]).includes('Missing SwitchBot API credentials'))
+    expect(hasMissingCreds).toBe(true)
+  })
+
+  it('adds cached accessories via configureAccessory', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    const accessory: any = { displayName: 'Cached Device' }
+    await (platform as any).configureAccessory(accessory)
+
+    // Should be stored in platform.accessories
+    expect(Array.isArray((platform as any).accessories)).toBe(true)
+    expect((platform as any).accessories.length).toBe(1)
+
+    // And should log the cache load message including device name
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const infoCalls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = infoCalls.some(args => String(args[0]).includes('Loading accessory from cache: Cached Device'))
+    expect(hasLine).toBe(true)
+  })
+})

package/src/test/{devices-matter → matter/devices-matter}/baseMatterAccessory.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { BaseMatterAccessory } from '../../devices-matter/BaseMatterAccessory.js'
+import { BaseMatterAccessory } from '../../../devices-matter/BaseMatterAccessory.js'
 
 // Minimal concrete subclass for testing
 class TestAccessory extends BaseMatterAccessory {

package/src/test/{platform-matter.additional.test.ts → matter/platform-matter.additional.test.ts}

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { SwitchBotMatterPlatform } from '../platform-matter.js'
-import { makeApiStub, makeLogStub } from './helpers/platform-fixtures.js'
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
 
 describe('additional platform-matter mapping tests', () => {
   it('parses OpenAPI color strings and triggers an update', async () => {

package/src/test/{platform-matter.bleparse.test.ts → matter/platform-matter.bleparse.test.ts}

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { SwitchBotMatterPlatform } from '../platform-matter.js'
-import { makeApiStub, makeLogStub } from './helpers/platform-fixtures.js'
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
 
 describe('platform-matter BLE advertisement parser', () => {
   it('parses extended serviceData fields correctly', () => {

package/src/test/{platform-matter.cleanup.test.ts → matter/platform-matter.cleanup.test.ts}

@@ -1,8 +1,8 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { SwitchBotMatterPlatform } from '../platform-matter.js'
-import { formatDeviceIdAsMac } from '../utils.js'
-import { makeApiStub, makeLogStub } from './helpers/platform-fixtures.js'
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { formatDeviceIdAsMac } from '../../utils.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
 
 describe('platform-matter lifecycle cleanup', () => {
   it('clearDeviceResources removes timers, instances and BLE handler entries', async () => {

package/src/test/{platform-matter.keepstale.test.ts → matter/platform-matter.keepstale.test.ts}

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { SwitchBotMatterPlatform } from '../platform-matter.js'
-import { makeApiStub, makeLogStub } from './helpers/platform-fixtures.js'
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
 
 describe('keepStaleAccessories config flag behavior', () => {
   it('keeps previously-registered accessories when options.keepStaleAccessories=true', async () => {

package/src/test/matter/platform-matter.logging.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * Verifies that debug logger formats arguments so that accessory displayName
+ * appears in the output for cached accessory load logs.
+ */
+describe('platform-matter logging', () => {
+  it('prints accessory name when loading cached Matter accessory', async () => {
+    const api: any = makeApiStub()
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotMatterPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+    } as any, api)
+
+    // Simulate Homebridge restoring a cached Matter accessory
+    const acc: any = { uuid: 'uuid-TEST', displayName: 'Test Device', context: { deviceId: 'DEV1' } }
+    ;(platform as any).configureMatterAccessory(acc)
+    // debugLog is async and gated; yield to allow the logger to run
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    // In 'debug' mode, debugLog uses log.info with a [DEBUG] prefix
+    // Ensure one of the info calls contains the message with the device name
+    const calls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = calls.some(args => String(args[0]).includes('Loading cached Matter accessory: Test Device'))
+    expect(hasLine).toBe(true)
+  })
+})

package/src/test/{platform-matter.mapping.test.ts → matter/platform-matter.mapping.test.ts}

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { SwitchBotMatterPlatform } from '../platform-matter.js'
-import { makeApiStub, makeLogStub } from './helpers/platform-fixtures.js'
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
 
 describe('platform-matter mapping helper', () => {
   it('prefers accessory instance update methods for battery and falls back to api.matter.updateAccessoryState', async () => {

package/src/test/{platform-matter.openapi-mapping.test.ts → matter/platform-matter.openapi-mapping.test.ts}

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { SwitchBotMatterPlatform } from '../platform-matter.js'
-import { makeApiStub, makeLogStub } from './helpers/platform-fixtures.js'
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
 
 describe('platform-matter OpenAPI -> Matter mapping', () => {
   it('maps light OpenAPI status (on/off, brightness, color, battery) to accessory instance helpers', async () => {

package/src/test/{platform-matter.test.ts → matter/platform-matter.test.ts}

@@ -1,8 +1,8 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { SwitchBotMatterPlatform } from '../platform-matter.js'
-import { PLATFORM_NAME, PLUGIN_NAME } from '../settings.js'
-import { makeApiStub, makeLogStub } from './helpers/platform-fixtures.js'
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { PLATFORM_NAME, PLUGIN_NAME } from '../../settings.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
 
 describe('platform-matter discovered devices', () => {
   it('uses discovered devices and registers them (platform + robotic)', async () => {

package/src/test/{platform-matter.unregister.test.ts → matter/platform-matter.unregister.test.ts}

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
 
-import { SwitchBotMatterPlatform } from '../platform-matter.js'
-import { makeApiStub, makeLogStub } from './helpers/platform-fixtures.js'
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
 
 describe('removeDisabledAccessories and unregister edge cases', () => {
   it('clears resources and unregisters accessory even with invalid timer and non-MAC deviceId', async () => {