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

package/docs/index.html

@@ -60,7 +60,7 @@
 </ul>
 <h2 id="troubleshooting" class="tsd-anchor-link">Troubleshooting<a href="#troubleshooting" 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>
-<h3 id="if-using-linux--raspberry-pi-os" class="tsd-anchor-link">If using Linux / Raspberry Pi OS<a href="#if-using-linux--raspberry-pi-os" 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><ol>
+<h3 id="if-using-linux-raspberry-pi-os" class="tsd-anchor-link">If using Linux / Raspberry Pi OS<a href="#if-using-linux-raspberry-pi-os" 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><ol>
 <li>
 <p><code>bluetoothctl</code> must be installed on the device, otherwise it cannot communicate via Bluetooth. Enable it with <code>sudo bluetoothctl power on</code>.</p>
 </li>
@@ -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/5f4f60a189b81b96820279b84f818e8ce02fc32b/src/index.ts#L12">index.ts:12</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.3",
+  "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": [
@@ -55,7 +55,7 @@
   "icon": "https://raw.githubusercontent.com/OpenWonderLabs/homebridge-switchbot/latest/branding/icon.png",
   "engineStrict": true,
   "engines": {
-    "homebridge": "^2.0.0-beta.38",
+    "homebridge": "^2.0.0-beta.39",
     "node": "^20 || ^22 || ^24"
   },
   "scripts": {
@@ -81,31 +81,31 @@
     "@homebridge/plugin-ui-utils": "^2.1.0",
     "async-mqtt": "^2.6.3",
     "fakegato-history": "^0.6.7",
-    "homebridge-lib": "^7.1.7",
+    "homebridge-lib": "^7.1.12",
     "node-switchbot": "^3.6.0",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^5.2.1",
+    "@antfu/eslint-config": "^6.2.0",
     "@types/aes-js": "^3.1.4",
     "@types/debug": "^4.1.12",
     "@types/fs-extra": "^11.0.4",
     "@types/mdast": "^4.0.4",
-    "@types/node": "^24.3.0",
-    "@types/semver": "^7.7.0",
+    "@types/node": "^24.9.2",
+    "@types/semver": "^7.7.1",
     "@types/source-map-support": "^0.5.10",
-    "@vitest/coverage-v8": "^3.2.4",
-    "eslint": "^9.33.0",
-    "eslint-plugin-format": "^1.0.1",
+    "@vitest/coverage-v8": "^4.0.6",
+    "eslint": "^9.38.0",
+    "eslint-plugin-format": "^1.0.2",
     "eslint-plugin-import": "^2.32.0",
-    "homebridge": "^2.0.0-beta.38",
-    "homebridge-config-ui-x": "5.4.1",
+    "homebridge": "^2.0.0-beta.39",
+    "homebridge-config-ui-x": "^5.8.0",
     "nodemon": "^3.1.10",
     "shx": "^0.4.0",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.28.11",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "typedoc": "^0.28.14",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.6"
   },
   "directories": {
     "doc": "docs"

package/src/devices-hap/device.ts

@@ -288,11 +288,7 @@ export abstract class deviceBase {
       this.device.bleMac = formattedDeviceId
       this.debugLog(`bleMac: ${this.device.bleMac}`)
       this.historyService = device.history
-        ? new this.platform.fakegatoAPI('room', accessory, {
-          log: this.platform.log,
-          storage: 'fs',
-          filename: `${hostname().split('.')[0]}_${this.device.bleMac}_persist.json`,
-        })
+        ? new this.platform.fakegatoAPI('room', accessory, { log: this.platform.log, storage: 'fs', filename: `${hostname().split('.')[0]}_${this.device.bleMac}_persist.json` })
         : null
     } catch (error) {
       this.errorLog(`failed to format device ID as MAC, Error: ${error}`)
@@ -744,59 +740,101 @@ export abstract class deviceBase {
    * Logging for Device
    */
   infoLog(...log: any[]): void {
-    if (this.enablingDeviceLogging()) {
-      this.log.info(`${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
+    if (!this.enablingDeviceLogging()) {
+      return
     }
+    this.logWith('info', `${this.device.deviceType}: ${this.accessory.displayName}`, undefined, String(...log))
   }
 
   successLog(...log: any[]): void {
-    if (this.enablingDeviceLogging()) {
-      this.log.success(`${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
+    if (!this.enablingDeviceLogging()) {
+      return
     }
+    this.logWith('success', `${this.device.deviceType}: ${this.accessory.displayName}`, undefined, String(...log))
   }
 
   debugSuccessLog(...log: any[]): void {
-    if (this.enablingDeviceLogging()) {
-      if (this.loggingIsDebug()) {
-        this.log.success(`[DEBUG] ${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
-      }
+    if (!this.enablingDeviceLogging()) {
+      return
+    }
+    if (!this.loggingIsDebug()) {
+      return
     }
+    this.logWith('success', `[DEBUG] ${this.device.deviceType}: ${this.accessory.displayName}`, 'debugSuccessLog', String(...log))
   }
 
   warnLog(...log: any[]): void {
-    if (this.enablingDeviceLogging()) {
-      this.log.warn(`${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
+    if (!this.enablingDeviceLogging()) {
+      return
     }
+    this.logWith('warn', `${this.device.deviceType}: ${this.accessory.displayName}`, undefined, String(...log))
   }
 
   debugWarnLog(...log: any[]): void {
-    if (this.enablingDeviceLogging()) {
-      if (this.loggingIsDebug()) {
-        this.log.warn(`[DEBUG] ${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
-      }
+    if (!this.enablingDeviceLogging() || !this.loggingIsDebug()) {
+      return
     }
+    this.logWith('warn', `[DEBUG] ${this.device.deviceType}: ${this.accessory.displayName}`, 'debugWarnLog', String(...log))
   }
 
   errorLog(...log: any[]): void {
-    if (this.enablingDeviceLogging()) {
-      this.log.error(`${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
+    if (!this.enablingDeviceLogging()) {
+      return
     }
+    this.logWith('error', `${this.device.deviceType}: ${this.accessory.displayName}`, undefined, String(...log))
   }
 
   debugErrorLog(...log: any[]): void {
-    if (this.enablingDeviceLogging()) {
-      if (this.loggingIsDebug()) {
-        this.log.error(`[DEBUG] ${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
-      }
+    if (!this.enablingDeviceLogging() || !this.loggingIsDebug()) {
+      return
     }
+    this.logWith('error', `[DEBUG] ${this.device.deviceType}: ${this.accessory.displayName}`, 'debugErrorLog', String(...log))
   }
 
   debugLog(...log: any[]): void {
-    if (this.enablingDeviceLogging()) {
-      if (this.deviceLogging === 'debug') {
-        this.log.info(`[DEBUG] ${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
-      } else if (this.deviceLogging === 'debugMode') {
-        this.log.debug(`${this.device.deviceType}: ${this.accessory.displayName}`, String(...log))
+    if (!this.enablingDeviceLogging()) {
+      return
+    }
+    // debug behaves differently depending on debug vs debugMode
+    if (this.deviceLogging === 'debug') {
+      this.logWith('debug', `[DEBUG] ${this.device.deviceType}: ${this.accessory.displayName}`, 'debugLog', String(...log))
+    } else if (this.deviceLogging === 'debugMode') {
+      this.logWith('debug', `${this.device.deviceType}: ${this.accessory.displayName}`, 'debugLog', String(...log))
+    }
+  }
+
+  // Generic logger used by device log helpers. Attempts to call a platform
+  // helper method first (if present), then falls back to the local logger.
+  protected logWith(level: string, message: string, platformMethodName?: string, payload?: string): void {
+    const method = platformMethodName ?? `${level}Log`
+    const pFn = (this.platform as any)?.[method]
+    if (typeof pFn === 'function') {
+      try {
+        // Forward both a short message (title) and optional payload to the
+        // platform logger so it can format/attach metadata consistently.
+        if (payload !== undefined) {
+          pFn(message, payload)
+        } else {
+          pFn(message)
+        }
+        return
+      } catch (_err) {
+        // fallthrough to local logger
+      }
+    }
+    const map: Record<string, string> = {
+      info: 'info',
+      success: 'success',
+      debug: 'debug',
+      warn: 'warn',
+      error: 'error',
+    }
+    const local = (this.log as any)[map[level] ?? level]
+    if (typeof local === 'function') {
+      if (payload !== undefined) {
+        local.call(this.log, message, payload)
+      } else {
+        local.call(this.log, message)
       }
     }
   }

package/src/devices-matter/BaseMatterAccessory.ts

@@ -10,6 +10,8 @@
 
 import type { API, EndpointType, Logger, MatterAccessory } from 'homebridge'
 
+import { rgb2hs } from '../utils.js'
+
 export interface BaseMatterAccessoryConfig {
   uuid: string
   displayName: string
@@ -86,26 +88,187 @@ export abstract class BaseMatterAccessory implements MatterAccessory {
    */
   protected async updateState(cluster: string, attributes: Record<string, unknown>): Promise<void> {
     await this.api.matter.updateAccessoryState(this.uuid, cluster, attributes)
-    this.log.debug(`[${this.displayName}] Updated ${cluster} state:`, attributes)
+    this.logDebug(`Updated ${cluster} state:`, attributes)
   }
 
   /**
    * Log helper methods
    */
+  // Generic logging delegation: prefer platform-provided log helpers in
+  // `this.context` (infoLog/debugLog/warnLog/errorLog) and fall back to the
+  // local `this.log` methods when not available.
+  protected logWith(level: 'info' | 'error' | 'debug' | 'warn', message: string, ...args: unknown[]): void {
+    const ctx: any = this.context as any
+    const map: Record<string, string> = {
+      info: 'infoLog',
+      error: 'errorLog',
+      debug: 'debugLog',
+      warn: 'warnLog',
+    }
+    const fn = ctx?.[map[level]]
+    if (typeof fn === 'function') {
+      fn(`[${this.displayName}] ${message}`, ...args)
+      return
+    }
+    const local = (this.log as any)[level]
+    if (typeof local === 'function') {
+      local.call(this.log, `[${this.displayName}] ${message}`, ...args)
+    }
+  }
+
   protected logInfo(message: string, ...args: unknown[]): void {
-    this.log.info(`[${this.displayName}] ${message}`, ...args)
+    this.logWith('info', message, ...args)
   }
 
   protected logError(message: string, ...args: unknown[]): void {
-    this.log.error(`[${this.displayName}] ${message}`, ...args)
+    this.logWith('error', message, ...args)
   }
 
   protected logDebug(message: string, ...args: unknown[]): void {
-    this.log.debug(`[${this.displayName}] ${message}`, ...args)
+    this.logWith('debug', message, ...args)
   }
 
   protected logWarn(message: string, ...args: unknown[]): void {
-    this.log.warn(`[${this.displayName}] ${message}`, ...args)
+    this.logWith('warn', message, ...args)
+  }
+
+  /**
+   * Logging helpers parity: allow Matter accessories to ask whether device-level
+   * logging is enabled or in debug mode. These mirror the helpers used by the
+   * HAP/IR device bases so behavior is consistent across platforms.
+   */
+  public async loggingIsDebug(): Promise<boolean> {
+    const ctx: any = this.context as any
+    const deviceLogging = ctx?.deviceLogging
+    // deviceLogging may be a string ('debug', 'debugMode', 'standard') or undefined
+    return deviceLogging === 'debugMode' || deviceLogging === 'debug'
+  }
+
+  public async enablingDeviceLogging(): Promise<boolean> {
+    const ctx: any = this.context as any
+    const deviceLogging = ctx?.deviceLogging
+    // If deviceLogging isn't provided, fall back to the platform-wide flag
+    // that indicates whether platform logging is enabled.
+    if (deviceLogging === undefined) {
+      return Boolean((ctx as any)?.platformLogging)
+    }
+    return deviceLogging === 'debugMode' || deviceLogging === 'debug' || deviceLogging === 'standard'
+  }
+
+  /**
+   * Convenience helpers that delegate OpenAPI/BLE commands to platform-provided
+   * functions that are injected into the accessory `context` by
+   * `platform-matter` when the accessory is created from a discovered device.
+   *
+   * These methods are intentionally thin wrappers — the platform controls
+   * retries, discovery and client lifecycle via the helper functions.
+   */
+  protected async sendOpenAPICommand(command: string, parameter = 'default'): Promise<any> {
+    const ctx: any = this.context as any
+    const fn = ctx?.sendOpenAPI
+    if (typeof fn === 'function') {
+      return fn(command, parameter)
+    }
+    throw new Error('OpenAPI helper not available')
+  }
+
+  protected async sendBLECommand(methodName: string, ...args: any[]): Promise<any> {
+    const ctx: any = this.context as any
+    const fn = ctx?.sendBLE
+    if (typeof fn === 'function') {
+      return fn(methodName, ...args)
+    }
+    throw new Error('BLE helper not available')
+  }
+
+  public async sendOnCommand(deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('turnOn')
+      } else {
+        await this.sendOpenAPICommand('turnOn')
+      }
+      // update our matter state
+      await this.updateState(this.api.matter.clusterNames.OnOff, { onOff: true })
+      this.logInfo(`sendOnCommand successful for ${id}`)
+    } catch (e: any) {
+      this.logError(`sendOnCommand failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
+  public async sendOffCommand(deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('turnOff')
+      } else {
+        await this.sendOpenAPICommand('turnOff')
+      }
+      await this.updateState(this.api.matter.clusterNames.OnOff, { onOff: false })
+      this.logInfo(`sendOffCommand successful for ${id}`)
+    } catch (e: any) {
+      this.logError(`sendOffCommand failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
+  public async sendSetBrightness(percent: number, deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('setBrightness', percent)
+      } else {
+        await this.sendOpenAPICommand('setBrightness', String(percent))
+      }
+      const level = Math.round((percent / 100) * 254)
+      await this.updateState(this.api.matter.clusterNames.LevelControl, { currentLevel: level })
+      this.logInfo(`sendSetBrightness successful for ${id}: ${percent}%`)
+    } catch (e: any) {
+      this.logError(`sendSetBrightness failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
+  public async sendSetColor(r: number, g: number, b: number, deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('setRGB', r, g, b)
+      } else {
+        await this.sendOpenAPICommand('setColor', `${r}:${g}:${b}`)
+      }
+      // Convert to hue/sat for matter state update
+      const [h, s] = rgb2hs(r, g, b)
+      await this.updateState(this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) })
+      this.logInfo(`sendSetColor successful for ${id}: ${r},${g},${b}`)
+    } catch (e: any) {
+      this.logError(`sendSetColor failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
+  }
+
+  public async sendSetColorTemperature(kelvin: number, deviceId?: string): Promise<void> {
+    const ctx: any = this.context as any
+    const id = deviceId ?? ctx?.deviceId
+    try {
+      if (ctx?.connectionType === 'BLE') {
+        await this.sendBLECommand('setColorTemperature', kelvin)
+      } else {
+        await this.sendOpenAPICommand('setColorTemperature', `${kelvin}`)
+      }
+      const mireds = Math.round(1000000 / kelvin)
+      await this.updateState(this.api.matter.clusterNames.ColorControl, { colorTemperatureMireds: mireds })
+      this.logInfo(`sendSetColorTemperature successful for ${id}: ${kelvin}K`)
+    } catch (e: any) {
+      this.logError(`sendSetColorTemperature failed for ${id}: ${String(e?.message ?? e)}`)
+      throw e
+    }
   }
 
   /**

package/src/devices-matter/ColorLightAccessory.ts

@@ -5,6 +5,7 @@
 
 import type { API, Logger, MatterRequests } from 'homebridge'
 
+import { hs2rgb } from '../utils.js'
 import { BaseMatterAccessory } from './BaseMatterAccessory.js'
 
 export class ColorLightAccessory extends BaseMatterAccessory {
@@ -56,38 +57,37 @@ export class ColorLightAccessory extends BaseMatterAccessory {
 
   private async handleOn(): Promise<void> {
     this.logInfo('turning on.')
-    // TODO: await myLightAPI.turnOn()
+    await this.sendOnCommand()
   }
 
   private async handleOff(): Promise<void> {
     this.logInfo('turning off.')
-    // TODO: await myLightAPI.turnOff()
+    await this.sendOffCommand()
   }
 
   private async handleSetLevel(request: MatterRequests.MoveToLevel): Promise<void> {
     this.logInfo(`MoveToLevel request: ${JSON.stringify(request)}`)
     const { level } = request
     const brightnessPercent = Math.round((level / 254) * 100)
-    this.logInfo(`setting brightness to ${brightnessPercent}%.`)
-    // TODO: await myLightAPI.setBrightness(brightnessPercent)
+    await this.sendSetBrightness(brightnessPercent)
   }
 
   private async handleSetColor(request: MatterRequests.MoveToColor): Promise<void> {
     this.logInfo(`MoveToColor request: ${JSON.stringify(request)}`)
-    const { colorX, colorY, transitionTime } = request
-    const xFloat = (colorX / 65535).toFixed(4)
-    const yFloat = (colorY / 65535).toFixed(4)
-    this.logInfo(`setting xy color to (${xFloat}, ${yFloat}) with transition ${transitionTime}.`)
-    // TODO: await myLightAPI.setXY(xFloat, yFloat, transitionTime)
+    const { colorX, colorY } = request
+    const hueApprox = Math.round((colorX / 65535) * 360)
+    const satApprox = Math.round((colorY / 65535) * 100)
+    const [r, g, b] = hs2rgb(hueApprox, satApprox)
+    await this.sendSetColor(r, g, b)
   }
 
   private async handleSetHueSaturation(request: MatterRequests.MoveToHueAndSaturation): Promise<void> {
     this.logInfo(`MoveToHueAndSaturation request: ${JSON.stringify(request)}`)
-    const { hue, saturation, transitionTime } = request
+    const { hue, saturation } = request
     const hueDegrees = Math.round((hue / 254) * 360)
     const saturationPercent = Math.round((saturation / 254) * 100)
-    this.logInfo(`setting color to ${hueDegrees}°, ${saturationPercent}% with transition ${transitionTime}.`)
-    // TODO: await myLightAPI.setColor(hueDegrees, saturationPercent, transitionTime)
+    const [r, g, b] = hs2rgb(hueDegrees, saturationPercent)
+    await this.sendSetColor(r, g, b)
   }
 
   public updateOnOffState(isOn: boolean): void {

package/src/devices-matter/ColorTemperatureLightAccessory.ts

@@ -52,28 +52,26 @@ export class ColorTemperatureLightAccessory extends BaseMatterAccessory {
 
   private async handleOn(): Promise<void> {
     this.logInfo('turning on.')
-    // TODO: await myLightAPI.turnOn()
+    await this.sendOnCommand()
   }
 
   private async handleOff(): Promise<void> {
     this.logInfo('turning off.')
-    // TODO: await myLightAPI.turnOff()
+    await this.sendOffCommand()
   }
 
   private async handleSetLevel(request: MatterRequests.MoveToLevel): Promise<void> {
     this.logInfo(`MoveToLevel request: ${JSON.stringify(request)}`)
     const { level } = request
     const brightnessPercent = Math.round((level / 254) * 100)
-    this.logInfo(`setting brightness to ${brightnessPercent}% (level: ${level}).`)
-    // TODO: await myLightAPI.setBrightness(brightnessPercent)
+    await this.sendSetBrightness(brightnessPercent)
   }
 
   private async handleSetColorTemperature(request: MatterRequests.MoveToColorTemperature): Promise<void> {
     this.logInfo(`MoveToColorTemperature request: ${JSON.stringify(request)}`)
-    const { colorTemperatureMireds, transitionTime } = request
+    const { colorTemperatureMireds } = request
     const kelvin = Math.round(1000000 / colorTemperatureMireds)
-    this.logInfo(`setting color temp to ${kelvin}k (${colorTemperatureMireds} mireds) with transitionTime=${transitionTime}.`)
-    // TODO: await myLightAPI.setColorTemperature(kelvin, transitionTime)
+    await this.sendSetColorTemperature(kelvin)
   }
 
   public updateOnOffState(isOn: boolean): void {

package/src/devices-matter/DimmableLightAccessory.ts

@@ -69,10 +69,10 @@ export class DimmableLightAccessory extends BaseMatterAccessory {
     this.logInfo('turning on.')
 
     try {
-      // TODO: Control your physical device
-      // await myLightAPI.turnOn()
+      // Use platform helper (OpenAPI/BLE) when available
+      await this.sendOnCommand()
 
-      this.logInfo('physical device turned on.')
+      this.logInfo('physical device turned on (via platform helper).')
     } catch (error) {
       this.logError('failed to turn on:', error)
       throw error
@@ -86,10 +86,10 @@ export class DimmableLightAccessory extends BaseMatterAccessory {
     this.logInfo('turning off.')
 
     try {
-      // TODO: Control your physical device
-      // await myLightAPI.turnOff()
+      // Use platform helper (OpenAPI/BLE) when available
+      await this.sendOffCommand()
 
-      this.logInfo('physical device turned off.')
+      this.logInfo('physical device turned off (via platform helper).')
     } catch (error) {
       this.logError('failed to turn off:', error)
       throw error
@@ -110,10 +110,10 @@ export class DimmableLightAccessory extends BaseMatterAccessory {
     this.logInfo(`setting brightness to ${brightnessPercent}% (level: ${level}), transitionTime: ${transitionTime}.`)
 
     try {
-      // TODO: Control your physical device
-      // await myLightAPI.setBrightness(brightnessPercent, transitionTime)
+      // Use platform helper (OpenAPI/BLE) when available
+      await this.sendSetBrightness(brightnessPercent)
 
-      this.logInfo(`physical device brightness set to ${brightnessPercent}%.`)
+      this.logInfo(`physical device brightness set to ${brightnessPercent}% (via platform helper).`)
     } catch (error) {
       this.logError('Failed to set brightness:', error)
       throw error