{"id":14986739,"url":"https://github.com/openwonderlabs/homebridge-switchbot","last_synced_at":"2026-04-11T16:12:51.721Z","repository":{"id":37086313,"uuid":"390774973","full_name":"OpenWonderLabs/homebridge-switchbot","owner":"OpenWonderLabs","description":"The Homebridge SwitchBot plugin allows you to access your SwitchBot Device(s) from HomeKit. Homebridge.","archived":false,"fork":false,"pushed_at":"2025-04-13T11:46:21.000Z","size":2838,"stargazers_count":266,"open_issues_count":29,"forks_count":61,"subscribers_count":5,"default_branch":"latest","last_synced_at":"2025-04-15T02:14:15.207Z","etag":null,"topics":["ble","homebridge","homebridge-plugin","nodejs","openapi","switchbot"],"latest_commit_sha":null,"homepage":"https://openwonderlabs.github.io/homebridge-switchbot/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenWonderLabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"donavanbecker","custom":"paypal.me/DonavanBecker"}},"created_at":"2021-07-29T15:48:42.000Z","updated_at":"2025-04-14T17:53:04.000Z","dependencies_parsed_at":"2022-07-13T15:29:45.199Z","dependency_job_id":"e597dcd5-963b-4727-a139-aff6f96d7abb","html_url":"https://github.com/OpenWonderLabs/homebridge-switchbot","commit_stats":{"total_commits":131,"total_committers":5,"mean_commits":26.2,"dds":"0.36641221374045807","last_synced_commit":"3ea2fde9ae7130c57c25803be696879cbbbfd601"},"previous_names":[],"tags_count":152,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fhomebridge-switchbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fhomebridge-switchbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fhomebridge-switchbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fhomebridge-switchbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenWonderLabs","download_url":"https://codeload.github.com/OpenWonderLabs/homebridge-switchbot/tar.gz/refs/heads/latest","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991559,"owners_count":21194894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","homebridge","homebridge-plugin","nodejs","openapi","switchbot"],"created_at":"2024-09-24T14:13:26.968Z","updated_at":"2026-03-05T06:08:09.913Z","avatar_url":"https://github.com/OpenWonderLabs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/donavanbecker","paypal.me/DonavanBecker"],"categories":[],"sub_categories":[],"readme":"\u003cspan align=\"center\"\u003e\n\n\u003ca href=\"https://github.com/homebridge/verified/blob/master/verified-plugins.json\"\u003e\u003cimg alt=\"homebridge-verified\" src=\"https://raw.githubusercontent.com/OpenWonderLabs/homebridge-switchbot/latest/branding/Homebridge_x_SwitchBot.svg?sanitize=true\" width=\"350px\"\u003e\u003c/a\u003e\n\n# @switchbot/homebridge-switchbot\n\n[![npm version](https://badgen.net/npm/v/@switchbot/homebridge-switchbot)](https://www.npmjs.com/package/@switchbot/homebridge-switchbot)\n[![npm downloads](https://badgen.net/npm/dt/@switchbot/homebridge-switchbot)](https://www.npmjs.com/package/@switchbot/homebridge-switchbot)\n[![discord-switchbot](https://badgen.net/discord/online-members/5wYTbwP4ha?icon=discord\u0026label=discord)](https://discord.gg/5wYTbwP4ha)\n\n\u003cp\u003eThe Homebridge \u003ca href=\"https://www.switch-bot.com\"\u003eSwitchBot\u003c/a\u003e plugin allows you to access your SwitchBot Device(s) from HomeKit with\n  \u003ca href=\"https://homebridge.io\"\u003eHomebridge\u003c/a\u003e.\n\u003c/p\u003e\n\n\u003c/span\u003e\n\n## Installation\n\n1. Search for \"SwitchBot\" on the plugin screen of [Homebridge Config UI X](https://github.com/oznu/homebridge-config-ui-x)\n2. Find: `@switchbot/homebridge-switchbot`\n   - See noble [prerequisites](https://github.com/abandonware/noble#prerequisites) for your OS. (This is used for BLE connection.)\n3. Click **Install**\n\n## Configuration\n\n- ### If using OpenAPI Connection\n  1. Download SwitchBot App on App Store or Google Play Store\n  2. Register a SwitchBot account and log in into your account\n  3. Generate an Token within the App\n     - Click Bottom Profile Tab\n     - Click Preference\n     - Click App version 10 Times, this will enable Developer Options\n     - Click Developer Options\n     - Click Copy `token` to Clipboard\n  4. Input your `token` into the config parameter\n  5. Generate an Secret within the App\n     - Click Bottom Profile Tab\n     - Click Preference\n     - Click App version 10 Times, this will enable Developer Options\n     - Click Developer Options\n     - Click Copy `secret` to Clipboard\n  6. Input your `secret` into the config parameter\n- ### If using BLE Connection\n  1. Download SwitchBot App on App Store or Google Play Store\n  2. Register a SwitchBot account and log in into your account\n  3. Click on Device wanting to connect too plugin\n     - Click the Settings Gear\n     - Click Device Info\n     - Copy BLE Mac aka `deviceId`\n  4. Input your `deviceId` into the Device Config\n\n## Troubleshooting\n\n- ### If using Linux / Raspberry Pi OS\n\n  1. `bluetoothctl` must be installed on the device, otherwise it cannot communicate via Bluetooth. Enable it with `sudo bluetoothctl power on`.\n\n  2. If errors occur, while enabling it, restart the process:\n\n     - `rfkill block bluetooth`\n     - `rfkill unblock bluetooth`\n\n  3. Also make sure, that the computer can discover the SwitchBot device:\n\n     - `sudo bluetoothctl`\n     - `scan on`\n\n     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.\n\n- ### If using MacOS\n  1. Manually grant Bluetooth access in System Settings UI for `Security \u0026 Privacy -\u003e Privacy` to the node executable, eg `/usr/local/bin/node`\n     ![Security \u0026 Privacy -\u003e Privacy](assets/security-privacy-bluetooth.png)\n     (This is what is intended in documentation for the noble bluetooth package [prerequisites](https://github.com/abandonware/noble#prerequisites) by \"Add terminal app\", however for HomeBridge it is `node` that needs the permission granted, not `terminal`.\n     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:\n  ```\n  Error: Failed to initialize the Noble object: unauthorized\n    at Noble.\u003canonymous\u003e (file:///usr/local/lib/node_modules/@switchbot/homebridge-switchbot/node_modules/node-switchbot/src/switchbot.ts:244:19)\n    at Object.onceWrapper (node:events:629:26)\n    at Noble.emit (node:events:514:28)\n    at Noble.onStateChange (/usr/local/lib/node_modules/@switchbot/homebridge-switchbot/node_modules/@stoprocent/noble/lib/noble.js:92:8)\n    at NobleMac.emit (node:events:514:28)\n  ```\n\n## Supported SwitchBot Devices\n\n- [SwitchBot Humidifier](https://www.switch-bot.com/products/switchbot-smart-humidifier)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n    - Can Push Updates over OpenAPI\n    - Can Receive Updates over BLE and OpenAPI\n- [SwitchBot Evaporative Humidifier (Auto-refill)](https://www.switch-bot.com/products/switchbot-evaporative-humidifier-auto-refill)\n- [SwitchBot Meter](https://www.switch-bot.com/products/switchbot-meter)\n- [SwitchBot Meter Plus (US)](https://www.switch-bot.com/products/switchbot-meter-plus)\n- [SwitchBot Meter Plus (JP)](https://www.switchbot.jp/products/switchbot-meter-plus)\n- [SwitchBot Indoor/Outdoor Thermo-Hygrometer](https://www.switch-bot.com/products/switchbot-indoor-outdoor-thermo-hygrometer)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n  - If using Bluetooth Low Energy (BLE) only:\n    - Must supply `deviceId` \u0026 `deviceName` to Device Config\n    - Check `Enable Bluetooth Low Energy (BLE) Connection` on Device Config\n- [SwitchBot Motion Sensor](https://www.switch-bot.com/products/motion-sensor)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n  - If using Bluetooth Low Energy (BLE) only:\n    - Must supply `deviceId` \u0026 `deviceName` to Device Config\n    - Check `Enable Bluetooth Low Energy (BLE) Connection` on Device Config\n- [SwitchBot Contact Sensor](https://www.switch-bot.com/products/contact-sensor)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n  - If using Bluetooth Low Energy (BLE) only:\n    - Must supply `deviceId` \u0026 `deviceName` to Device Config\n    - Check `Enable Bluetooth Low Energy (BLE) Connection` on Device Config\n- [SwitchBot Curtain](https://www.switch-bot.com/products/switchbot-curtain)\n- [SwitchBot Curtain 3](https://www.switch-bot.com/products/switchbot-curtain-3)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n  - If using Bluetooth Low Energy (BLE) only:\n    - Must supply `deviceId` \u0026 `deviceName` to Device Config\n    - Check `Enable Bluetooth Low Energy (BLE) Connection` on Device Config\n- [SwitchBot Blind Tilt](https://us.switch-bot.com/products/switchbot-blind-tilt)\n  - Supports OpenAPI \u0026 partial Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n- [SwitchBot Bulb](https://www.switch-bot.com/products/switchbot-color-bulb)\n- [SwitchBot Ceiling Light](https://www.switchbot.jp/collections/all/products/switchbot-ceiling-light)\n- [SwitchBot Ceiling Light Pro](https://www.switchbot.jp/collections/all/products/switchbot-ceiling-light)\n- [SwitchBot Light Strip](https://www.switch-bot.com/products/switchbot-light-strip)\n  - Supports OpenAPI \u0026 partial Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n- [SwitchBot Lock](https://us.switch-bot.com/products/switchbot-lock)\n- [SwitchBot Lock Pro](https://www.switchbot.jp/products/switchbot-lock-pro)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n- US: [SwitchBot Mini Robot Vacuum K10+](https://www.switch-bot.com/products/switchbot-mini-robot-vacuum-k10)\n- US: [SwitchBot Floor Cleaning Robot S10](https://www.switch-bot.com/products/switchbot-floor-cleaning-robot-s10)\n- JP: [SwitchBot Robot Vacuum Cleaner S1](https://www.switchbot.jp/products/switchbot-robot-vacuum-cleaner)\n- JP: [SwitchBot Robot Vacuum Cleaner S1 Plus](https://www.switchbot.jp/products/switchbot-robot-vacuum-cleaner)\n  - Supports OpenAPI Connection Only\n- [SwitchBot Plug](https://www.switch-bot.com/products/switchbot-plug)\n- [SwitchBot Plug Mini (US)](https://www.switch-bot.com/products/switchbot-plug-mini)\n- [SwitchBot Plug Mini (JP)](https://www.switchbot.jp/products/switchbot-plug-mini)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n- [SwitchBot Bot](https://www.switch-bot.com/products/switchbot-bot)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n  - If using OpenAPI:\n    - [SwitchBot Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini), [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), or [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3) Required\n    - Enable Cloud Services for Device on SwitchBot App\n    - You must set your Bot's Device ID for either Press Mode or Switch Mode in Plugin Config (SwitchBot Device Settings \u003e Bot Settings)\n      - Press Mode - Turns on then instantly turn it off\n      - Switch Mode - Turns on and keep it on until it is turned off\n        - This can get out of sync, since API doesn't give me a status\n        - To Correct you must go into the SwitchBot App and correct the status of either `On` or `Off`\n  - If using Bluetooth Low Energy (BLE) only:\n    - Must supply `deviceId` \u0026 `deviceName` to Device Config\n    - Check `Enable Bluetooth Low Energy (BLE) Connection` on Device Config\n- [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n    - Enables Humidity, Temperature, and Light Sensor\n- [SwitchBot Hub Mini 2](https://us.switch-bot.com/products/switchbot-hub-mini-2)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n    - Enables Humidity, Temperature, and Light Sensor\n- [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n    - Enables Humidity, Temperature, and Light Sensor\n- [SwitchBot Battery Circulator Fan](https://us.switch-bot.com/products/switchbot-battery-circulator-fan)\n  - Supports OpenAPI Connection Only\n- [SwitchBot Water Leak Detector](https://us.switch-bot.com/products/switchbot-water-leak-detector)\n  - Supports OpenAPI \u0026 Bluetooth Low Energy (BLE) Connections\n\n## Supported IR Devices\n\n### _(All IR Devices require [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), [SwitchBot Hub Mini 2](https://us.switch-bot.com/products/switchbot-hub-mini-2), [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3), or [Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini))_\n\n- TV\n  - Allows for On/Off and Volume Controls\n  - Optional Disable Sending Power Command\n- Projector (Displayed as TV)\n  - Allows for On/Off and Volume Controls\n- Set Top Box (Displayed as Set Top Box)\n  - Allows for On/Off and Volume Controls\n- DVD (Displayed as Set Top Box)\n  - Allows for On/Off and Volume Controls\n- Streamer (Displayed as Streaming Stick)\n  - Allows for On/Off and Volume Controls\n- Speaker (Displayed as Speaker)\n  - Allows for On/Off and Volume Controls\n- Fans\n  - Allows for On/Off Controls\n  - Optional Rotation Speed\n  - Optional Swing Mode\n- Lights\n  - Allows for On/Off Controls\n- Air Purifiers\n  - Allows for On/Off Controls\n- Air Conditioners\n  - Allows for On/Off, Tempeture, and Mode Controls\n  - Optional Disable Auto Mode\n- Cameras\n  - Allows for On/Off Controls\n- Vacuum Cleaners\n  - Allows for On/Off Controls\n- Water Heaters\n  - Allows for On/Off Controls\n- Others\n  - Option to Display as differenet Device Type\n    - Supports Fan Device Type\n  - Allows for On/Off Controls\n\n## SwitchBot APIs\n\n- [OpenWonderLabs/node-switchbot](https://github.com/OpenWonderLabs/node-switchbot)\n  - [OpenWonderLabs/SwitchBotAPI](https://github.com/OpenWonderLabs/SwitchBotAPI)\n  - [OpenWonderLabs/SwitchBotAPI-BLE](https://github.com/OpenWonderLabs/SwitchBotAPI-BLE)\n\n## Development / Tests\n\n- Run unit tests:\n  ```bash\n  npm run test\n  ```\n\n- Notes:\n  - Added Lock Ultra (Cloud + BLE) support (requires `node-switchbot` v3.6.3).\n\n## Community\n\n- [SwitchBot (Official website)](https://www.switch-bot.com/)\n- [Facebook @SwitchBotRobot](https://www.facebook.com/SwitchBotRobot/)\n- [Twitter @SwitchBot](https://twitter.com/switchbot)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenwonderlabs%2Fhomebridge-switchbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenwonderlabs%2Fhomebridge-switchbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenwonderlabs%2Fhomebridge-switchbot/lists"}