@switchbot/homebridge-switchbot 5.1.0-beta.9 → 5.1.0

package/docs/index.html

@@ -40,23 +40,6 @@
 </ul>
 <p>Click <strong>Save Advanced Settings</strong> to apply changes. These settings match the options available in <code>config.schema.json</code> and can be overridden per device.</p>
 <!-- Optionally add a screenshot here -->
-<h3 id="per-device-external-publishing-hap-or-matter" class="tsd-anchor-link">Per-Device External Publishing (HAP or Matter)<a href="#per-device-external-publishing-hap-or-matter" 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>Each device now supports an <code>externalPublishProtocol</code> option to control whether it is published as an external accessory.</p>
-<ul>
-<li><code>none</code> (default): normal platform registration behavior.</li>
-<li><code>hap</code>: publish this device as a HAP external accessory.</li>
-<li><code>matter</code>: publish this device as a Matter external accessory.</li>
-</ul>
-<p>Behavior notes:</p>
-<ul>
-<li>This is configured per device in the Homebridge UI under <strong>Publish as External Device</strong> when adding or editing a device.</li>
-<li>If the selected external publish API is not available on your Homebridge runtime, the plugin falls back to normal platform registration for that device.</li>
-<li>Use <code>hap</code> for HAP-focused setups and <code>matter</code> for Matter-focused setups; leave as <code>none</code> unless you specifically want external accessory publishing.</li>
-</ul>
-<p>Example device config excerpt:</p>
-<pre><code class="json"><span class="hl-0">{</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;deviceId&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;E7F8A1B2C3D4&quot;</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;configDeviceName&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;Bedroom Bot&quot;</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;configDeviceType&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;Bot&quot;</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;externalPublishProtocol&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;hap&quot;</span><br/><span class="hl-0">}</span>
-</code><button type="button">Copy</button></pre>
-
 <ul>
 <li>
 <h3 id="if-using-openapi-connection" class="tsd-anchor-link">If using OpenAPI Connection<a href="#if-using-openapi-connection" 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>
@@ -134,7 +117,7 @@
 (This is what is intended in documentation for the noble bluetooth package <a href="https://github.com/abandonware/noble#prerequisites">prerequisites</a> by &quot;Add terminal app&quot;, however for HomeBridge it is <code>node</code> that needs the permission granted, not <code>terminal</code>.
 Without this step, then you will receive the following error when the swichbot plugin launches, which will cause Homebridge or the child bridge process to restart:</li>
 </ol>
-<pre><code><span class="hl-3">Error</span><span class="hl-0">: </span><span class="hl-4">Failed</span><span class="hl-0"> </span><span class="hl-4">to</span><span class="hl-0"> </span><span class="hl-4">initialize</span><span class="hl-0"> </span><span class="hl-4">the</span><span class="hl-0"> </span><span class="hl-4">Noble</span><span class="hl-0"> </span><span class="hl-3">object</span><span class="hl-0">: </span><span class="hl-4">unauthorized</span><br/><span class="hl-0">  </span><span class="hl-4">at</span><span class="hl-0"> </span><span class="hl-4">Noble</span><span class="hl-0">.&lt;</span><span class="hl-5">anonymous</span><span class="hl-0">&gt; (</span><span class="hl-4">file</span><span class="hl-0">:</span><span class="hl-6">///usr/local/lib/node_modules/@switchbot/homebridge-switchbot/node_modules/node-switchbot/src/switchbot.ts:244:19)</span><br/><span class="hl-0">  </span><span class="hl-5">at</span><span class="hl-0"> </span><span class="hl-5">Object</span><span class="hl-0">.</span><span class="hl-5">onceWrapper</span><span class="hl-0"> (</span><span class="hl-4">node</span><span class="hl-0">:</span><span class="hl-5">events</span><span class="hl-0">:</span><span class="hl-7">629</span><span class="hl-0">:</span><span class="hl-7">26</span><span class="hl-0">)</span><br/><span class="hl-0">  </span><span class="hl-5">at</span><span class="hl-0"> </span><span class="hl-5">Noble</span><span class="hl-0">.</span><span class="hl-5">emit</span><span class="hl-0"> (</span><span class="hl-4">node</span><span class="hl-0">:</span><span class="hl-5">events</span><span class="hl-0">:</span><span class="hl-7">514</span><span class="hl-0">:</span><span class="hl-7">28</span><span class="hl-0">)</span><br/><span class="hl-0">  </span><span class="hl-5">at</span><span class="hl-0"> </span><span class="hl-5">Noble</span><span class="hl-0">.</span><span class="hl-5">onStateChange</span><span class="hl-0"> (/</span><span class="hl-5">usr</span><span class="hl-0">/</span><span class="hl-5">local</span><span class="hl-0">/</span><span class="hl-5">lib</span><span class="hl-0">/</span><span class="hl-5">node_modules</span><span class="hl-0">/@</span><span class="hl-5">switchbot</span><span class="hl-0">/</span><span class="hl-5">homebridge</span><span class="hl-0">-</span><span class="hl-5">switchbot</span><span class="hl-0">/</span><span class="hl-5">node_modules</span><span class="hl-0">/@</span><span class="hl-5">stoprocent</span><span class="hl-0">/</span><span class="hl-5">noble</span><span class="hl-0">/</span><span class="hl-5">lib</span><span class="hl-0">/</span><span class="hl-5">noble</span><span class="hl-0">.</span><span class="hl-5">js</span><span class="hl-0">:</span><span class="hl-7">92</span><span class="hl-0">:</span><span class="hl-7">8</span><span class="hl-0">)</span><br/><span class="hl-0">  </span><span class="hl-5">at</span><span class="hl-0"> </span><span class="hl-5">NobleMac</span><span class="hl-0">.</span><span class="hl-5">emit</span><span class="hl-0"> (</span><span class="hl-4">node</span><span class="hl-0">:</span><span class="hl-5">events</span><span class="hl-0">:</span><span class="hl-7">514</span><span class="hl-0">:</span><span class="hl-7">28</span><span class="hl-0">)</span>
+<pre><code><span class="hl-0">Error</span><span class="hl-1">: </span><span class="hl-2">Failed</span><span class="hl-1"> </span><span class="hl-2">to</span><span class="hl-1"> </span><span class="hl-2">initialize</span><span class="hl-1"> </span><span class="hl-2">the</span><span class="hl-1"> </span><span class="hl-2">Noble</span><span class="hl-1"> </span><span class="hl-0">object</span><span class="hl-1">: </span><span class="hl-2">unauthorized</span><br/><span class="hl-1">  </span><span class="hl-2">at</span><span class="hl-1"> </span><span class="hl-2">Noble</span><span class="hl-1">.&lt;</span><span class="hl-3">anonymous</span><span class="hl-1">&gt; (</span><span class="hl-2">file</span><span class="hl-1">:</span><span class="hl-4">///usr/local/lib/node_modules/@switchbot/homebridge-switchbot/node_modules/node-switchbot/src/switchbot.ts:244:19)</span><br/><span class="hl-1">  </span><span class="hl-3">at</span><span class="hl-1"> </span><span class="hl-3">Object</span><span class="hl-1">.</span><span class="hl-3">onceWrapper</span><span class="hl-1"> (</span><span class="hl-2">node</span><span class="hl-1">:</span><span class="hl-3">events</span><span class="hl-1">:</span><span class="hl-5">629</span><span class="hl-1">:</span><span class="hl-5">26</span><span class="hl-1">)</span><br/><span class="hl-1">  </span><span class="hl-3">at</span><span class="hl-1"> </span><span class="hl-3">Noble</span><span class="hl-1">.</span><span class="hl-3">emit</span><span class="hl-1"> (</span><span class="hl-2">node</span><span class="hl-1">:</span><span class="hl-3">events</span><span class="hl-1">:</span><span class="hl-5">514</span><span class="hl-1">:</span><span class="hl-5">28</span><span class="hl-1">)</span><br/><span class="hl-1">  </span><span class="hl-3">at</span><span class="hl-1"> </span><span class="hl-3">Noble</span><span class="hl-1">.</span><span class="hl-3">onStateChange</span><span class="hl-1"> (/</span><span class="hl-3">usr</span><span class="hl-1">/</span><span class="hl-3">local</span><span class="hl-1">/</span><span class="hl-3">lib</span><span class="hl-1">/</span><span class="hl-3">node_modules</span><span class="hl-1">/@</span><span class="hl-3">switchbot</span><span class="hl-1">/</span><span class="hl-3">homebridge</span><span class="hl-1">-</span><span class="hl-3">switchbot</span><span class="hl-1">/</span><span class="hl-3">node_modules</span><span class="hl-1">/@</span><span class="hl-3">stoprocent</span><span class="hl-1">/</span><span class="hl-3">noble</span><span class="hl-1">/</span><span class="hl-3">lib</span><span class="hl-1">/</span><span class="hl-3">noble</span><span class="hl-1">.</span><span class="hl-3">js</span><span class="hl-1">:</span><span class="hl-5">92</span><span class="hl-1">:</span><span class="hl-5">8</span><span class="hl-1">)</span><br/><span class="hl-1">  </span><span class="hl-3">at</span><span class="hl-1"> </span><span class="hl-3">NobleMac</span><span class="hl-1">.</span><span class="hl-3">emit</span><span class="hl-1"> (</span><span class="hl-2">node</span><span class="hl-1">:</span><span class="hl-3">events</span><span class="hl-1">:</span><span class="hl-5">514</span><span class="hl-1">:</span><span class="hl-5">28</span><span class="hl-1">)</span>
 </code><button>Copy</button></pre>
 
 </li>
@@ -362,7 +345,7 @@ Without this step, then you will receive the following error when the swichbot p
 <h4 id="how-to-configure-in-homebridge" class="tsd-anchor-link">How to Configure in Homebridge<a href="#how-to-configure-in-homebridge" 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></h4>
 <p>In the Homebridge UI, when adding or editing a SwitchBot device, enter the <strong>Encryption Key</strong> and <strong>Key ID</strong> in the provided fields. These values will be securely used for BLE communication with your device.</p>
 <p><strong>Example device config excerpt:</strong></p>
-<pre><code class="json"><span class="hl-0">{</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;deviceId&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;E7F8A1B2C3D4&quot;</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;deviceName&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;SwitchBot Lock&quot;</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;enableBLE&quot;</span><span class="hl-0">: </span><span class="hl-8">true</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;encryptionKey&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;0123456789abcdef0123456789abcdef&quot;</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;keyId&quot;</span><span class="hl-0">: </span><span class="hl-2">&quot;01&quot;</span><br/><span class="hl-0">}</span>
+<pre><code class="json"><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;deviceId&quot;</span><span class="hl-1">: </span><span class="hl-7">&quot;E7F8A1B2C3D4&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;deviceName&quot;</span><span class="hl-1">: </span><span class="hl-7">&quot;SwitchBot Lock&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;enableBLE&quot;</span><span class="hl-1">: </span><span class="hl-8">true</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;encryptionKey&quot;</span><span class="hl-1">: </span><span class="hl-7">&quot;0123456789abcdef0123456789abcdef&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;keyId&quot;</span><span class="hl-1">: </span><span class="hl-7">&quot;01&quot;</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h4 id="which-devices-require-ble-encryption" class="tsd-anchor-link">Which Devices Require BLE Encryption?<a href="#which-devices-require-ble-encryption" 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></h4>
@@ -511,7 +494,7 @@ Without this step, then you will receive the following error when the swichbot p
 <li><code>dailyApiResetLocalMidnight</code> (boolean, default false): if true, resets the daily counter at local midnight; when false, resets at UTC midnight.</li>
 </ul>
 <p>Example (excerpt):</p>
-<pre><code class="json"><span class="hl-0">{</span><br/><span class="hl-0">  </span><span class="hl-1">&quot;options&quot;</span><span class="hl-0">: {</span><br/><span class="hl-0">    </span><span class="hl-1">&quot;dailyApiLimit&quot;</span><span class="hl-0">: </span><span class="hl-7">10000</span><span class="hl-0">,</span><br/><span class="hl-0">    </span><span class="hl-1">&quot;dailyApiReserveForCommands&quot;</span><span class="hl-0">: </span><span class="hl-7">1000</span><span class="hl-0">,</span><br/><span class="hl-0">    </span><span class="hl-1">&quot;webhookOnlyOnReserve&quot;</span><span class="hl-0">: </span><span class="hl-8">false</span><span class="hl-0">,</span><br/><span class="hl-0">    </span><span class="hl-1">&quot;dailyApiResetLocalMidnight&quot;</span><span class="hl-0">: </span><span class="hl-8">true</span><br/><span class="hl-0">  }</span><br/><span class="hl-0">}</span>
+<pre><code class="json"><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-6">&quot;options&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiLimit&quot;</span><span class="hl-1">: </span><span class="hl-5">10000</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiReserveForCommands&quot;</span><span class="hl-1">: </span><span class="hl-5">1000</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;webhookOnlyOnReserve&quot;</span><span class="hl-1">: </span><span class="hl-8">false</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">&quot;dailyApiResetLocalMidnight&quot;</span><span class="hl-1">: </span><span class="hl-8">true</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <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>
@@ -527,7 +510,7 @@ Without this step, then you will receive the following error when the swichbot p
 <ul>
 <li>
 <p>Run unit tests:</p>
-<pre><code class="bash"><span class="hl-9">npm</span><span class="hl-0"> </span><span class="hl-2">run</span><span class="hl-0"> </span><span class="hl-2">test</span>
+<pre><code class="bash"><span class="hl-9">npm</span><span class="hl-1"> </span><span class="hl-7">run</span><span class="hl-1"> </span><span class="hl-7">test</span>
 </code><button type="button">Copy</button></pre>
 
 </li>
@@ -544,4 +527,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="#openapi-pollingrate-advanced-settings-ui"><span>Open<wbr/>API <wbr/>Polling/<wbr/>Rate <wbr/>Advanced <wbr/>Settings (<wbr/>UI)</span></a></li><li><a href="#per-device-external-publishing-hap-or-matter"><span>Per-<wbr/>Device <wbr/>External <wbr/>Publishing (<wbr/>HAP or <wbr/>Matter)</span></a></li><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="#ble-encryption-support"><span>BLE <wbr/>Encryption <wbr/>Support</span></a></li><li><ul><li><a href="#ble-encryption-key-and-key-id"><span>BLE <wbr/>Encryption <wbr/>Key and <wbr/>Key <wbr/>ID</span></a></li><li><ul><li><a href="#how-to-obtain-ble-encryption-key-and-key-id"><span>How to <wbr/>Obtain <wbr/>BLE <wbr/>Encryption <wbr/>Key and <wbr/>Key <wbr/>ID</span></a></li><li><a href="#how-to-configure-in-homebridge"><span>How to <wbr/>Configure in <wbr/>Homebridge</span></a></li><li><a href="#which-devices-require-ble-encryption"><span>Which <wbr/>Devices <wbr/>Require <wbr/>BLE <wbr/>Encryption?</span></a></li></ul></li></ul></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-mini-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 <wbr/>Mini 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="#whats-new-with-node-switchbot-v400"><span>What&#39;s new with node-<wbr/>switchbot v4.0.0</span></a></li><li><a href="#openapi-rate-limiting-and-daily-budget"><span>Open<wbr/>API rate limiting and daily budget</span></a></li><li><a href="#switchbot-apis"><span>Switch<wbr/>Bot <wbr/>AP<wbr/>Is</span></a></li><li><a href="#development-tests"><span>Development / <wbr/>Tests</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="#openapi-pollingrate-advanced-settings-ui"><span>Open<wbr/>API <wbr/>Polling/<wbr/>Rate <wbr/>Advanced <wbr/>Settings (<wbr/>UI)</span></a></li><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="#ble-encryption-support"><span>BLE <wbr/>Encryption <wbr/>Support</span></a></li><li><ul><li><a href="#ble-encryption-key-and-key-id"><span>BLE <wbr/>Encryption <wbr/>Key and <wbr/>Key <wbr/>ID</span></a></li><li><ul><li><a href="#how-to-obtain-ble-encryption-key-and-key-id"><span>How to <wbr/>Obtain <wbr/>BLE <wbr/>Encryption <wbr/>Key and <wbr/>Key <wbr/>ID</span></a></li><li><a href="#how-to-configure-in-homebridge"><span>How to <wbr/>Configure in <wbr/>Homebridge</span></a></li><li><a href="#which-devices-require-ble-encryption"><span>Which <wbr/>Devices <wbr/>Require <wbr/>BLE <wbr/>Encryption?</span></a></li></ul></li></ul></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-mini-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 <wbr/>Mini 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="#whats-new-with-node-switchbot-v400"><span>What&#39;s new with node-<wbr/>switchbot v4.0.0</span></a></li><li><a href="#openapi-rate-limiting-and-daily-budget"><span>Open<wbr/>API rate limiting and daily budget</span></a></li><li><a href="#switchbot-apis"><span>Switch<wbr/>Bot <wbr/>AP<wbr/>Is</span></a></li><li><a href="#development-tests"><span>Development / <wbr/>Tests</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,3 +1,3 @@
 <!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-comment tsd-typography"><p>Registers the SwitchBot platform with Homebridge.</p>
 </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><div class="tsd-comment tsd-typography"><p>The Homebridge API instance.</p>
-</div></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/324ff500a95bfe7d722fc56e5a653b3028ebd446/src/index.ts#L22">index.ts:22</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>
+</div></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/a8567ae7471ac7354c5c3424818c54371239af9b/src/index.ts#L22">index.ts:22</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.1.0-beta.9",
+  "version": "5.1.0",
   "description": "The SwitchBot plugin allows you to access your SwitchBot device(s) from HomeKit.",
   "author": "SwitchBot <support@wondertechlabs.com> (https://github.com/SwitchBot)",
   "contributors": [
@@ -32,7 +32,6 @@
   },
   "keywords": [
     "homebridge-plugin",
-    "homebridge-matter",
     "switchbot",
     "lights",
     "fan",
@@ -93,21 +92,28 @@
   },
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.2.3",
-    "node-switchbot": "^4.0.2"
+    "class-validator": "^0.15.1",
+    "node-switchbot": "^4.0.1"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^8.2.0",
+    "@types/debug": "^4.1.13",
+    "@types/fs-extra": "^11.0.4",
     "@types/node": "^25.6.0",
-    "@vitest/coverage-v8": "^4.1.5",
+    "@types/semver": "^7.7.1",
+    "@types/source-map-support": "^0.5.10",
+    "@vitest/coverage-v8": "^4.1.4",
     "esbuild": "^0.28.0",
-    "eslint": "^10.3.0",
+    "eslint": "^10.2.0",
     "eslint-plugin-format": "^2.0.1",
-    "eslint-plugin-perfectionist": "^5.9.0",
-    "homebridge": "^2.0.1",
+    "eslint-plugin-html": "^8.1.4",
+    "eslint-plugin-perfectionist": "^5.8.0",
+    "homebridge": "^2.0.0-beta.89",
+    "homebridge-config-ui-x": "^5.21.0",
     "nodemon": "^3.1.14",
     "shx": "^0.4.0",
     "typedoc": "^0.28.19",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   }
 }

package/scripts/build-ui.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import esbuild from 'esbuild'
-import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -11,38 +10,10 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 const srcDir = path.resolve(__dirname, '../src/homebridge-ui/public/js')
 const outputDir = path.resolve(__dirname, '../dist/homebridge-ui/public/js')
-const publicDir = path.resolve(__dirname, '../dist/homebridge-ui/public')
 
 // Ensure output directory exists
 fs.mkdirSync(outputDir, { recursive: true })
 
-function assetHash(filePath) {
-  const contents = fs.readFileSync(filePath)
-  return crypto.createHash('sha256').update(contents).digest('hex').slice(0, 8)
-}
-
-function cacheBustBuiltAssets() {
-  const indexPath = path.join(publicDir, 'index.html')
-  if (!fs.existsSync(indexPath)) {
-    return
-  }
-
-  let html = fs.readFileSync(indexPath, 'utf8')
-  const assets = ['app.js', 'advanced-settings.js']
-
-  for (const assetName of assets) {
-    const assetPath = path.join(outputDir, assetName)
-    if (!fs.existsSync(assetPath)) {
-      continue
-    }
-
-    const hashedSrc = `js/${assetName}?v=${assetHash(assetPath)}`
-    html = html.replace(new RegExp(`js/${assetName}(\\?v=[^\"']+)?`, 'g'), hashedSrc)
-  }
-
-  fs.writeFileSync(indexPath, html)
-}
-
 // Transpile TypeScript to JavaScript with esbuild
 esbuild
   .build({
@@ -58,7 +29,6 @@ esbuild
     logLevel: 'info',
   })
   .then(() => {
-    cacheBustBuiltAssets()
     console.log('✓ UI bundling complete')
   })
   .catch((error) => {

package/src/{Platform.HAP.ts → SwitchBotHAPPlatform.ts}

@@ -1,11 +1,10 @@
-import type { API, Logger, PlatformConfig } from 'homebridge'
-
 import type { SwitchBotPluginConfig } from './settings.js'
+import type { API, Logger, PlatformConfig } from 'homebridge'
 
 import { createDevice } from './deviceFactory.js'
 import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js'
 import { SwitchBotClient } from './switchbotClient.js'
-import { normalizeTypeForMatter, resolveExternalPublishProtocol } from './utils.js'
+import { normalizeTypeForMatter } from './utils.js'
 
 /**
  * Homebridge platform class for SwitchBot HAP (HomeKit Accessory Protocol) integration.
@@ -42,6 +41,9 @@ export class SwitchBotHAPPlatform {
   private lastConfigHash: string = ''
   /** Interval for periodic config reload */
   private configReloadInterval: NodeJS.Timeout | null = null
+  /** Readable characteristics per device id, so a poll can push new values */
+  private hapPushTargets: Map<string, { device: any, entries: Array<{ service: any, characteristic: any, get: () => Promise<any> }> }> = new Map()
+
   /** Timers for per-device OpenAPI polling */
   private openApiPollTimers: Map<string, NodeJS.Timeout> = new Map()
   /** Timer for batched OpenAPI polling */
@@ -141,7 +143,7 @@ export class SwitchBotHAPPlatform {
     }
 
     const devices = (this.config as any)?.devices ?? []
-    const createdDevices: { created: any, d: any, type: string, externalPublishProtocol: 'none' | 'hap' | 'matter' }[] = []
+    const createdDevices: { created: any, d: any, type: string }[] = []
     for (const raw of devices) {
       // Normalize config keys from UI schema to internal shape (for cross-platform consistency)
       const d: any = {
@@ -153,19 +155,19 @@ export class SwitchBotHAPPlatform {
         _raw: raw,
       }
       const type: string = normalizeTypeForMatter(d.type)
-      const externalPublishProtocol = resolveExternalPublishProtocol(raw)
       const deviceOpts: any = { id: d.id, type, name: d.name, encryptionKey: d.encryptionKey, keyId: d.keyId, log: this.log }
       this.log.debug(`[HAP/Debug] Device options for ${d.name ?? d.id}:`, JSON.stringify(deviceOpts, null, 2))
       try {
         const created = await createDevice(deviceOpts, this.config, false)
         this.devices.push(created)
-        createdDevices.push({ created, d, type, externalPublishProtocol })
+        createdDevices.push({ created, d, type })
       } catch (e: any) {
         this.log.error(`Failed to create HAP device ${d.id}:`, e instanceof Error ? e.stack || e.message : e)
       }
     }
     // Register HAP accessories after all devices are created for symmetry with Matter platform
     await this.registerHAPAccessories(createdDevices)
+    this.primeHapValues()
     this.lastConfigHash = newHash
   }
 
@@ -190,15 +192,14 @@ export class SwitchBotHAPPlatform {
    *
    * If the Homebridge HAP API is not available, registration is skipped and a log message is emitted.
    */
-  private async registerHAPAccessories(createdDevices: { created: any, d: any, type: string, externalPublishProtocol: 'none' | 'hap' | 'matter' }[]): Promise<void> {
-    if (!this.api || !(this.api as any).hap || typeof (this.api as any).hap.registerPlatformAccessories !== 'function') {
+  private async registerHAPAccessories(createdDevices: { created: any, d: any, type: string }[]): Promise<void> {
+    if (!this.api || !(this.api as any).hap || typeof (this.api as any).registerPlatformAccessories !== 'function') {
       this.log.info('HAP API not available to register accessories')
       return
     }
     const hap = (this.api as any).hap
     const accessoriesToRegister: any[] = []
-    const externalAccessoriesToPublish: any[] = []
-    for (const { created, d, type, externalPublishProtocol } of createdDevices) {
+    for (const { created, d, type } of createdDevices) {
       try {
         const uuid = hap.uuid.generate(`${d.id}`)
         let accessory: any = this.accessories.get(uuid)
@@ -215,9 +216,7 @@ export class SwitchBotHAPPlatform {
           }
         }
         if (!accessory) {
-          // Use the PlatformAccessory constructor from the HAP API
-          const PlatformAccessory = (this.api as any).hap?.PlatformAccessory || (this.api as any).platformAccessory
-          accessory = new PlatformAccessory(d.name || type, uuid)
+          accessory = new (this.api as any).platformAccessory(d.name || type, uuid)
           try {
             accessory.context = accessory.context || {}
             accessory.context.deviceId = d.id
@@ -225,11 +224,7 @@ export class SwitchBotHAPPlatform {
           } catch (e) {
             // ignore context failures
           }
-          if (externalPublishProtocol === 'hap') {
-            externalAccessoriesToPublish.push(accessory)
-          } else {
-            accessoriesToRegister.push(accessory)
-          }
+          accessoriesToRegister.push(accessory)
           this.accessories.set(uuid, accessory)
         } else {
           try {
@@ -249,12 +244,38 @@ export class SwitchBotHAPPlatform {
             // ignore
           }
         }
+        // Ensure AccessoryInformation service exists - required for cache deserialization.
+        // Without it, hap-nodejs _sideloadServices crashes on next start.
+        try {
+          const InfoService = hap.Service.AccessoryInformation
+          if (InfoService) {
+            const info = accessory.getService(InfoService) || accessory.addService(InfoService)
+            const accDescForInfo = await created.createAccessory?.(this.api).catch?.(() => undefined)
+            const manufacturer = (accDescForInfo && accDescForInfo.manufacturer) || 'SwitchBot'
+            const model = (accDescForInfo && accDescForInfo.model) || type || 'SwitchBot Device'
+            const serial = (accDescForInfo && accDescForInfo.serialNumber) || d.id
+            const firmware = (accDescForInfo && accDescForInfo.firmwareRevision) || '1.0.0'
+            try {
+              info.setCharacteristic(hap.Characteristic.Manufacturer, manufacturer)
+              info.setCharacteristic(hap.Characteristic.Model, model)
+              info.setCharacteristic(hap.Characteristic.SerialNumber, serial)
+              info.setCharacteristic(hap.Characteristic.FirmwareRevision, firmware)
+            } catch (e) {
+              // ignore
+            }
+          }
+        } catch (e) {
+          // ignore
+        }
         // Add basic service descriptor from device (symmetrical to Matter: remove stale services/chars)
         const accDesc = await created.createAccessory?.(this.api)
         if (accDesc && accDesc.services) {
           const serviceTypes = accDesc.services.map((s: any) => s.type)
           for (const existingService of accessory.services.slice()) {
-            if (existingService.constructor && existingService.constructor.name && !serviceTypes.includes(existingService.constructor.name)) {
+            // Never remove AccessoryInformation - required for cache deserialization
+            if (existingService.constructor && existingService.constructor.name
+              && existingService.constructor.name !== 'AccessoryInformation'
+              && !serviceTypes.includes(existingService.constructor.name)) {
               accessory.removeService(existingService)
             }
           }
@@ -285,9 +306,32 @@ export class SwitchBotHAPPlatform {
               }
               if (getterSetter && typeof getterSetter.get === 'function') {
                 service.getCharacteristic(Characteristic).onGet(getterSetter.get)
+                // Remember it so a poll can push the new value.
+                const target = this.hapPushTargets.get(d.id) ?? { device: created?.instance ?? created, entries: [] }
+                target.entries.push({ service, characteristic: Characteristic, get: getterSetter.get })
+                this.hapPushTargets.set(d.id, target)
               }
               if (getterSetter && typeof getterSetter.set === 'function') {
-                service.getCharacteristic(Characteristic).onSet(getterSetter.set)
+                service.getCharacteristic(Characteristic).onSet(async (value: any) => {
+                  await getterSetter.set(value)
+
+                  const refreshAfterSet = Array.isArray(getterSetter.refreshAfterSet) ? getterSetter.refreshAfterSet : []
+                  for (const refreshCharName of refreshAfterSet) {
+                    const refreshGetterSetter: any = (s.characteristics || {})[refreshCharName]
+                    if (!refreshGetterSetter || typeof refreshGetterSetter.get !== 'function') {
+                      continue
+                    }
+                    const RefreshCharacteristic = (hap.Characteristic as any)[refreshCharName]
+                    if (!RefreshCharacteristic) {
+                      continue
+                    }
+                    try {
+                      service.getCharacteristic(RefreshCharacteristic).updateValue(await refreshGetterSetter.get())
+                    } catch (e) {
+                      this.log.debug?.(`Failed to refresh ${refreshCharName} after setting ${charName}`, e)
+                    }
+                  }
+                })
               }
             }
           }
@@ -307,24 +351,6 @@ export class SwitchBotHAPPlatform {
     } else {
       this.log.info('No HAP accessories to register')
     }
-    if (externalAccessoriesToPublish.length > 0) {
-      if (typeof (this.api as any).publishExternalAccessories === 'function') {
-        try {
-          (this.api as any).publishExternalAccessories(PLUGIN_NAME, externalAccessoriesToPublish)
-          this.log.info(`Published ${externalAccessoriesToPublish.length} HAP external accessory(ies) with Homebridge`)
-        } catch (e) {
-          this.log.warn('Failed to publish HAP external accessories', e)
-        }
-      } else {
-        this.log.warn('HAP external accessory publishing API not available; falling back to regular platform registration')
-        try {
-          (this.api as any).registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, externalAccessoriesToPublish)
-          this.log.info(`Registered ${externalAccessoriesToPublish.length} HAP accessory(ies) as fallback (external publishing unavailable)`)
-        } catch (e) {
-          this.log.warn('Failed to register fallback HAP accessories', e)
-        }
-      }
-    }
   }
 
   /**
@@ -359,7 +385,6 @@ export class SwitchBotHAPPlatform {
       id: d.deviceId ?? d.id,
       type: d.configDeviceType ?? d.type,
       name: d.configDeviceName ?? d.name,
-      externalPublishProtocol: resolveExternalPublishProtocol(d),
     })))
   }
 
@@ -422,6 +447,52 @@ export class SwitchBotHAPPlatform {
    *
    * @returns {void}
    */
+  /**
+   * Read every registered characteristic for a device and notify HomeKit.
+   *
+   * The device state is cached and de-duplicated, so one call costs a single
+   * API request however many characteristics the accessory has.
+   */
+  private async _pushDeviceState(id: string): Promise<void> {
+    const target = this.hapPushTargets.get(id)
+    if (!target?.entries.length) {
+      return
+    }
+    // Read once first. A device that could not be read must push nothing: the
+    // getters report a fallback for a missing field, and pushing that would
+    // replace a good value in HomeKit with one that looks like a measurement.
+    try {
+      const state = await target.device?.getState?.()
+      if (state?.unreadable) {
+        this.log.debug?.(`Skipped pushing updates for ${id}: device not readable`)
+        return
+      }
+    } catch (e) {
+      this.log.debug?.(`Skipped pushing updates for ${id}:`, (e as Error)?.message)
+      return
+    }
+    for (const { service, characteristic, get } of target.entries) {
+      try {
+        const value = await get()
+        if (value !== undefined && value !== null) {
+          service.getCharacteristic(characteristic).updateValue(value)
+        }
+      } catch (e) {
+        this.log.debug?.(`Failed to push an update for ${id}:`, (e as Error)?.message)
+      }
+    }
+  }
+
+  /**
+   * Push once now, so the Home app shows a value without waiting for the first
+   * poll interval.
+   */
+  private primeHapValues(): void {
+    for (const id of this.hapPushTargets.keys()) {
+      void this._pushDeviceState(id)
+    }
+  }
+
   private _setupOpenApiPolling(): void {
     // Clear any existing timers
     for (const t of this.openApiPollTimers.values()) clearInterval(t)
@@ -497,6 +568,7 @@ export class SwitchBotHAPPlatform {
             if (client && typeof client.getDevice === 'function') {
               await client.getDevice(id)
               this.openApiRequestsToday++
+              await this._pushDeviceState(id)
               this.log.debug(`[OpenAPI] Polled device ${id} (per-device interval ${perDeviceRate}s) [${this.openApiRequestsToday}/${dailyLimit}]`)
             }
           } catch (e) {
@@ -536,6 +608,7 @@ export class SwitchBotHAPPlatform {
               try {
                 await client.getDevice(dev.deviceId ?? dev.id)
                 this.openApiRequestsToday++
+                await this._pushDeviceState(dev.deviceId ?? dev.id)
                 this.log.debug(`[OpenAPI] Batched poll device ${dev.deviceId ?? dev.id} [${this.openApiRequestsToday}/${dailyLimit}]`)
               } catch (e) {
                 this.log.debug(`[OpenAPI] Batched polling failed for device ${dev.deviceId ?? dev.id}:`, (e as Error)?.message)