The node-switchbot is a Node.js module that allows you to interact with various SwitchBot devices. You can control your SwitchBot (Bot)'s arm, operate your SwitchBot Curtain, and manage your SwitchBot Lock. Additionally, you can monitor temperature and humidity using the SwitchBot Thermometer & Hygrometer (Meter), and check the status of the SwitchBot Motion Sensor and SwitchBot Contact Sensor.
This module now supports both Bluetooth Low Energy (BLE) and the SwitchBot OpenAPI, providing more flexibility and options for interacting with your devices.
Please note that most of this module was developed by referencing the official BLE API and OpenAPI documentation. However, some functionalities were developed through trial and error, so there might be inaccuracies in the information obtained from this module.
To install the node-switchbot module within your project, use the following command:
$ npm install --save node-switchbotv4.0.0 introduces a unified hybrid approach that automatically uses BLE when available with seamless API fallback.
import{SwitchBot}from'node-switchbot'constswitchbot=newSwitchBot({token: 'YOUR_TOKEN',// OpenAPI token (optional for BLE-only)secret: 'YOUR_SECRET',// OpenAPI secret (optional for BLE-only)enableBLE: true,// Enable BLE discovery (Linux/macOS)enableFallback: true,// Auto-fallback between BLE/API})// Discover all devices (BLE + API)constdevices=awaitswitchbot.discover()// Control devicesconstbot=switchbot.devices.get('YOUR_DEVICE_ID')awaitbot.press()// Get status conststatus=awaitbot.getStatus()console.log(status)// Cleanupawaitswitchbot.cleanup()// Bot - Press/Switch controlawaitbot.turnOn()awaitbot.turnOff()awaitbot.press()// Bot with Password Protection (BLE only)constprotectedBot=newWoHand({id: 'YOUR_BOT_ID',password: 'A1b2'})awaitprotectedBot.setPassword('A1b2')// Set 4-char alphanumeric passwordawaitprotectedBot.press()// Commands are automatically encryptedawaitprotectedBot.clearPassword()// Remove password protection// Curtain - Position controlawaitcurtain.open()awaitcurtain.close()awaitcurtain.setPosition(50)// 50% open// Lock - Lock/Unlockawaitlock.lock()awaitlock.unlock()// Bulb - Color and brightnessawaitbulb.turnOn()awaitbulb.setBrightness(80)awaitbulb.setColor(255,0,0)// Red// Meter - Read sensorsconstmeterStatus=awaitmeter.getStatus()console.log(meterStatus.temperature,meterStatus.humidity)See the examples directory for more usage patterns.
To see a breakdown of how to use the BLE functionality of this project, visit the BLE (Bluetooth Low Energy) documentation.
To see a breakdown of how to use the OpenAPI functionality of this project, visit the OpenAPI documentation.
Breaking Changes in v4.0.0:
- ✨ Unified API: Single
SwitchBotclass replaces separateSwitchBotBLEandSwitchBotOpenAPIclasses - 🔄 Automatic Discovery: Combined BLE + OpenAPI discovery in one call
- 🛡️ Automatic Fallback: BLE commands automatically fall back to API on failure
- 📦 Device Manager: Access devices via
switchbot.devices.get(id)instead of direct discovery results - 🏷️ TypeScript: Full TypeScript rewrite with comprehensive type definitions
⚠️ No Backward Compatibility: v3.x APIs are not supported - migration required
Migration Example:
// v3.x (old)import{SwitchBotBLE,SwitchBotOpenAPI}from'node-switchbot'constble=newSwitchBotBLE()constapi=newSwitchBotOpenAPI(token,secret)// v4.0.0 (new)import{SwitchBot}from'node-switchbot'constswitchbot=newSwitchBot({ token, secret,enableBLE: true})