@switchbot/homebridge-switchbot 5.0.0 → 5.1.0-beta.0

package/docs/index.html

@@ -40,6 +40,23 @@
 </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>
@@ -117,7 +134,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-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>
+<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>
 </code><button>Copy</button></pre>
 
 </li>
@@ -345,7 +362,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-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>
+<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>
 </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>
@@ -494,7 +511,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-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>
+<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>
 </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>
@@ -510,7 +527,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-1"> </span><span class="hl-7">run</span><span class="hl-1"> </span><span class="hl-7">test</span>
+<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>
 </code><button type="button">Copy</button></pre>
 
 </li>
@@ -527,4 +544,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="#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="#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>

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/50cea4b3bf59e48befc35e5599a830888265844b/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/b3af65f017e09fd27d158673c1c37935372c3fd8/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.0.0",
+  "version": "5.1.0-beta.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": [

package/src/SwitchBotHAPPlatform.ts

@@ -4,7 +4,7 @@ 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 } from './utils.js'
+import { normalizeTypeForMatter, resolveExternalPublishProtocol } from './utils.js'
 
 /**
  * Homebridge platform class for SwitchBot HAP (HomeKit Accessory Protocol) integration.
@@ -140,7 +140,7 @@ export class SwitchBotHAPPlatform {
     }
 
     const devices = (this.config as any)?.devices ?? []
-    const createdDevices: { created: any, d: any, type: string }[] = []
+    const createdDevices: { created: any, d: any, type: string, externalPublishProtocol: 'none' | 'hap' | 'matter' }[] = []
     for (const raw of devices) {
       // Normalize config keys from UI schema to internal shape (for cross-platform consistency)
       const d: any = {
@@ -152,12 +152,13 @@ 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 })
+        createdDevices.push({ created, d, type, externalPublishProtocol })
       } catch (e: any) {
         this.log.error(`Failed to create HAP device ${d.id}:`, e instanceof Error ? e.stack || e.message : e)
       }
@@ -188,14 +189,15 @@ 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 }[]): Promise<void> {
+  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') {
       this.log.info('HAP API not available to register accessories')
       return
     }
     const hap = (this.api as any).hap
     const accessoriesToRegister: any[] = []
-    for (const { created, d, type } of createdDevices) {
+    const externalAccessoriesToPublish: any[] = []
+    for (const { created, d, type, externalPublishProtocol } of createdDevices) {
       try {
         const uuid = hap.uuid.generate(`${d.id}`)
         let accessory: any = this.accessories.get(uuid)
@@ -220,7 +222,11 @@ export class SwitchBotHAPPlatform {
           } catch (e) {
             // ignore context failures
           }
-          accessoriesToRegister.push(accessory)
+          if (externalPublishProtocol === 'hap') {
+            externalAccessoriesToPublish.push(accessory)
+          } else {
+            accessoriesToRegister.push(accessory)
+          }
           this.accessories.set(uuid, accessory)
         } else {
           try {
@@ -298,6 +304,24 @@ 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)
+        }
+      }
+    }
   }
 
   /**
@@ -332,6 +356,7 @@ export class SwitchBotHAPPlatform {
       id: d.deviceId ?? d.id,
       type: d.configDeviceType ?? d.type,
       name: d.configDeviceName ?? d.name,
+      externalPublishProtocol: resolveExternalPublishProtocol(d),
     })))
   }
 

package/src/SwitchBotMatterPlatform.ts

@@ -4,7 +4,7 @@ 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 { createMatterHandlers, DEVICE_MATTER_CLUSTERS, DEVICE_MATTER_SUPPORTED, normalizeTypeForMatter, resolveMatterDeviceType } from './utils.js'
+import { createMatterHandlers, DEVICE_MATTER_CLUSTERS, DEVICE_MATTER_SUPPORTED, normalizeTypeForMatter, resolveExternalPublishProtocol, resolveMatterDeviceType } from './utils.js'
 
 /**
  * Homebridge platform class for SwitchBot Matter integration.
@@ -113,7 +113,7 @@ export class SwitchBotMatterPlatform {
     }
 
     const devices = (this.config as any)?.devices ?? []
-    const createdDevices: { created: any, d: any, type: string, useMatter: boolean, matterAvailable: boolean }[] = []
+    const createdDevices: { created: any, d: any, type: string, useMatter: boolean, matterAvailable: boolean, externalPublishProtocol: 'none' | 'hap' | 'matter' }[] = []
     for (const raw of devices) {
       // Normalize config keys from UI schema to internal shape (for cross-platform consistency)
       const d: any = {
@@ -125,6 +125,7 @@ export class SwitchBotMatterPlatform {
         _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(`[Matter/Debug] Device options for ${d.name ?? d.id}:`, JSON.stringify(deviceOpts, null, 2))
       const matterSupported = !!DEVICE_MATTER_SUPPORTED[(type || '').toLowerCase()]
@@ -134,7 +135,7 @@ export class SwitchBotMatterPlatform {
       try {
         const created = await createDevice(deviceOpts, this.config, useMatter)
         this.devices.push(created)
-        createdDevices.push({ created, d, type, useMatter, matterAvailable })
+        createdDevices.push({ created, d, type, useMatter, matterAvailable, externalPublishProtocol })
         if (useMatter) {
           this.log.info(`Prepared Matter accessory for ${d.id} (${type})${matterAvailable ? ' (auto-detected)' : ' (manually enabled)'}`)
         } else {
@@ -179,14 +180,15 @@ export class SwitchBotMatterPlatform {
    * If the Homebridge Matter API is not available, registration is skipped and a log message is emitted.
    * Accessories that are not enabled for Matter are ignored.
    */
-  async registerMatterAccessories(createdDevices: { created: any, d: any, type: string, useMatter: boolean, matterAvailable: boolean }[]): Promise<void> {
+  async registerMatterAccessories(createdDevices: { created: any, d: any, type: string, useMatter: boolean, matterAvailable: boolean, externalPublishProtocol: 'none' | 'hap' | 'matter' }[]): Promise<void> {
     if (!this.api || !(this.api as any).matter || typeof (this.api as any).matter.registerPlatformAccessories !== 'function') {
       this.log.info('Homebridge Matter API not available; skipping Matter accessory registration')
       return
     }
     const matterApi = (this.api as any).matter
     const accessoriesToRegister: any[] = []
-    for (const { created, d, type, useMatter, matterAvailable } of createdDevices) {
+    const externalAccessoriesToPublish: any[] = []
+    for (const { created, d, type, useMatter, matterAvailable, externalPublishProtocol } of createdDevices) {
       // Only register accessories where Matter is enabled and supported
       if (!useMatter) {
         // Log reason for skipping registration
@@ -237,7 +239,11 @@ export class SwitchBotMatterPlatform {
             handlers: createdDesc.handlers || createMatterHandlers(this.log, d.id, type, (this.config as any)?._client) || undefined,
             context: { deviceId: d.id, type, created: true },
           }
-          accessoriesToRegister.push(accessory)
+          if (externalPublishProtocol === 'matter') {
+            externalAccessoriesToPublish.push(accessory)
+          } else {
+            accessoriesToRegister.push(accessory)
+          }
           this.accessories.set(uuid, accessory)
         } else {
           // Ensure context and update properties for restored accessory
@@ -260,7 +266,11 @@ export class SwitchBotMatterPlatform {
           accessory.handlers = createdDesc.handlers || createMatterHandlers(this.log, d.id, type, (this.config as any)?._client) || undefined
           accessory.displayName = createdDesc.name || d.name || type
           accessory.UUID = accessory.UUID || accessory.uuid || uuid
-          accessoriesToRegister.push(accessory)
+          if (externalPublishProtocol === 'matter') {
+            externalAccessoriesToPublish.push(accessory)
+          } else {
+            accessoriesToRegister.push(accessory)
+          }
           this.accessories.set(accessory.UUID || uuid, accessory)
         }
         this.log.info(`Created/updated Matter accessory ${d.id} (${type})`)
@@ -278,6 +288,23 @@ export class SwitchBotMatterPlatform {
     } else {
       this.log.info('No Matter accessories to register')
     }
+    if (externalAccessoriesToPublish.length > 0) {
+      try {
+        if (typeof matterApi.publishExternalAccessories === 'function') {
+          await matterApi.publishExternalAccessories(PLUGIN_NAME, externalAccessoriesToPublish)
+          this.log.info(`Published ${externalAccessoriesToPublish.length} Matter external accessory(ies) with Homebridge`)
+        } else if (typeof matterApi.registerExternalAccessories === 'function') {
+          await matterApi.registerExternalAccessories(PLUGIN_NAME, PLATFORM_NAME, externalAccessoriesToPublish)
+          this.log.info(`Registered ${externalAccessoriesToPublish.length} Matter external accessory(ies) with Homebridge`)
+        } else {
+          this.log.warn('Matter external accessory publishing API not available; falling back to regular platform registration')
+          await matterApi.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, externalAccessoriesToPublish)
+          this.log.info(`Registered ${externalAccessoriesToPublish.length} Matter accessory(ies) as fallback (external publishing unavailable)`)
+        }
+      } catch (e) {
+        this.log.warn('Failed to publish/register Matter external accessories', e)
+      }
+    }
   }
 
   /**
@@ -312,6 +339,7 @@ export class SwitchBotMatterPlatform {
       id: d.deviceId ?? d.id,
       type: d.configDeviceType ?? d.type,
       name: d.configDeviceName ?? d.name,
+      externalPublishProtocol: resolveExternalPublishProtocol(d),
     })))
   }
 

package/src/homebridge-ui/public/js/api.ts

@@ -189,7 +189,19 @@ export async function addDevice(
   deviceId: string,
   name: string,
   type: string,
-  options?: { address?: string, model?: string, rssi?: number, encryptionKey?: string, keyId?: string },
+  options?: {
+    address?: string
+    model?: string
+    rssi?: number
+    connectionPreference?: string
+    externalPublishProtocol?: string
+    room?: string
+    encryptionKey?: string
+    keyId?: string
+    refreshRate?: number
+    blePollingEnabled?: boolean
+    blePollIntervalMs?: number
+  },
 ): Promise<any> {
   if (typeof homebridge.getPluginConfig !== 'function' || typeof homebridge.updatePluginConfig !== 'function') {
     throw new TypeError('Homebridge UI API not available')
@@ -224,6 +236,24 @@ export async function addDevice(
   if (options?.keyId) {
     newDevice.keyId = options.keyId
   }
+  if (options?.connectionPreference) {
+    newDevice.connectionPreference = options.connectionPreference
+  }
+  if (options?.externalPublishProtocol) {
+    newDevice.externalPublishProtocol = options.externalPublishProtocol
+  }
+  if (options?.room) {
+    newDevice.room = options.room
+  }
+  if (typeof options?.refreshRate === 'number' && Number.isFinite(options.refreshRate)) {
+    newDevice.refreshRate = options.refreshRate
+  }
+  if (typeof options?.blePollingEnabled === 'boolean') {
+    newDevice.blePollingEnabled = options.blePollingEnabled
+  }
+  if (typeof options?.blePollIntervalMs === 'number' && Number.isFinite(options.blePollIntervalMs)) {
+    newDevice.blePollIntervalMs = options.blePollIntervalMs
+  }
   config.devices.push(newDevice)
   await homebridge.updatePluginConfig(configArr)
   if (typeof homebridge.savePluginConfig === 'function') {

package/src/homebridge-ui/public/js/devices.ts

@@ -26,8 +26,14 @@ export async function addDeviceToConfig(device: any, options: { refresh?: boolea
       address: importValues.address,
       model: device.model,
       rssi: device.rssi,
+      connectionPreference: importValues.connectionPreference,
+      externalPublishProtocol: importValues.externalPublishProtocol,
+      room: importValues.room,
       encryptionKey: importValues.encryptionKey,
       keyId: importValues.keyId,
+      refreshRate: importValues.refreshRate,
+      blePollingEnabled: importValues.blePollingEnabled,
+      blePollIntervalMs: importValues.blePollIntervalMs,
     })
     uiLog.info('Add device response:', resp)
 

package/src/homebridge-ui/public/js/modals.ts

@@ -6,6 +6,7 @@ export type ImportDiscoveredDeviceResult = {
   configDeviceType: string
   address?: string
   connectionPreference?: string
+  externalPublishProtocol?: string
   room?: string
   encryptionKey?: string
   keyId?: string
@@ -154,6 +155,30 @@ export async function importDiscoveredDevice(device: any): Promise<ImportDiscove
       connectionPrefSelect.appendChild(opt)
     })
 
+    // --- External Publish Protocol ---
+    const externalPublishLabel = document.createElement('label')
+    externalPublishLabel.textContent = 'Publish as External Device'
+    externalPublishLabel.style.display = 'block'
+    externalPublishLabel.style.marginBottom = '6px'
+    externalPublishLabel.style.fontWeight = '500'
+    externalPublishLabel.style.fontSize = '12px'
+    externalPublishLabel.style.color = '#6b7280'
+
+    const externalPublishSelect = document.createElement('select')
+    externalPublishSelect.style.width = '100%'
+    externalPublishSelect.style.marginBottom = '12px'
+    externalPublishSelect.style.padding = '8px 10px'
+    externalPublishSelect.style.borderRadius = '6px'
+    externalPublishSelect.style.fontSize = '14px'
+    externalPublishSelect.style.boxSizing = 'border-box'
+    ;['none', 'hap', 'matter'].forEach((val) => {
+      const opt = document.createElement('option')
+      opt.value = val
+      opt.text = val === 'none' ? 'None' : val.toUpperCase()
+      opt.selected = (device.externalPublishProtocol || 'none') === val
+      externalPublishSelect.appendChild(opt)
+    })
+
     // --- Room ---
     const roomLabel = document.createElement('label')
     roomLabel.textContent = 'Room'
@@ -308,6 +333,7 @@ export async function importDiscoveredDevice(device: any): Promise<ImportDiscove
         configDeviceType: typeSelect.value || device.type,
         address: macInput.value || undefined,
         connectionPreference: connectionPrefSelect.value || undefined,
+        externalPublishProtocol: externalPublishSelect.value || 'none',
         room: roomInput.value || undefined,
         encryptionKey: encryptionKeyInput.value || undefined,
         keyId: keyIdInput.value || undefined,
@@ -331,6 +357,8 @@ export async function importDiscoveredDevice(device: any): Promise<ImportDiscove
     contentDiv.appendChild(typeSelect)
     contentDiv.appendChild(connectionPrefLabel)
     contentDiv.appendChild(connectionPrefSelect)
+    contentDiv.appendChild(externalPublishLabel)
+    contentDiv.appendChild(externalPublishSelect)
     contentDiv.appendChild(roomLabel)
     contentDiv.appendChild(roomInput)
     contentDiv.appendChild(macLabel)
@@ -573,6 +601,30 @@ export async function editDevice(device: any): Promise<void> {
     connectionPrefSelect.appendChild(opt)
   })
 
+  // --- External Publish Protocol ---
+  const externalPublishLabel = document.createElement('label')
+  externalPublishLabel.textContent = 'Publish as External Device'
+  externalPublishLabel.style.display = 'block'
+  externalPublishLabel.style.marginBottom = '6px'
+  externalPublishLabel.style.fontWeight = '500'
+  externalPublishLabel.style.fontSize = '12px'
+  externalPublishLabel.style.color = '#6b7280'
+
+  const externalPublishSelect = document.createElement('select')
+  externalPublishSelect.style.width = '100%'
+  externalPublishSelect.style.marginBottom = '12px'
+  externalPublishSelect.style.padding = '8px 10px'
+  externalPublishSelect.style.borderRadius = '6px'
+  externalPublishSelect.style.fontSize = '14px'
+  externalPublishSelect.style.boxSizing = 'border-box'
+  ;['none', 'hap', 'matter'].forEach((val) => {
+    const opt = document.createElement('option')
+    opt.value = val
+    opt.text = val === 'none' ? 'None' : val.toUpperCase()
+    opt.selected = (device.externalPublishProtocol || 'none') === val
+    externalPublishSelect.appendChild(opt)
+  })
+
   // --- Room ---
   const roomLabel = document.createElement('label')
   roomLabel.textContent = 'Room'
@@ -674,6 +726,7 @@ export async function editDevice(device: any): Promise<void> {
         configDeviceName: nameInput.value || undefined,
         configDeviceType: typeSelect.value,
         connectionPreference: connectionPrefSelect.value,
+        externalPublishProtocol: externalPublishSelect.value,
         room: roomInput.value || undefined,
         encryptionKey: encryptionKeyInput.value || undefined,
         keyId: keyIdInput.value || undefined,
@@ -690,6 +743,9 @@ export async function editDevice(device: any): Promise<void> {
       if (params.room !== undefined) {
         options.room = params.room
       }
+      if (params.externalPublishProtocol !== undefined) {
+        options.externalPublishProtocol = params.externalPublishProtocol
+      }
       if (params.encryptionKey !== undefined) {
         options.encryptionKey = params.encryptionKey
       }
@@ -739,6 +795,8 @@ export async function editDevice(device: any): Promise<void> {
   contentDiv.appendChild(typeSelect)
   contentDiv.appendChild(connectionPrefLabel)
   contentDiv.appendChild(connectionPrefSelect)
+  contentDiv.appendChild(externalPublishLabel)
+  contentDiv.appendChild(externalPublishSelect)
   contentDiv.appendChild(roomLabel)
   contentDiv.appendChild(roomInput)
   contentDiv.appendChild(encryptionKeyLabel)

package/src/homebridge-ui/public/js/render.ts

@@ -1011,8 +1011,9 @@ export function renderDeviceList(list: any[]): void {
 
     const typeText = d.type ? `type: ${d.type}` : ''
     const connText = d.connectionPreference ? `conn: ${d.connectionPreference}` : ''
+    const extText = d.externalPublishProtocol && d.externalPublishProtocol !== 'none' ? `external: ${d.externalPublishProtocol}` : ''
     const roomText = d.room ? `room: ${d.room}` : ''
-    meta.textContent = [typeText, connText, roomText].filter(Boolean).join(' | ')
+    meta.textContent = [typeText, connText, extText, roomText].filter(Boolean).join(' | ')
 
     info.appendChild(nameContainer)
     info.appendChild(meta)

package/src/settings.ts

@@ -1,12 +1,24 @@
 export const PLUGIN_NAME = '@switchbot/homebridge-switchbot'
 export const PLATFORM_NAME = 'SwitchBot'
 
+export interface SwitchBotDeviceConfig {
+  deviceId?: string
+  id?: string
+  configDeviceName?: string
+  name?: string
+  configDeviceType?: string
+  type?: string
+  externalPublishProtocol?: 'none' | 'hap' | 'matter'
+  [key: string]: any
+}
+
 export interface SwitchBotPluginConfig {
   openApiToken?: string
   openApiSecret?: string
   preferMatter?: boolean
   enableMatter?: boolean
   enableBLE?: boolean // Enable or disable BLE support
+  devices?: SwitchBotDeviceConfig[]
   // other plugin-specific configuration
   [key: string]: any
 }