{"id":15011153,"url":"https://github.com/openwonderlabs/node-switchbot","last_synced_at":"2026-04-11T03:35:23.424Z","repository":{"id":37788329,"uuid":"222875757","full_name":"OpenWonderLabs/node-switchbot","owner":"OpenWonderLabs","description":"The node-switchbot is a Node.js module which allows you communicate with SwitchBot Devices over BLE or OpenAPI","archived":false,"fork":false,"pushed_at":"2026-03-04T19:34:56.000Z","size":2996,"stargazers_count":91,"open_issues_count":6,"forks_count":32,"subscribers_count":4,"default_branch":"latest","last_synced_at":"2026-03-05T01:42:10.980Z","etag":null,"topics":["ble","nodejs","switchbot"],"latest_commit_sha":null,"homepage":"https://openwonderlabs.github.io/node-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":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-11-20T07:22:21.000Z","updated_at":"2026-02-25T18:22:49.000Z","dependencies_parsed_at":"2023-12-11T21:28:39.245Z","dependency_job_id":"b88d190a-b3e4-45ba-b1dd-f6fe2318e10a","html_url":"https://github.com/OpenWonderLabs/node-switchbot","commit_stats":{"total_commits":101,"total_committers":10,"mean_commits":10.1,"dds":0.5445544554455446,"last_synced_commit":"d7683ea231de1b96ca9936f5638b1c66417dd4df"},"previous_names":["futomi/node-switchbot"],"tags_count":118,"template":false,"template_full_name":null,"purl":"pkg:github/OpenWonderLabs/node-switchbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fnode-switchbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fnode-switchbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fnode-switchbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fnode-switchbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenWonderLabs","download_url":"https://codeload.github.com/OpenWonderLabs/node-switchbot/tar.gz/refs/heads/latest","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fnode-switchbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30206336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"online","status_checked_at":"2026-03-07T02:00:06.765Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","nodejs","switchbot"],"created_at":"2024-09-24T19:39:18.538Z","updated_at":"2026-04-11T03:35:23.410Z","avatar_url":"https://github.com/OpenWonderLabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![node-switchbot](https://raw.githubusercontent.com/OpenWonderLabs/node-switchbot/latest/branding/Node_x_SwitchBot.svg?sanitize=true)\n\n# Node-SwitchBot\n\n[![npm version](https://badgen.net/npm/v/node-switchbot)](https://www.npmjs.com/package/node-switchbot)\n[![npm downloads](https://badgen.net/npm/dt/node-switchbot)](https://www.npmjs.com/package/node-switchbot)\n\n\u003c/div\u003e\n\nThe `node-switchbot` is a Node.js module that allows you to interact with various SwitchBot devices. You can control your [SwitchBot (Bot)'s](https://www.switch-bot.com/bot) arm, operate your [SwitchBot Curtain](https://www.switch-bot.com/products/switchbot-curtain), and manage your [SwitchBot Lock](https://www.switch-bot.com/products/switchbot-lock). Additionally, you can monitor temperature and humidity using the [SwitchBot Thermometer \u0026 Hygrometer (Meter)](https://www.switch-bot.com/meter), and check the status of the [SwitchBot Motion Sensor](https://www.switch-bot.com/products/motion-sensor) and [SwitchBot Contact Sensor](https://www.switch-bot.com/products/contact-sensor).\n\nThis module now supports both Bluetooth Low Energy (BLE) and the SwitchBot OpenAPI, providing more flexibility and options for interacting with your devices.\n\nPlease note that most of this module was developed by referencing the official [BLE API](https://github.com/OpenWonderLabs/SwitchBotAPI-BLE) and [OpenAPI](https://github.com/OpenWonderLabs/SwitchBotAPI) documentation. However, some functionalities were developed through trial and error, so there might be inaccuracies in the information obtained from this module.\n\n---\n\n## [Installation](https://npmjs.org/node-switchbot)\n\nTo install the `node-switchbot` module within your project, use the following command:\n\n```sh\n$ npm install --save node-switchbot\n```\n\n---\n\n## Quick Start (v4.0.0)\n\n**v4.0.0** introduces a unified hybrid approach that automatically uses BLE when available with seamless API fallback.\n\n### Basic Usage\n\n```javascript\nimport { SwitchBot } from 'node-switchbot'\n\nconst switchbot = new SwitchBot({\n  token: 'YOUR_TOKEN',      // OpenAPI token (optional for BLE-only)\n  secret: 'YOUR_SECRET',    // OpenAPI secret (optional for BLE-only)\n  enableBLE: true,          // Enable BLE discovery (Linux/macOS)\n  enableFallback: true,     // Auto-fallback between BLE/API\n})\n\n// Discover all devices (BLE + API)\nconst devices = await switchbot.discover()\n\n// Control devices\nconst bot = switchbot.devices.get('YOUR_DEVICE_ID')\nawait bot.press()\n\n// Get status  \nconst status = await bot.getStatus()\nconsole.log(status)\n\n// Cleanup\nawait switchbot.cleanup()\n```\n\n### Device Control Examples\n\n```javascript\n// Bot - Press/Switch control\nawait bot.turnOn()\nawait bot.turnOff()\nawait bot.press()\n\n// Bot with Password Protection (BLE only)\nconst protectedBot = new WoHand({ id: 'YOUR_BOT_ID', password: 'A1b2' })\nawait protectedBot.setPassword('A1b2')  // Set 4-char alphanumeric password\nawait protectedBot.press()              // Commands are automatically encrypted\nawait protectedBot.clearPassword()      // Remove password protection\n\n// Curtain - Position control\nawait curtain.open()\nawait curtain.close()\nawait curtain.setPosition(50)  // 50% open\n\n// Lock - Lock/Unlock\nawait lock.lock()\nawait lock.unlock()\n\n// Bulb - Color and brightness\nawait bulb.turnOn()\nawait bulb.setBrightness(80)\nawait bulb.setColor(255, 0, 0)  // Red\n\n// Meter - Read sensors\nconst meterStatus = await meter.getStatus()\nconsole.log(meterStatus.temperature, meterStatus.humidity)\n```\n\nSee the [examples directory](https://github.com/OpenWonderLabs/node-switchbot/tree/latest/examples) for more usage patterns.\n\n---\n\n## [BLE (Bluetooth Low Energy)](BLE.md)\n\nTo see a breakdown of how to use the BLE functionality of this project, visit the [BLE (Bluetooth Low Energy)](BLE.md) documentation.\n\n## [OpenAPI](OpenAPI.md)\n\nTo see a breakdown of how to use the OpenAPI functionality of this project, visit the [OpenAPI](OpenAPI.md) documentation.\n\n---\n\n## Migration from v3.x\n\n**Breaking Changes in v4.0.0:**\n\n- ✨ **Unified API**: Single `SwitchBot` class replaces separate `SwitchBotBLE` and `SwitchBotOpenAPI` classes\n- 🔄 **Automatic Discovery**: Combined BLE + OpenAPI discovery in one call\n- 🛡️ **Automatic Fallback**: BLE commands automatically fall back to API on failure\n- 📦 **Device Manager**: Access devices via `switchbot.devices.get(id)` instead of direct discovery results\n- 🏷️ **TypeScript**: Full TypeScript rewrite with comprehensive type definitions\n- ⚠️ **No Backward Compatibility**: v3.x APIs are not supported - migration required\n\n**Migration Example:**\n\n```javascript\n// v3.x (old)\nimport { SwitchBotBLE, SwitchBotOpenAPI } from 'node-switchbot'\nconst ble = new SwitchBotBLE()\nconst api = new SwitchBotOpenAPI(token, secret)\n\n// v4.0.0 (new)\nimport { SwitchBot } from 'node-switchbot'\nconst switchbot = new SwitchBot({ token, secret, enableBLE: true })\n```\n\n---\n\n## References\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%2Fnode-switchbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenwonderlabs%2Fnode-switchbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenwonderlabs%2Fnode-switchbot/lists"}