@switchbot/homebridge-switchbot

<!DOCTYPE html><html class="default" lang="en" data-base="./"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@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"><h1>@switchbot/homebridge-switchbot</h1></div><div class="tsd-panel tsd-typography"><span align="center"> <p><a href="https://github.com/homebridge/verified/blob/master/verified-plugins.json"><img alt="homebridge-verified" src="https://raw.githubusercontent.com/OpenWonderLabs/homebridge-switchbot/latest/branding/Homebridge_x_SwitchBot.svg?sanitize=true" width="350px"></a></p> <h1 id="switchbothomebridge-switchbot" class="tsd-anchor-link">@switchbot/homebridge-switchbot<a href="#switchbothomebridge-switchbot" 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></h1> <p><a href="https://www.npmjs.com/package/@switchbot/homebridge-switchbot"><img src="https://badgen.net/npm/v/@switchbot/homebridge-switchbot" alt="npm version"></a> <a href="https://www.npmjs.com/package/@switchbot/homebridge-switchbot"><img src="https://badgen.net/npm/dt/@switchbot/homebridge-switchbot" alt="npm downloads"></a> <a href="https://discord.gg/5wYTbwP4ha"><img src="https://badgen.net/discord/online-members/5wYTbwP4ha?icon=discord&label=discord" alt="discord-switchbot"></a></p> <p>The Homebridge <a href="https://www.switch-bot.com">SwitchBot</a> plugin allows you to access your SwitchBot Device(s) from HomeKit with <a href="https://homebridge.io">Homebridge</a>. </p> </span> <h2 id="installation" class="tsd-anchor-link">Installation<a href="#installation" 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> <ol> <li>Search for "SwitchBot" on the plugin screen of <a href="https://github.com/oznu/homebridge-config-ui-x">Homebridge Config UI X</a></li> <li>Find: <code>@switchbot/homebridge-switchbot</code> <ul> <li>See noble <a href="https://github.com/abandonware/noble#prerequisites">prerequisites</a> for your OS. (This is used for BLE connection.)</li> </ul> </li> <li>Click <strong>Install</strong></li> </ol> <h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <h3 id="openapi-pollingrate-advanced-settings-ui" class="tsd-anchor-link">OpenAPI Polling/Rate Advanced Settings (UI)<a href="#openapi-pollingrate-advanced-settings-ui" 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>You can now configure global OpenAPI polling and rate-limiting options directly from the Homebridge UI:</p> <ul> <li>Go to the SwitchBot plugin settings in Homebridge Config UI X.</li> <li>Scroll to the <strong>Advanced Settings</strong> section at the bottom of the page.</li> <li>Adjust the following options as needed: <ul> <li><strong>OpenAPI Polling Interval (seconds):</strong> How often to poll devices via OpenAPI for status. Default: 300 (5 min). Min: 30. Can be overridden per device.</li> <li><strong>Enable Batched OpenAPI Polling:</strong> Poll all OpenAPI devices in a single batch at the configured interval. Devices with per-device refreshRate are excluded from the batch.</li> <li><strong>OpenAPI Batch Polling Interval (seconds):</strong> Interval for batched OpenAPI polling. Falls back to OpenAPI Polling Interval if not set. Default: 300.</li> <li><strong>OpenAPI Daily Request Limit:</strong> Maximum OpenAPI requests per day allowed by the plugin. Default: 10000.</li> <li><strong>OpenAPI Reserve for Commands:</strong> Requests reserved for user actions. When remaining budget reaches this value, background polling pauses. Default: 1000.</li> <li><strong>Reset OpenAPI Counter at Local Midnight:</strong> If true, resets the daily OpenAPI request counter at local midnight. If false, resets at UTC midnight.</li> <li><strong>Only Allow Webhooks on Reserve:</strong> When remaining OpenAPI budget reaches the reserve, only webhooks and user commands are allowed. Background polling/discovery pauses.</li> <li><strong>OpenAPI Batch Concurrency:</strong> Maximum number of parallel OpenAPI status calls during a batch. Default: 5.</li> <li><strong>OpenAPI Batch Jitter (seconds):</strong> Random startup delay before the first batch to reduce synchronized spikes. Default: 0.</li> </ul> </li> </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>  <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> <ol> <li>Download SwitchBot App on App Store or Google Play Store</li> <li>Register a SwitchBot account and log in into your account</li> <li>Generate an Token within the App <ul> <li>Click Bottom Profile Tab</li> <li>Click Preference</li> <li>Click App version 10 Times, this will enable Developer Options</li> <li>Click Developer Options</li> <li>Click Copy <code>token</code> to Clipboard</li> </ul> </li> <li>Input your <code>token</code> into the config parameter</li> <li>Generate an Secret within the App <ul> <li>Click Bottom Profile Tab</li> <li>Click Preference</li> <li>Click App version 10 Times, this will enable Developer Options</li> <li>Click Developer Options</li> <li>Click Copy <code>secret</code> to Clipboard</li> </ul> </li> <li>Input your <code>secret</code> into the config parameter</li> </ol> </li> <li> <h3 id="if-using-ble-connection" class="tsd-anchor-link">If using BLE Connection<a href="#if-using-ble-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> <ol> <li>Download SwitchBot App on App Store or Google Play Store</li> <li>Register a SwitchBot account and log in into your account</li> <li>Click on Device wanting to connect too plugin <ul> <li>Click the Settings Gear</li> <li>Click Device Info</li> <li>Copy BLE Mac aka <code>deviceId</code></li> </ul> </li> <li>Input your <code>deviceId</code> into the Device Config</li> </ol> </li> </ul> <h2 id="troubleshooting" class="tsd-anchor-link">Troubleshooting<a href="#troubleshooting" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <ul> <li> <h3 id="if-using-linux-raspberry-pi-os" class="tsd-anchor-link">If using Linux / Raspberry Pi OS<a href="#if-using-linux-raspberry-pi-os" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3> <ol> <li> <p><code>bluetoothctl</code> must be installed on the device, otherwise it cannot communicate via Bluetooth. Enable it with <code>sudo bluetoothctl power on</code>.</p> </li> <li> <p>If errors occur, while enabling it, restart the process:</p> <ul> <li><code>rfkill block bluetooth</code></li> <li><code>rfkill unblock bluetooth</code></li> </ul> </li> <li> <p>Also make sure, that the computer can discover the SwitchBot device:</p> <ul> <li><code>sudo bluetoothctl</code></li> <li><code>scan on</code></li> </ul> <p>This lists all discovered Bluetooth devices. The BLE address of the SwitchBot device should be included in this list, otherwise your computer does not discover it.</p> </li> </ol> </li> <li> <h3 id="if-using-macos" class="tsd-anchor-link">If using MacOS<a href="#if-using-macos" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3> <ol> <li>Manually grant Bluetooth access in System Settings UI for <code>Security & Privacy -> Privacy</code> to the node executable, eg <code>/usr/local/bin/node</code> <img src="media/security-privacy-bluetooth.png" alt="Security & Privacy -> Privacy"> (This is what is intended in documentation for the noble bluetooth package <a href="https://github.com/abandonware/noble#prerequisites">prerequisites</a> by "Add terminal app", 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">.<</span><span class="hl-3">anonymous</span><span class="hl-1">> (</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> </ul> <h2 id="supported-switchbot-devices" class="tsd-anchor-link">Supported SwitchBot Devices<a href="#supported-switchbot-devices" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <ul> <li><a href="https://www.switch-bot.com/products/switchbot-smart-humidifier">SwitchBot Humidifier</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections <ul> <li>Can Push Updates over OpenAPI</li> <li>Can Receive Updates over BLE and OpenAPI</li> </ul> </li> </ul> </li> <li><a href="https://www.switch-bot.com/products/switchbot-evaporative-humidifier-auto-refill">SwitchBot Evaporative Humidifier (Auto-refill)</a></li> <li><a href="https://www.switch-bot.com/products/switchbot-meter">SwitchBot Meter</a></li> <li><a href="https://www.switch-bot.com/products/switchbot-meter-plus">SwitchBot Meter Plus (US)</a></li> <li><a href="https://www.switchbot.jp/products/switchbot-meter-plus">SwitchBot Meter Plus (JP)</a></li> <li><a href="https://www.switch-bot.com/products/switchbot-indoor-outdoor-thermo-hygrometer">SwitchBot Indoor/Outdoor Thermo-Hygrometer</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> </ul> </li> <li>If using Bluetooth Low Energy (BLE) only: <ul> <li>Must supply <code>deviceId</code> & <code>deviceName</code> to Device Config</li> <li>Check <code>Enable Bluetooth Low Energy (BLE) Connection</code> on Device Config</li> </ul> </li> </ul> </li> <li><a href="https://www.switch-bot.com/products/motion-sensor">SwitchBot Motion Sensor</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> </ul> </li> <li>If using Bluetooth Low Energy (BLE) only: <ul> <li>Must supply <code>deviceId</code> & <code>deviceName</code> to Device Config</li> <li>Check <code>Enable Bluetooth Low Energy (BLE) Connection</code> on Device Config</li> </ul> </li> </ul> </li> <li><a href="https://www.switch-bot.com/products/contact-sensor">SwitchBot Contact Sensor</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> </ul> </li> <li>If using Bluetooth Low Energy (BLE) only: <ul> <li>Must supply <code>deviceId</code> & <code>deviceName</code> to Device Config</li> <li>Check <code>Enable Bluetooth Low Energy (BLE) Connection</code> on Device Config</li> </ul> </li> </ul> </li> <li><a href="https://www.switch-bot.com/products/switchbot-curtain">SwitchBot Curtain</a></li> <li><a href="https://www.switch-bot.com/products/switchbot-curtain-3">SwitchBot Curtain 3</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> </ul> </li> <li>If using Bluetooth Low Energy (BLE) only: <ul> <li>Must supply <code>deviceId</code> & <code>deviceName</code> to Device Config</li> <li>Check <code>Enable Bluetooth Low Energy (BLE) Connection</code> on Device Config</li> </ul> </li> </ul> </li> <li><a href="https://us.switch-bot.com/products/switchbot-blind-tilt">SwitchBot Blind Tilt</a> <ul> <li>Supports OpenAPI & partial Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> </ul> </li> </ul> </li> <li><a href="https://www.switch-bot.com/products/switchbot-color-bulb">SwitchBot Bulb</a></li> <li><a href="https://www.switchbot.jp/collections/all/products/switchbot-ceiling-light">SwitchBot Ceiling Light</a></li> <li><a href="https://www.switchbot.jp/collections/all/products/switchbot-ceiling-light">SwitchBot Ceiling Light Pro</a></li> <li><a href="https://www.switch-bot.com/products/switchbot-light-strip">SwitchBot Light Strip</a> <ul> <li>Supports OpenAPI & partial Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> </ul> </li> </ul> </li> <li><a href="https://us.switch-bot.com/products/switchbot-lock">SwitchBot Lock</a></li> <li><a href="https://www.switchbot.jp/products/switchbot-lock-pro">SwitchBot Lock Pro</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> </ul> </li> </ul> </li> <li>US: <a href="https://www.switch-bot.com/products/switchbot-mini-robot-vacuum-k10">SwitchBot Mini Robot Vacuum K10+</a></li> <li>US: <a href="https://www.switch-bot.com/products/switchbot-floor-cleaning-robot-s10">SwitchBot Floor Cleaning Robot S10</a></li> <li>JP: <a href="https://www.switchbot.jp/products/switchbot-robot-vacuum-cleaner">SwitchBot Robot Vacuum Cleaner S1</a></li> <li>JP: <a href="https://www.switchbot.jp/products/switchbot-robot-vacuum-cleaner">SwitchBot Robot Vacuum Cleaner S1 Plus</a> <ul> <li>Supports OpenAPI Connection Only</li> </ul> </li> <li><a href="https://www.switch-bot.com/products/switchbot-plug">SwitchBot Plug</a></li> <li><a href="https://www.switch-bot.com/products/switchbot-plug-mini">SwitchBot Plug Mini (US)</a></li> <li><a href="https://www.switchbot.jp/products/switchbot-plug-mini">SwitchBot Plug Mini (JP)</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> </ul> </li> </ul> </li> <li><a href="https://www.switch-bot.com/products/switchbot-bot">SwitchBot Bot</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections</li> <li>If using OpenAPI: <ul> <li><a href="https://www.switch-bot.com/products/switchbot-hub-mini">SwitchBot Hub Mini</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, or <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> Required</li> <li>Enable Cloud Services for Device on SwitchBot App</li> <li>You must set your Bot's Device ID for either Press Mode or Switch Mode in Plugin Config (SwitchBot Device Settings > Bot Settings) <ul> <li>Press Mode - Turns on then instantly turn it off</li> <li>Switch Mode - Turns on and keep it on until it is turned off <ul> <li>This can get out of sync, since API doesn't give me a status</li> <li>To Correct you must go into the SwitchBot App and correct the status of either <code>On</code> or <code>Off</code></li> </ul> </li> </ul> </li> </ul> </li> <li>If using Bluetooth Low Energy (BLE) only: <ul> <li>Must supply <code>deviceId</code> & <code>deviceName</code> to Device Config</li> <li>Check <code>Enable Bluetooth Low Energy (BLE) Connection</code> on Device Config</li> </ul> </li> </ul> </li> <li><a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections <ul> <li>Enables Humidity, Temperature, and Light Sensor</li> </ul> </li> </ul> </li> <li><a href="https://us.switch-bot.com/products/switchbot-hub-mini-2">SwitchBot Hub Mini 2</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections <ul> <li>Enables Humidity, Temperature, and Light Sensor</li> </ul> </li> </ul> </li> <li><a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections <ul> <li>Enables Humidity, Temperature, and Light Sensor</li> </ul> </li> </ul> </li> <li><a href="https://us.switch-bot.com/products/switchbot-battery-circulator-fan">SwitchBot Battery Circulator Fan</a> <ul> <li>Supports OpenAPI Connection Only</li> </ul> </li> <li><a href="https://us.switch-bot.com/products/switchbot-water-leak-detector">SwitchBot Water Leak Detector</a> <ul> <li>Supports OpenAPI & Bluetooth Low Energy (BLE) Connections</li> </ul> </li> </ul> <h2 id="ble-encryption-support" class="tsd-anchor-link">BLE Encryption Support<a href="#ble-encryption-support" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <h3 id="ble-encryption-key-and-key-id" class="tsd-anchor-link">BLE Encryption Key and Key ID<a href="#ble-encryption-key-and-key-id" 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>Some SwitchBot devices (notably newer locks, curtains, and select sensors) require a BLE encryption key and keyId for secure Bluetooth communication. This plugin supports configuring these fields for each device.</p> <h4 id="how-to-obtain-ble-encryption-key-and-key-id" class="tsd-anchor-link">How to Obtain BLE Encryption Key and Key ID<a href="#how-to-obtain-ble-encryption-key-and-key-id" 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> <ol> <li><strong>Open the SwitchBot App</strong> and select your device.</li> <li>Go to <strong>Device Settings</strong> (gear icon).</li> <li>Tap <strong>Device Info</strong>.</li> <li>If your device supports BLE encryption, you will see fields for <strong>Encryption Key</strong> and <strong>Key ID</strong>. (If not visible, your device may not require encryption or may need a firmware update.)</li> <li>Copy the <strong>Encryption Key</strong> and <strong>Key ID</strong> values.</li> </ol> <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">"deviceId"</span><span class="hl-1">: </span><span class="hl-7">"E7F8A1B2C3D4"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">"deviceName"</span><span class="hl-1">: </span><span class="hl-7">"SwitchBot Lock"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">"enableBLE"</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">"encryptionKey"</span><span class="hl-1">: </span><span class="hl-7">"0123456789abcdef0123456789abcdef"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">"keyId"</span><span class="hl-1">: </span><span class="hl-7">"01"</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> <ul> <li>SwitchBot Lock (and Lock Pro)</li> <li>SwitchBot Curtain 3 (and some Curtain 2 with updated firmware)</li> <li>Some sensors and new device models (see device info in app)</li> </ul> <p>If you are unsure, check your device's info in the SwitchBot app. If the fields are present, copy them into the plugin config.</p> <p><strong>Note:</strong> If you enter an incorrect key or keyId, BLE communication will fail for that device. Double-check values if you encounter connection issues.</p> <hr> <h2 id="supported-ir-devices" class="tsd-anchor-link">Supported IR Devices<a href="#supported-ir-devices" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <h3 id="all-ir-devices-require-switchbot-hub-2-switchbot-hub-mini-2-switchbot-hub-3-or-hub-mini" class="tsd-anchor-link"><em>(All IR Devices require <a href="https://us.switch-bot.com/products/switchbot-hub-2">SwitchBot Hub 2</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-mini-2">SwitchBot Hub Mini 2</a>, <a href="https://us.switch-bot.com/products/switchbot-hub-3">SwitchBot Hub 3</a>, or <a href="https://www.switch-bot.com/products/switchbot-hub-mini">Hub Mini</a>)</em><a href="#all-ir-devices-require-switchbot-hub-2-switchbot-hub-mini-2-switchbot-hub-3-or-hub-mini" 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> <ul> <li>TV <ul> <li>Allows for On/Off and Volume Controls</li> <li>Optional Disable Sending Power Command</li> </ul> </li> <li>Projector (Displayed as TV) <ul> <li>Allows for On/Off and Volume Controls</li> </ul> </li> <li>Set Top Box (Displayed as Set Top Box) <ul> <li>Allows for On/Off and Volume Controls</li> </ul> </li> <li>DVD (Displayed as Set Top Box) <ul> <li>Allows for On/Off and Volume Controls</li> </ul> </li> <li>Streamer (Displayed as Streaming Stick) <ul> <li>Allows for On/Off and Volume Controls</li> </ul> </li> <li>Speaker (Displayed as Speaker) <ul> <li>Allows for On/Off and Volume Controls</li> </ul> </li> <li>Fans <ul> <li>Allows for On/Off Controls</li> <li>Optional Rotation Speed</li> <li>Optional Swing Mode</li> </ul> </li> <li>Lights <ul> <li>Allows for On/Off Controls</li> </ul> </li> <li>Air Purifiers <ul> <li>Allows for On/Off Controls</li> </ul> </li> <li>Air Conditioners <ul> <li>Allows for On/Off, Tempeture, and Mode Controls</li> <li>Optional Disable Auto Mode</li> </ul> </li> <li>Cameras <ul> <li>Allows for On/Off Controls</li> </ul> </li> <li>Vacuum Cleaners <ul> <li>Allows for On/Off Controls</li> </ul> </li> <li>Water Heaters <ul> <li>Allows for On/Off Controls</li> </ul> </li> <li>Others <ul> <li>Option to Display as differenet Device Type <ul> <li>Supports Fan Device Type</li> </ul> </li> <li>Allows for On/Off Controls</li> </ul> </li> </ul> <h2 id="matter-platform" class="tsd-anchor-link">Matter Platform<a href="#matter-platform" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <h3 id="batched-refresh-and-api-load-control" class="tsd-anchor-link">Batched refresh and API load control<a href="#batched-refresh-and-api-load-control" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>By default, the Matter platform uses a single batched refresh to update device status. You can tune or override this behavior with the following options under <code>options</code>:</p> <ul> <li><code>matterBatchEnabled</code> (boolean, default true): enable/disable platform-level batched refresh. Devices with a per-device <code>refreshRate</code> still run their own timers.</li> <li><code>matterBatchRefreshRate</code> (number, seconds): batch interval (falls back to <code>options.refreshRate</code>, then 300 if not set).</li> <li><code>matterBatchConcurrency</code> (number): limit of parallel OpenAPI status calls during a batch (default 5).</li> <li><code>matterBatchJitter</code> (number, seconds): random startup delay before the first batch to reduce synchronized spikes.</li> </ul> <p>Device-level override:</p> <ul> <li>If a device sets <code>refreshRate</code> in its config, it uses a per-device timer and is excluded from the platform batch.</li> </ul> <p>Reliability and rate-limiting:</p> <ul> <li>Each device status call retries with exponential backoff on non-success responses.</li> <li>After exhausting retries, the device enters a short cooldown before being retried; cooldowns are persisted across restarts.</li> <li>The batch worklist is randomized every cycle to further distribute API load.</li> </ul> <p>These controls keep API usage smooth and predictable while preserving per-device control when needed.</p> <h2 id="whats-new-with-node-switchbot-v400" class="tsd-anchor-link">What's new with node-switchbot v4.0.0<a href="#whats-new-with-node-switchbot-v400" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <ul> <li> <p>Matter-first: when Homebridge Matter is available the plugin now prefers registering Matter accessories (with HAP fallback).</p> </li> <li> <p>Hybrid client: the plugin uses <code>node-switchbot@^4.0.0</code> with BLE + OpenAPI discovery and OpenAPI fallback.</p> </li> <li> <p>OpenAPI credentials: cloud discovery and cloud fallback paths require both <code>openApiToken</code> and <code>openApiSecret</code>.</p> </li> <li> <p>UI always served: the plugin UI is packaged into <code>dist/homebridge-ui</code> and is always served when Homebridge UI support is present; there is no platform-level opt-out.</p> </li> <li> <p>OpenAPI hardening: OpenAPI calls have AbortController timeouts, jittered exponential backoff, per-device retry limits and cooldowns, and safe response parsing for resilient behavior.</p> </li> <li> <p>v4 resilience enabled in discovery: plugin discovery enables retry, circuit-breaker, and connection-intelligence flags from <code>node-switchbot</code> v4.</p> </li> <li> <p>Write coalescing (debounce): command writes to the same device are coalesced by default to avoid command floods. Configure with <code>writeDebounceMs</code> (milliseconds, default 100). Set to <code>0</code> to disable coalescing.</p> </li> </ul> <p>See <code>MIGRATION.md</code> for migration notes and recommended upgrade steps.</p> <h2 id="openapi-rate-limiting-and-daily-budget" class="tsd-anchor-link">OpenAPI rate limiting and daily budget<a href="#openapi-rate-limiting-and-daily-budget" 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> <p>To prevent hitting SwitchBot’s daily OpenAPI limit, the plugin provides several platform-level options under <code>options</code>:</p> <ul> <li><code>dailyApiLimit</code> (number, default 10000): maximum OpenAPI requests per day that the plugin will allow.</li> <li><code>dailyApiReserveForCommands</code> (number, default 1000): requests reserved for user actions so background polling pauses before the hard limit.</li> <li><code>webhookOnlyOnReserve</code> (boolean, default false): when remaining budget reaches the reserve, pause background polling/discovery; webhooks and commands continue until the hard limit.</li> <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">"options"</span><span class="hl-1">: {</span><br/><span class="hl-1"> </span><span class="hl-6">"dailyApiLimit"</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">"dailyApiReserveForCommands"</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">"webhookOnlyOnReserve"</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">"dailyApiResetLocalMidnight"</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> <ul> <li><a href="https://github.com/OpenWonderLabs/node-switchbot">OpenWonderLabs/node-switchbot</a> <ul> <li><a href="https://github.com/OpenWonderLabs/SwitchBotAPI">OpenWonderLabs/SwitchBotAPI</a></li> <li><a href="https://github.com/OpenWonderLabs/SwitchBotAPI-BLE">OpenWonderLabs/SwitchBotAPI-BLE</a></li> </ul> </li> </ul> <h2 id="development-tests" class="tsd-anchor-link">Development / Tests<a href="#development-tests" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <ul> <li> <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> </code><button type="button">Copy</button></pre> </li> <li> <p>Notes:</p> <ul> <li>Added Lock Ultra (Cloud + BLE) support with <code>node-switchbot</code> v4.</li> </ul> </li> </ul> <h2 id="community" class="tsd-anchor-link">Community<a href="#community" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2> <ul> <li><a href="https://www.switch-bot.com/">SwitchBot (Official website)</a></li> <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'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>