node-switchbot 4.0.0-beta.17 → 4.0.0-beta.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/BLE.md +215 -838
- package/CHANGELOG.md +96 -1371
- package/OpenAPI.md +169 -135
- package/README.md +1 -1
- package/dist/devices/base.d.ts.map +1 -1
- package/dist/devices/base.js.map +1 -1
- package/dist/devices/wo-ai-hub.d.ts.map +1 -1
- package/dist/devices/wo-ai-hub.js.map +1 -1
- package/dist/devices/wo-air-purifier-pm25.d.ts.map +1 -1
- package/dist/devices/wo-air-purifier-pm25.js.map +1 -1
- package/dist/devices/wo-air-purifier.d.ts.map +1 -1
- package/dist/devices/wo-air-purifier.js.map +1 -1
- package/dist/devices/wo-blind-tilt.d.ts.map +1 -1
- package/dist/devices/wo-blind-tilt.js.map +1 -1
- package/dist/devices/wo-bulb.d.ts.map +1 -1
- package/dist/devices/wo-bulb.js.map +1 -1
- package/dist/devices/wo-candle-warmer-lamp.d.ts.map +1 -1
- package/dist/devices/wo-candle-warmer-lamp.js.map +1 -1
- package/dist/devices/wo-keypad-vision-pro.d.ts.map +1 -1
- package/dist/devices/wo-keypad-vision-pro.js.map +1 -1
- package/dist/devices/wo-pan-tilt-cam-plus-3k.d.ts.map +1 -1
- package/dist/devices/wo-pan-tilt-cam-plus-3k.js.map +1 -1
- package/dist/devices/wo-relay-switch-1.d.ts.map +1 -1
- package/dist/devices/wo-relay-switch-1.js.map +1 -1
- package/dist/devices/wo-remote-with-screen.d.ts.map +1 -1
- package/dist/devices/wo-remote-with-screen.js.map +1 -1
- package/dist/devices/wo-rgbic-neon-wire-rope-light.d.ts.map +1 -1
- package/dist/devices/wo-rgbic-neon-wire-rope-light.js.map +1 -1
- package/dist/devices/wo-water-detector.d.ts.map +1 -1
- package/dist/devices/wo-water-detector.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/utils/fallback-handler.js +0 -1
- package/dist/utils/fallback-handler.js.map +1 -1
- package/dist/utils/index.d.ts.map +1 -1
- package/dist/utils/index.js.map +1 -1
- package/package.json +25 -10
- package/.gitattributes +0 -2
- package/.github/copilot-instructions.md +0 -179
- package/.github/dependabot.yml +0 -17
- package/.github/labeler.yml +0 -38
- package/.github/npm-version-script-esm.js +0 -97
- package/.github/workflows/beta-release.yml +0 -52
- package/.github/workflows/release.yml +0 -71
- package/.github/workflows/stale.yml +0 -12
- package/branding/Node_x_SwitchBot.svg +0 -8
- package/branding/icon.png +0 -0
- package/branding/switchbot.png +0 -0
- package/docs/.nojekyll +0 -1
- package/docs/assets/hierarchy.js +0 -1
- package/docs/assets/highlight.css +0 -92
- package/docs/assets/icons.js +0 -18
- package/docs/assets/icons.svg +0 -1
- package/docs/assets/main.js +0 -60
- package/docs/assets/navigation.js +0 -1
- package/docs/assets/search.js +0 -1
- package/docs/assets/style.css +0 -1633
- package/docs/classes/APIError.html +0 -6
- package/docs/classes/APINotAvailableError.html +0 -4
- package/docs/classes/BLEConnection.html +0 -25
- package/docs/classes/BLENotAvailableError.html +0 -4
- package/docs/classes/BLEScanner.html +0 -17
- package/docs/classes/CommandFailedError.html +0 -6
- package/docs/classes/ConnectionTimeoutError.html +0 -5
- package/docs/classes/DeviceManager.html +0 -25
- package/docs/classes/DeviceNotFoundError.html +0 -4
- package/docs/classes/DeviceOverrideStateDuringConnection.html +0 -82
- package/docs/classes/DiscoveryError.html +0 -5
- package/docs/classes/OpenAPIClient.html +0 -66
- package/docs/classes/SequenceDevice.html +0 -92
- package/docs/classes/SwitchBot.html +0 -22
- package/docs/classes/SwitchBotDevice.html +0 -115
- package/docs/classes/SwitchBotError.html +0 -4
- package/docs/classes/ValidationError.html +0 -5
- package/docs/classes/WoAIHub.html +0 -116
- package/docs/classes/WoAirPurifier.html +0 -88
- package/docs/classes/WoAirPurifierPM25.html +0 -117
- package/docs/classes/WoAirPurifierTable.html +0 -89
- package/docs/classes/WoArtFrame.html +0 -103
- package/docs/classes/WoBlindTilt.html +0 -89
- package/docs/classes/WoBulb.html +0 -102
- package/docs/classes/WoCandleWarmerLamp.html +0 -122
- package/docs/classes/WoCeilingLight.html +0 -103
- package/docs/classes/WoCirculatorFan.html +0 -89
- package/docs/classes/WoClimatePanel.html +0 -89
- package/docs/classes/WoContact.html +0 -82
- package/docs/classes/WoCurtain.html +0 -94
- package/docs/classes/WoFloorLamp.html +0 -103
- package/docs/classes/WoGarageDoorOpener.html +0 -94
- package/docs/classes/WoHand.html +0 -95
- package/docs/classes/WoHub2.html +0 -82
- package/docs/classes/WoHub3.html +0 -83
- package/docs/classes/WoHubMiniMatter.html +0 -83
- package/docs/classes/WoHumi.html +0 -89
- package/docs/classes/WoHumi2.html +0 -90
- package/docs/classes/WoIOSensorTH.html +0 -83
- package/docs/classes/WoKeypad.html +0 -83
- package/docs/classes/WoKeypadVision.html +0 -83
- package/docs/classes/WoKeypadVisionPro.html +0 -83
- package/docs/classes/WoLeak.html +0 -82
- package/docs/classes/WoPanTiltCamPlus3K.html +0 -122
- package/docs/classes/WoPlugMiniJP.html +0 -89
- package/docs/classes/WoPlugMiniUS.html +0 -88
- package/docs/classes/WoPresence.html +0 -82
- package/docs/classes/WoRGBICBulb.html +0 -114
- package/docs/classes/WoRGBICNeonWireRopeLight.html +0 -126
- package/docs/classes/WoRGBICWWFloorLamp.html +0 -114
- package/docs/classes/WoRGBICWWStripLight.html +0 -114
- package/docs/classes/WoRelaySwitch1.html +0 -93
- package/docs/classes/WoRelaySwitch1PM.html +0 -94
- package/docs/classes/WoRelaySwitch2PM.html +0 -98
- package/docs/classes/WoRemote.html +0 -83
- package/docs/classes/WoRemoteWithScreen.html +0 -116
- package/docs/classes/WoRollerShade.html +0 -95
- package/docs/classes/WoSensorTH.html +0 -82
- package/docs/classes/WoSensorTHPlus.html +0 -83
- package/docs/classes/WoSensorTHPro.html +0 -83
- package/docs/classes/WoSensorTHProCO2.html +0 -83
- package/docs/classes/WoSmartLock.html +0 -91
- package/docs/classes/WoSmartLockLite.html +0 -91
- package/docs/classes/WoSmartLockPro.html +0 -95
- package/docs/classes/WoSmartLockProWiFi.html +0 -95
- package/docs/classes/WoSmartLockVision.html +0 -91
- package/docs/classes/WoSmartLockVisionPro.html +0 -95
- package/docs/classes/WoSmartThermostatRadiator.html +0 -89
- package/docs/classes/WoStrip.html +0 -103
- package/docs/classes/WoStripLight3.html +0 -103
- package/docs/classes/WoVacuum.html +0 -98
- package/docs/classes/WoVacuumK10Plus.html +0 -98
- package/docs/classes/WoVacuumK10Pro.html +0 -98
- package/docs/classes/WoVacuumK10ProCombo.html +0 -98
- package/docs/classes/WoVacuumK11Plus.html +0 -98
- package/docs/classes/WoVacuumK20.html +0 -98
- package/docs/classes/WoVacuumS10.html +0 -98
- package/docs/classes/WoVacuumS20.html +0 -98
- package/docs/classes/WoWaterDetector.html +0 -116
- package/docs/enums/LogLevel.html +0 -7
- package/docs/enums/SwitchBotBLEModel.html +0 -40
- package/docs/enums/SwitchBotBLEModelName.html +0 -40
- package/docs/functions/updateBaseURL.html +0 -3
- package/docs/hierarchy.html +0 -1
- package/docs/index.html +0 -55
- package/docs/interfaces/APICommandRequest.html +0 -5
- package/docs/interfaces/APICommandResponse.html +0 -5
- package/docs/interfaces/APIDevice.html +0 -18
- package/docs/interfaces/APIDeviceStatus.html +0 -36
- package/docs/interfaces/APIErrorResponse.html +0 -5
- package/docs/interfaces/APIResponse.html +0 -5
- package/docs/interfaces/AirPurifierCommands.html +0 -6
- package/docs/interfaces/AirPurifierServiceData.html +0 -29
- package/docs/interfaces/AirPurifierStatus.html +0 -17
- package/docs/interfaces/BLEAdvertisement.html +0 -13
- package/docs/interfaces/BLEScanOptions.html +0 -10
- package/docs/interfaces/BLEServiceData.html +0 -27
- package/docs/interfaces/BlindTiltCommands.html +0 -7
- package/docs/interfaces/BlindTiltServiceData.html +0 -30
- package/docs/interfaces/BlindTiltStatus.html +0 -16
- package/docs/interfaces/BotCommands.html +0 -8
- package/docs/interfaces/BotServiceData.html +0 -27
- package/docs/interfaces/BotStatus.html +0 -14
- package/docs/interfaces/BulbCommands.html +0 -10
- package/docs/interfaces/BulbServiceData.html +0 -35
- package/docs/interfaces/BulbStatus.html +0 -16
- package/docs/interfaces/CeilingLightCommands.html +0 -10
- package/docs/interfaces/CeilingLightServiceData.html +0 -35
- package/docs/interfaces/CeilingLightStatus.html +0 -16
- package/docs/interfaces/CommandResult.html +0 -12
- package/docs/interfaces/ContactServiceData.html +0 -30
- package/docs/interfaces/ContactStatus.html +0 -15
- package/docs/interfaces/CurtainCommands.html +0 -8
- package/docs/interfaces/CurtainExtendedInfo.html +0 -4
- package/docs/interfaces/CurtainServiceData.html +0 -31
- package/docs/interfaces/CurtainStatus.html +0 -17
- package/docs/interfaces/DeviceInfo.html +0 -36
- package/docs/interfaces/DeviceListResponse.html +0 -4
- package/docs/interfaces/DeviceStatus.html +0 -12
- package/docs/interfaces/DiscoveryOptions.html +0 -14
- package/docs/interfaces/HubServiceData.html +0 -31
- package/docs/interfaces/HubStatus.html +0 -15
- package/docs/interfaces/HumidifierCommands.html +0 -9
- package/docs/interfaces/HumidifierServiceData.html +0 -31
- package/docs/interfaces/HumidifierStatus.html +0 -18
- package/docs/interfaces/KeypadStatus.html +0 -13
- package/docs/interfaces/LeakServiceData.html +0 -28
- package/docs/interfaces/LeakStatus.html +0 -13
- package/docs/interfaces/LockCommands.html +0 -7
- package/docs/interfaces/LockServiceData.html +0 -29
- package/docs/interfaces/LockStatus.html +0 -15
- package/docs/interfaces/MeterServiceData.html +0 -30
- package/docs/interfaces/MeterStatus.html +0 -15
- package/docs/interfaces/MotionServiceData.html +0 -30
- package/docs/interfaces/MotionStatus.html +0 -14
- package/docs/interfaces/PlugCommands.html +0 -4
- package/docs/interfaces/PlugServiceData.html +0 -33
- package/docs/interfaces/PlugStatus.html +0 -16
- package/docs/interfaces/PresenceServiceData.html +0 -29
- package/docs/interfaces/PresenceStatus.html +0 -14
- package/docs/interfaces/RelaySwitchCommands.html +0 -6
- package/docs/interfaces/RelaySwitchServiceData.html +0 -30
- package/docs/interfaces/RelaySwitchStatus.html +0 -16
- package/docs/interfaces/RemoteStatus.html +0 -12
- package/docs/interfaces/SceneListResponse.html +0 -3
- package/docs/interfaces/StripCommands.html +0 -10
- package/docs/interfaces/StripServiceData.html +0 -35
- package/docs/interfaces/StripStatus.html +0 -16
- package/docs/interfaces/SwitchBotConfig.html +0 -39
- package/docs/interfaces/VacuumCommands.html +0 -8
- package/docs/interfaces/VacuumStatus.html +0 -16
- package/docs/interfaces/WebhookConfig.html +0 -4
- package/docs/interfaces/WebhookDetails.html +0 -7
- package/docs/interfaces/WebhookQueryResponse.html +0 -5
- package/docs/interfaces/WebhookSetupResponse.html +0 -5
- package/docs/media/BLE.md +0 -1259
- package/docs/media/OpenAPI.md +0 -186
- package/docs/modules.html +0 -1
- package/docs/types/ConnectionType.html +0 -2
- package/docs/types/PhysicalDeviceType.html +0 -2
- package/docs/types/VirtualDeviceType.html +0 -2
- package/docs/variables/urls.html +0 -1
- package/tmp-switchbot-scan.mjs +0 -79
- package/todo/todo.md +0 -15
- package/tsconfig.build.json +0 -17
package/BLE.md
CHANGED
|
@@ -6,948 +6,325 @@ The `SwitchBot` class allows you to interact with SwitchBot devices using the Sw
|
|
|
6
6
|
|
|
7
7
|
- [BLE (Bluetooth Low Energy)](#ble-bluetooth-low-energy)
|
|
8
8
|
- [Supported OS](#supported-os)
|
|
9
|
-
|
|
10
|
-
- [Importing and Setting Up](#importing-and-setting-up)
|
|
11
|
-
- [`SwitchBotBLE` Object](#switchbot-object)
|
|
12
|
-
- [`discover()` method](#discover-method)
|
|
13
|
-
- [`ondiscover` event handler](#ondiscover-event-handler)
|
|
14
|
-
- [`startScan()` method](#startscan-method)
|
|
15
|
-
- [`onadvertisement` event handler](#onadvertisement-event-handler)
|
|
16
|
-
- [`stopScan()` method](#stopscan-method)
|
|
17
|
-
- [`wait()` method](#wait-method)
|
|
18
|
-
- [`SwitchBotDevice` Object](#switchbotdevice-object)
|
|
19
|
-
- [Properties](#properties)
|
|
20
|
-
- [`getDeviceName()` method](#getdevicename-method)
|
|
21
|
-
- [`setDeviceName()` method](#setdevicename-method)
|
|
22
|
-
- [`connect()` method](#connect-method)
|
|
23
|
-
- [`disconnect()` method](#disconnect-method)
|
|
24
|
-
- [`onconnect` event handler](#onconnect-event-handler)
|
|
25
|
-
- [`ondisconnect` event handler](#ondisconnect-event-handler)
|
|
26
|
-
- [`WoHand` Object](#wohand-object)
|
|
27
|
-
- [`press()` method](#press-method)
|
|
28
|
-
- [`turnOn()` method](#turnon-method)
|
|
29
|
-
- [`turnOff()` method](#turnoff-method)
|
|
30
|
-
- [`down()` method](#down-method)
|
|
31
|
-
- [`up()` method](#up-method)
|
|
32
|
-
- [`WoCurtain` object](#wocurtain-object)
|
|
33
|
-
- [`open()` method](#open-method)
|
|
34
|
-
- [`close()` method](#close-method)
|
|
35
|
-
- [`pause()` method](#pause-method)
|
|
36
|
-
- [`runToPos()` method](#runtopos-method)
|
|
37
|
-
- [`WoPlugMini` object](#woplugmini-object)
|
|
38
|
-
- [`turnOn()` method](#turnon-method)
|
|
39
|
-
- [`turnOff()` method](#turnoff-method)
|
|
40
|
-
- [`toggle()` method](#toggle-method)
|
|
41
|
-
- [`WoSmartLock` object](#wosmartlock-object)
|
|
42
|
-
- [`lock()` method](#lock-method)
|
|
43
|
-
- [`unlock()` method](#unlock-method)
|
|
44
|
-
- [`unlock_no_unlatch()` method](#unlock_no_unlatch-method)
|
|
45
|
-
- [`info()` method](#info-method)
|
|
46
|
-
- [Advertisement data](#advertisement-data)
|
|
47
|
-
- [Bot (WoHand)](#bot-wohand)
|
|
48
|
-
- [Meter (WoSensorTH)](#meter-wosensorth)
|
|
49
|
-
- [Curtain (WoCurtain)](#curtain-wocurtain)
|
|
50
|
-
- [Contact (WoContact)](#contact-wocontact)
|
|
51
|
-
- [Motion (WoMotion)](#motion-womotion)
|
|
52
|
-
- [PlugMini (WoPlugMini)](#plugmini-woplugmini)
|
|
53
|
-
- [Supported Devices](#supported-devices)
|
|
54
|
-
- [Advertisement Data](#advertisement-data)
|
|
55
|
-
- [Control Device](#control-device)
|
|
56
|
-
- [Summary](#summary)
|
|
57
|
-
|
|
58
|
-
## BLE (Bluetooth Low Energy)
|
|
59
|
-
|
|
60
|
-
### Supported OS
|
|
61
|
-
|
|
62
|
-
The node-switchbot supports Linux-based OSes (such as Raspbian, Ubuntu) and macOS. Windows is not currently supported. BLE functionality requires [@stoprocent/noble](https://github.com/stoprocent/noble#readme) which works natively on Linux and macOS.
|
|
63
|
-
|
|
64
|
-
### Dependencies
|
|
65
|
-
|
|
66
|
-
- [Node.js](https://nodejs.org/en/): ^20 || ^22 || ^24
|
|
67
|
-
- [@stoprocent/noble](https://github.com/stoprocent/noble) - Included as a dependency
|
|
68
|
-
|
|
69
|
-
### Prerequisites
|
|
70
|
-
|
|
71
|
-
#### macOS
|
|
72
|
-
|
|
73
|
-
- **Xcode**: Install from the App Store
|
|
74
|
-
- **Bluetooth Permissions**: On newer versions of macOS, allow Bluetooth access for your terminal app:
|
|
75
|
-
1. Open "System Preferences" → "Security & Privacy" → "Privacy" → "Bluetooth"
|
|
76
|
-
2. Add and enable your terminal application (Terminal.app, iTerm.app, etc.)
|
|
77
|
-
|
|
78
|
-
#### Linux (Ubuntu, Debian, Raspbian)
|
|
79
|
-
|
|
80
|
-
- **Kernel**: Version 3.6 or above
|
|
81
|
-
- **Required Packages**:
|
|
9
|
+
# SwitchBot BLE Documentation
|
|
82
10
|
|
|
83
|
-
|
|
84
|
-
sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
- **Node Path**: Ensure `node` is on your PATH
|
|
88
|
-
|
|
89
|
-
```bash
|
|
90
|
-
# If needed, symlink nodejs to node
|
|
91
|
-
sudo ln -s /usr/bin/nodejs /usr/bin/node
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
- **Running without sudo** (Recommended):
|
|
95
|
-
|
|
96
|
-
```bash
|
|
97
|
-
sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
This grants the `node` binary `cap_net_raw` privileges for BLE operations.
|
|
101
|
-
|
|
102
|
-
Required package: `sudo apt-get install libcap2-bin`
|
|
103
|
-
|
|
104
|
-
- **Raspberry Pi Specific**: If having trouble connecting to BLE devices, disable the `pnat` plugin by adding this line to `/etc/bluetooth/main.conf`:
|
|
105
|
-
```
|
|
106
|
-
DisablePlugins=pnat
|
|
107
|
-
```
|
|
108
|
-
Then restart the system.
|
|
11
|
+
BLE support in `node-switchbot` is part of the v4 unified architecture. The primary API is the `SwitchBot` class, which can use BLE directly, OpenAPI directly, or both together with automatic fallback.
|
|
109
12
|
|
|
110
|
-
|
|
13
|
+
This document covers:
|
|
111
14
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
See [@stoprocent/noble prerequisites](https://github.com/stoprocent/noble?tab=readme-ov-file#prerequisites) for more detailed platform-specific instructions.
|
|
117
|
-
|
|
118
|
-
### Importing and Setting Up
|
|
15
|
+
- BLE support and prerequisites on macOS and Linux
|
|
16
|
+
- BLE-first usage through the unified `SwitchBot` class
|
|
17
|
+
- Bot password protection over BLE
|
|
18
|
+
- Low-level BLE helpers for advanced use: `BLEScanner` and `BLEConnection`
|
|
119
19
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
```typescript
|
|
123
|
-
import { SwitchBotBLE } from 'node-switchbot'
|
|
124
|
-
|
|
125
|
-
// Example usage
|
|
126
|
-
const switchBotBLE = new SwitchBotBLE()
|
|
127
|
-
|
|
128
|
-
try {
|
|
129
|
-
await switchBotBLE.startScan()
|
|
130
|
-
} catch (e: any) {
|
|
131
|
-
console.error(`Failed to start BLE scanning, Error: ${e.message ?? e}`)
|
|
132
|
-
}
|
|
133
|
-
```
|
|
20
|
+
## v4 BLE Model
|
|
134
21
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
The `SwitchBotBLE` constructor takes an argument optionally. It must be a hash object containing the properties as follows:
|
|
138
|
-
|
|
139
|
-
| Property | Type | Required | Description |
|
|
140
|
-
| :------- | :---- | :------- | :-------------------------------------------------------------------------------------- |
|
|
141
|
-
| `noble` | Noble | option | a Noble object of the [`@stoprocent/noble`](https://github.com/stoprocent/noble) module |
|
|
142
|
-
|
|
143
|
-
The node-switchbot module uses the [`@stoprocent/noble`](https://github.com/stoprocent/noble) module in order to interact with BLE devices. If you want to interact other BLE devices using the `@stoprocent/noble` module, you can create an `Noble` object by yourself, then pass it to this module. If you don't specify a `Noble` object to the `noble` property, this module automatically create a `Noble` object internally.
|
|
144
|
-
|
|
145
|
-
The sample code below shows how to pass a `Noble` object to the `Switchbot` constructor.
|
|
146
|
-
|
|
147
|
-
```Typescript
|
|
148
|
-
// Create a Noble object
|
|
149
|
-
const noble = require('@stoprocent/noble');
|
|
150
|
-
|
|
151
|
-
const switchBotBLE = new SwitchBotBLE({ 'noble': Noble })
|
|
152
|
-
```
|
|
22
|
+
In v4.0.0, BLE is no longer a separate top-level workflow that you have to adopt in isolation. Instead:
|
|
153
23
|
|
|
154
|
-
|
|
24
|
+
- `SwitchBot` is the main public entry point
|
|
25
|
+
- BLE is used when `enableBLE: true`
|
|
26
|
+
- OpenAPI can be used as fallback when credentials are present
|
|
27
|
+
- Devices are accessed through `switchbot.devices`
|
|
28
|
+
- Per-device commands automatically choose the best available connection path
|
|
155
29
|
|
|
156
|
-
|
|
30
|
+
## Supported Platforms
|
|
157
31
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
| Property | Type | Required | Description |
|
|
161
|
-
| :--------- | :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
162
|
-
| `duration` | Integer | Optional | Duration for discovery process (msec). The default value is 5000 (msec). |
|
|
163
|
-
| `model` | String | Optional | `"H"`, `"T"` or `"c"`. If `"H"` is specified, this method will discover only Bots. If `"T"` is specified, this method will discover only Meters. If `"c"` is specified, this method will discover only Curtains. |
|
|
164
|
-
| `id` | String | Optional | If this value is set, this method will discover only a device whose ID is as same as this value. The ID is identical to the MAC address. This parameter is case-insensitive, and colons are ignored. |
|
|
165
|
-
| `quick` | Boolean | Optional | If this value is `true`, this method finishes the discovery process when the first device is found, then calls the `resolve()` function without waiting the specified `duration`. The default value is `false`. |
|
|
166
|
-
|
|
167
|
-
In the code snippet below, no parameter is passed to the method:
|
|
168
|
-
|
|
169
|
-
```Typescript
|
|
170
|
-
switchBotBLE.discover().then((device_list) => {
|
|
171
|
-
// Do something...
|
|
172
|
-
}).catch((error) => {
|
|
173
|
-
console.error(error);
|
|
174
|
-
});
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
If no parameter is passed to the method as the code above, an `Array` object will be passed to the `resolve()` function in 5 seconds. The `Array` object contains [`SwitchbotDevice`](#SwitchbotDevice-object) objects representing the found devices. See the section "[`SwitchbotDevice`](#SwitchbotDevice-object) objects" for more details.
|
|
178
|
-
|
|
179
|
-
If you want a quick response, you can set the `quick` property to `true`.
|
|
180
|
-
|
|
181
|
-
```Typescript
|
|
182
|
-
switchBotBLE.discover({
|
|
183
|
-
duration: 5000,
|
|
184
|
-
quick: true
|
|
185
|
-
}).then((device_list) => {
|
|
186
|
-
// Do something...
|
|
187
|
-
}).catch((error) => {
|
|
188
|
-
console.error(error);
|
|
189
|
-
});
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
As the `quick` property is set to `true`, the `resolve()` function will be called immediately after a device is found regardless the value of the `duration` property.
|
|
193
|
-
|
|
194
|
-
#### `ondiscover` event handler
|
|
195
|
-
|
|
196
|
-
The `ondiscover` property on the [`Switchbot`](#Switchbot-object) object is an event handler called whenever a device is newly found in the discovery process. A [`SwitchbotDevice`](#SwitchbotDevice-object) object is passed to the callback function set to the `ondiscover` property.
|
|
197
|
-
|
|
198
|
-
```Typescript
|
|
199
|
-
switchBotBLE.ondiscover = (device) => {
|
|
200
|
-
console.log(device.id + ' (' + device.modelName + ')');
|
|
201
|
-
};
|
|
202
|
-
|
|
203
|
-
switchBotBLE.discover().then(() => {
|
|
204
|
-
console.log('The discovery process was finished.');
|
|
205
|
-
}).catch((error) => {
|
|
206
|
-
console.error(error);
|
|
207
|
-
});
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
The code snippet above will output the result as follows:
|
|
211
|
-
|
|
212
|
-
```
|
|
213
|
-
cb4eb903c96d (WoSensorTH)
|
|
214
|
-
c12e453e2008 (WoHand)
|
|
215
|
-
The discovery process was finished.
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
#### `startScan()` method
|
|
219
|
-
|
|
220
|
-
The `startScan()` method starts to scan advertising packets coming from devices. This method takes an argument which is a hash object containing the parameters as follows:
|
|
221
|
-
|
|
222
|
-
| Property | Type | Required | Description |
|
|
223
|
-
| :------- | :----- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
224
|
-
| `model` | String | Optional | `"H"`, `"T"`, `"c"`, `"g"` or `"j"`. If `"H"` is specified, this method will discover only Bots. If `"T"` is specified, this method will discover only Meters. If `"c"` is specified, this method will discover only Curtains. If `"g"` or `"j"` is specified, this method will discover only (US/JP) Plug Minis. |
|
|
225
|
-
| `id` | String | Optional | If this value is set, this method will discover only a device whose ID is as same as this value. The ID is identical to the MAC address. This value is case-insensitive, and colons are ignored. |
|
|
226
|
-
|
|
227
|
-
Whenever a packet is received, the callback function set to the [`onadvertisement`](#Switchbot-onadvertisement-event-handler) property of the [`Switchbot`](#Switchbot-object) object will be called. When a packet is received, a hash object representing the packet will be passed to the callback function.
|
|
228
|
-
|
|
229
|
-
```Typescript
|
|
230
|
-
// Set a callback function called when a packet is received
|
|
231
|
-
switchBotBLE.onadvertisement = (ad) => {
|
|
232
|
-
console.log(ad);
|
|
233
|
-
};
|
|
234
|
-
|
|
235
|
-
// Start to scan advertising packets
|
|
236
|
-
switchBotBLE.startScan({
|
|
237
|
-
id: 'cb:4e:b9:03:c9:6d',
|
|
238
|
-
}).then(() => {
|
|
239
|
-
// Wait for 30 seconds
|
|
240
|
-
return switchBotBLE.wait(30000);
|
|
241
|
-
}).then(() => {
|
|
242
|
-
// Stop to scan
|
|
243
|
-
switchBotBLE.stopScan();
|
|
244
|
-
process.exit();
|
|
245
|
-
}).catch((error) => {
|
|
246
|
-
console.error(error);
|
|
247
|
-
});
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
The code snippet above will output the result as follows:
|
|
251
|
-
|
|
252
|
-
```
|
|
253
|
-
{
|
|
254
|
-
id: 'cb4eb903c96d',
|
|
255
|
-
address: 'cb:4e:b9:03:c9:6d',
|
|
256
|
-
rssi: -65,
|
|
257
|
-
serviceData: {
|
|
258
|
-
model: 'T',
|
|
259
|
-
modelName: 'WoSensorTH',
|
|
260
|
-
celsius: 25.8,
|
|
261
|
-
fahrenheit: 78.4,
|
|
262
|
-
fahrenheit_mode: false,
|
|
263
|
-
humidity: 43,
|
|
264
|
-
battery: 100
|
|
265
|
-
}
|
|
266
|
-
}
|
|
267
|
-
...
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
The `serviceData` property depends on the model of the device. See the section "[Advertisement data](#Advertisement-data)" for the details of the data format.
|
|
271
|
-
|
|
272
|
-
#### `onadvertisement` event handler
|
|
273
|
-
|
|
274
|
-
If a callback function is set to the `onadvertisement` property, the callback function will be called whenever an advertising packet is received from a device during the scan is active (from the moment when the [`startScan()`](#startscan-method) method is called, to the moment when the [`stopScan()`](#Switchbot-stopScan-method) method is called).
|
|
275
|
-
|
|
276
|
-
```typescript
|
|
277
|
-
switchBotBLE.onadvertisement = async (ad: any) => {
|
|
278
|
-
try {
|
|
279
|
-
this.bleEventHandler[ad.address]?.(ad.serviceData)
|
|
280
|
-
} catch (e: any) {
|
|
281
|
-
await this.errorLog(`Failed to handle BLE event, Error: ${e.message ?? e}`)
|
|
282
|
-
}
|
|
283
|
-
}
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
See the section "[`startScan()` method](#startscan-method)" for details.
|
|
287
|
-
|
|
288
|
-
#### `stopScan()` method
|
|
289
|
-
|
|
290
|
-
The `stopScan()` method stops to scan advertising packets coming from devices. This method returns nothing. Note that this method is _not_ asynchronous but synchronous unlike the other methods. See the section "[`startScan()` method](#startscan-method)" for details.
|
|
291
|
-
|
|
292
|
-
```typescript
|
|
293
|
-
try {
|
|
294
|
-
switchBotBLE.stopScan()
|
|
295
|
-
console.log('Stopped BLE scanning to close listening.')
|
|
296
|
-
} catch (e: any) {
|
|
297
|
-
console.error(`Failed to stop BLE scanning, Error: ${e.message ?? e}`)
|
|
298
|
-
}
|
|
299
|
-
```
|
|
300
|
-
|
|
301
|
-
#### `wait()` method
|
|
302
|
-
|
|
303
|
-
The `wait()` method waits for the specified milliseconds. This method takes an integer representing the duration (millisecond). This method returns a `Promise` object.
|
|
304
|
-
|
|
305
|
-
This method has nothing to do with Switchbot devices. It's just a utility method. See the section "[Quick Start](#Quick-Start)" for details of the usage of this method.
|
|
306
|
-
|
|
307
|
-
```typescript
|
|
308
|
-
await switchBotBLE.wait(1000)
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
### `SwitchBotDevice` Object
|
|
312
|
-
|
|
313
|
-
The `SwitchbotDevice` object represents a Switchbot device (Bot, Meter, Curtain, Contact or Motion), which is created through the discovery process triggered by the [`switchBotBLE.discover()`](#discover-method) method.
|
|
314
|
-
|
|
315
|
-
Actually, the `SwitchbotDevice` object is a super class of the [`WoHand`](#SwitchbotDeviceWoHand-object) and `WoSensorTH` objects. The [`WoHand`](#SwitchbotDeviceWoHand-object) object represents a Bot, the `WoSensorTH` object represents a Meter.
|
|
316
|
-
|
|
317
|
-
You can use the properties and methods described in this section on Bot, Meter, Curtain, Contact and Motion. See the section "[`WoHand` object](#SwitchbotDeviceWoHand-object)" for the details of the functionalities available only on Bot. For now, `WoSensorTH` object has no additional functionality.
|
|
318
|
-
|
|
319
|
-
#### Properties
|
|
320
|
-
|
|
321
|
-
The `SwitchbotDevice` object supports the properties as follows:
|
|
322
|
-
|
|
323
|
-
| Property | Type | Description |
|
|
324
|
-
| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
325
|
-
| `id` | String | ID of the device. (e.g., `"cb4eb903c96d"`) |
|
|
326
|
-
| `address` | String | MAC address of the device. Basically it is as same as the value of the `id` except that this value includes `:` in the string. (e.g., `"cb:4e:b9:03:c9:6d"`) |
|
|
327
|
-
| `model` | String | This value is `"H"` "Bot (WoHand)", `"T"` "Meter (WoSensorTH)", `"c"` "Curtain (WoCurtain)", `"d"` "Contact (WoContact)" or `"s"` "Motion (WoMotion)". |
|
|
328
|
-
| `modelName` | String | This value is `"WoHand"`, `"WoSensorTH"`, `WoCurtain`, `WoContect` or `WoMotion`. |
|
|
329
|
-
| `connectionState` | String | This value indicates the BLE connection state. `"connecting"`, `"connected"`, `"disconnecting"`, or `"disconnected"`. |
|
|
330
|
-
| `onconnect` | Function | See the section "[`onconnect` event handler](#SwitchbotDevice-onconnect-event-handler)" for details. |
|
|
331
|
-
| `ondisconnect` | Function | See the section "[`ondisconnect` event handler](#SwitchbotDevice-ondisconnect-event-handler)" for details. |
|
|
332
|
-
|
|
333
|
-
#### `getDeviceName()` method
|
|
334
|
-
|
|
335
|
-
The `getDeviceName()` method fetches the device name saved in the device. This method returns a `Promise` object.
|
|
336
|
-
|
|
337
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
338
|
-
|
|
339
|
-
If the device name is fetched successfully, the device name will be passed to the `resolve()`.
|
|
340
|
-
|
|
341
|
-
```Typescript
|
|
342
|
-
switchbot
|
|
343
|
-
.discover({ model: "H", quick: true })
|
|
344
|
-
.then((device_list) => {
|
|
345
|
-
return device_list[0].getDeviceName();
|
|
346
|
-
})
|
|
347
|
-
.then((name) => {
|
|
348
|
-
console.log(name);
|
|
349
|
-
process.exit();
|
|
350
|
-
})
|
|
351
|
-
.catch((error) => {
|
|
352
|
-
console.error(error);
|
|
353
|
-
process.exit();
|
|
354
|
-
});
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
The code above will output the result as follows:
|
|
358
|
-
|
|
359
|
-
```Typescript
|
|
360
|
-
WoHand;
|
|
361
|
-
```
|
|
362
|
-
|
|
363
|
-
#### `setDeviceName()` method
|
|
364
|
-
|
|
365
|
-
The `setDeviceName()` method update the device name saved in the device with the name specified as the first argument. This method returns a `Promise` object. Nothing will be passed to the `resolve()` function.
|
|
366
|
-
|
|
367
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
368
|
-
|
|
369
|
-
The character set of the device name saved in the device is UTF-8. The byte length of the name must be less than or equal to 20 bytes. If the name consists of only ASCII characters, up to 20 characters would be allowed. But if the name consists of multibyte characters, the upper limit of characters would be fewer than half. For example, Japanese characters could be saved at most 6 characters because most of Japanese characters consume 3 byte per each character.
|
|
370
|
-
|
|
371
|
-
```Typescript
|
|
372
|
-
switchbot
|
|
373
|
-
.discover({ model: "H", quick: true })
|
|
374
|
-
.then((device_list) => {
|
|
375
|
-
return device_list[0].setDeviceName("Bot in kitchen");
|
|
376
|
-
})
|
|
377
|
-
.then(() => {
|
|
378
|
-
console.log("Done.");
|
|
379
|
-
process.exit();
|
|
380
|
-
})
|
|
381
|
-
.catch((error) => {
|
|
382
|
-
console.error(error);
|
|
383
|
-
process.exit();
|
|
384
|
-
});
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
#### `connect()` method
|
|
388
|
-
|
|
389
|
-
The `connect()` method establishes a connection with the device (i.e., pairing). This method returns a `Promise` object. If the device has already been connected, this method does nothing and calls the `resolve()` function immediately.
|
|
390
|
-
|
|
391
|
-
Most of the methods implemented in the `SwitchbotDevice` object automatically connect and disconnect the device. But this mechanism would be absolutely inefficient if you want to manipulate the device repeatedly in the short time.
|
|
392
|
-
|
|
393
|
-
The connection established using the `connect()` method is not disconnected automatically unless the [`disconnect()`](#SwitchbotDevice-disconnect-method) method is explicitly called.
|
|
394
|
-
|
|
395
|
-
The code snippet below establishes a connection with the Bot using the `connect()` method, then puts the Bot's arm down, then waits for 5 seconds, then puts the arm down, finally disconnects the device using the [`disconnect()`](#SwitchbotDevice-disconnect-method) method:
|
|
396
|
-
|
|
397
|
-
```Typescript
|
|
398
|
-
let device = null;
|
|
399
|
-
|
|
400
|
-
switchbot
|
|
401
|
-
.discover({ model: "H", quick: true })
|
|
402
|
-
.then((device_list) => {
|
|
403
|
-
device = device_list[0];
|
|
404
|
-
if (!device) {
|
|
405
|
-
console.log("No device was found.");
|
|
406
|
-
process.exit();
|
|
407
|
-
}
|
|
408
|
-
console.log(device.modelName + " (" + device.address + ") was found.");
|
|
409
|
-
console.log("Connecting...");
|
|
410
|
-
return device.connect();
|
|
411
|
-
})
|
|
412
|
-
.then(() => {
|
|
413
|
-
console.log("Putting the arm down...");
|
|
414
|
-
return device.down();
|
|
415
|
-
})
|
|
416
|
-
.then(() => {
|
|
417
|
-
console.log("Waiting for 5 seconds...");
|
|
418
|
-
return switchBotBLE.wait(5000);
|
|
419
|
-
})
|
|
420
|
-
.then(() => {
|
|
421
|
-
console.log("Putting the arm up...");
|
|
422
|
-
return device.up();
|
|
423
|
-
})
|
|
424
|
-
.then(() => {
|
|
425
|
-
console.log("Disconnecting...");
|
|
426
|
-
return device.disconnect();
|
|
427
|
-
})
|
|
428
|
-
.then(() => {
|
|
429
|
-
console.log("Done.");
|
|
430
|
-
process.exit();
|
|
431
|
-
})
|
|
432
|
-
.catch((error) => {
|
|
433
|
-
console.error(error);
|
|
434
|
-
process.exit();
|
|
435
|
-
});
|
|
436
|
-
```
|
|
32
|
+
BLE is supported on:
|
|
437
33
|
|
|
438
|
-
|
|
34
|
+
- macOS
|
|
35
|
+
- Linux, including Ubuntu, Debian, Raspbian, and similar distributions
|
|
439
36
|
|
|
440
|
-
|
|
441
|
-
WoHand (c1:2e:45:3e:20:08) was found.
|
|
442
|
-
Connecting...
|
|
443
|
-
Putting the arm down...
|
|
444
|
-
Waiting for 5 seconds...
|
|
445
|
-
Putting the arm up...
|
|
446
|
-
Disconnecting...
|
|
447
|
-
Done.
|
|
448
|
-
```
|
|
37
|
+
BLE is not supported on Windows in this package. On Windows, use API-only mode through the unified `SwitchBot` class.
|
|
449
38
|
|
|
450
|
-
|
|
39
|
+
## Requirements
|
|
451
40
|
|
|
452
|
-
|
|
41
|
+
- Node.js `^20 || ^22 || ^24`
|
|
42
|
+
- `@stoprocent/noble` is included as a dependency
|
|
453
43
|
|
|
454
|
-
|
|
44
|
+
## Prerequisites
|
|
455
45
|
|
|
456
|
-
|
|
46
|
+
### macOS
|
|
457
47
|
|
|
458
|
-
|
|
48
|
+
- Install Xcode from the App Store
|
|
49
|
+
- Allow Bluetooth access for your terminal application in System Settings or System Preferences
|
|
459
50
|
|
|
460
|
-
|
|
51
|
+
### Linux (Ubuntu, Debian, Raspbian)
|
|
461
52
|
|
|
462
|
-
|
|
463
|
-
switchbot
|
|
464
|
-
.discover({ model: "H", quick: true })
|
|
465
|
-
.then((device_list) => {
|
|
466
|
-
const device = device_list[0];
|
|
467
|
-
if (!device) {
|
|
468
|
-
console.log("No device was found.");
|
|
469
|
-
process.exit();
|
|
470
|
-
}
|
|
471
|
-
console.log(device.modelName + " (" + device.address + ") was found.");
|
|
472
|
-
|
|
473
|
-
// Set event handers
|
|
474
|
-
device.onconnect = () => {
|
|
475
|
-
console.log("Connected.");
|
|
476
|
-
};
|
|
477
|
-
device.ondisconnect = () => {
|
|
478
|
-
console.log("Disconnected.");
|
|
479
|
-
};
|
|
480
|
-
|
|
481
|
-
console.log("Pressing the switch...");
|
|
482
|
-
return device.press();
|
|
483
|
-
})
|
|
484
|
-
.then(() => {
|
|
485
|
-
console.log("Done.");
|
|
486
|
-
process.exit();
|
|
487
|
-
})
|
|
488
|
-
.catch((error) => {
|
|
489
|
-
console.error(error);
|
|
490
|
-
process.exit();
|
|
491
|
-
});
|
|
492
|
-
```
|
|
53
|
+
Install required packages:
|
|
493
54
|
|
|
494
|
-
|
|
55
|
+
```bash
|
|
56
|
+
sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
|
|
57
|
+
```
|
|
495
58
|
|
|
496
|
-
|
|
497
|
-
WoHand (c1:2e:45:3e:20:08) was found.
|
|
498
|
-
Pressing the switch...
|
|
499
|
-
Connected.
|
|
500
|
-
Disconnected.
|
|
501
|
-
Done.
|
|
502
|
-
```
|
|
59
|
+
For non-root access, also install `libcap2-bin` and grant raw socket capability to `node`:
|
|
503
60
|
|
|
504
|
-
|
|
61
|
+
```bash
|
|
62
|
+
sudo apt-get install libcap2-bin
|
|
63
|
+
sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
|
|
64
|
+
```
|
|
505
65
|
|
|
506
|
-
|
|
66
|
+
On Raspberry Pi, if BLE connections are unstable, you may need to disable the `pnat` plugin in `/etc/bluetooth/main.conf` and restart Bluetooth or reboot.
|
|
507
67
|
|
|
508
|
-
|
|
68
|
+
### Fedora and Other RPM-Based Linux
|
|
509
69
|
|
|
510
|
-
|
|
70
|
+
```bash
|
|
71
|
+
sudo yum install bluez bluez-libs bluez-libs-devel
|
|
72
|
+
```
|
|
511
73
|
|
|
512
|
-
|
|
74
|
+
For more platform details, see the `@stoprocent/noble` prerequisites documentation.
|
|
513
75
|
|
|
514
|
-
|
|
76
|
+
## Unified BLE Usage
|
|
515
77
|
|
|
516
|
-
|
|
78
|
+
### BLE-Only Mode
|
|
517
79
|
|
|
518
|
-
|
|
80
|
+
Use BLE without OpenAPI credentials:
|
|
519
81
|
|
|
520
|
-
|
|
82
|
+
```typescript
|
|
83
|
+
import { LogLevel, SwitchBot } from 'node-switchbot'
|
|
521
84
|
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
return device_list[0].press();
|
|
527
|
-
})
|
|
528
|
-
.then(() => {
|
|
529
|
-
console.log("Done.");
|
|
85
|
+
const switchbot = new SwitchBot({
|
|
86
|
+
enableBLE: true,
|
|
87
|
+
enableFallback: false,
|
|
88
|
+
logLevel: LogLevel.INFO,
|
|
530
89
|
})
|
|
531
|
-
.catch((error) => {
|
|
532
|
-
console.error(error);
|
|
533
|
-
});
|
|
534
|
-
```
|
|
535
|
-
|
|
536
|
-
When the Bot receives this command, the Bot's arm will be put down (stretched), then put up (retracted) in a few seconds.
|
|
537
|
-
|
|
538
|
-
#### `turnOn()` method
|
|
539
|
-
|
|
540
|
-
The `turnOn()` method sends a turn-on command to the Bot. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
|
|
541
|
-
|
|
542
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
543
|
-
|
|
544
|
-
When the Bot receives this command, the Bot's arm will be put down (stretched) or put up (retracted) depending on the mode setting.
|
|
545
90
|
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
| | Enabled | Up (retracted) |
|
|
551
|
-
|
|
552
|
-
```Typescript
|
|
553
|
-
switchbot
|
|
554
|
-
.discover({ model: "H", quick: true })
|
|
555
|
-
.then((device_list) => {
|
|
556
|
-
return device_list[0].turnOn();
|
|
91
|
+
const devices = await switchbot.discover({
|
|
92
|
+
scanBLE: true,
|
|
93
|
+
fetchAPI: false,
|
|
94
|
+
timeout: 10_000,
|
|
557
95
|
})
|
|
558
|
-
.then(() => {
|
|
559
|
-
console.log("Done.");
|
|
560
|
-
})
|
|
561
|
-
.catch((error) => {
|
|
562
|
-
console.error(error);
|
|
563
|
-
});
|
|
564
|
-
```
|
|
565
|
-
|
|
566
|
-
#### `turnOff()` method
|
|
567
|
-
|
|
568
|
-
The `turnOff()` method sends a turn-off command to the Bot. This method returns a `Promise` object. Nothing will be passed to the `resove()`.
|
|
569
|
-
|
|
570
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
571
|
-
|
|
572
|
-
When the Bot receives this command, the Bot's arm will be put down (stretched) or put up (retracted) depending on the mode setting.
|
|
573
96
|
|
|
574
|
-
|
|
575
|
-
| :---------- | :--------------------------- | :------------------------------------ |
|
|
576
|
-
| Press mode | N/A | Down (stretched), then Up (retracted) |
|
|
577
|
-
| Switch mode | Disabled | Up (retracted) |
|
|
578
|
-
| | Enabled | Down (stretched) |
|
|
97
|
+
console.log(`Found ${devices.length} BLE device(s)`)
|
|
579
98
|
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
return device_list[0].turnOff();
|
|
585
|
-
})
|
|
586
|
-
.then(() => {
|
|
587
|
-
console.log("Done.");
|
|
588
|
-
})
|
|
589
|
-
.catch((error) => {
|
|
590
|
-
console.error(error);
|
|
591
|
-
});
|
|
592
|
-
```
|
|
99
|
+
const bot = switchbot.devices.get('YOUR_DEVICE_ID')
|
|
100
|
+
if (bot) {
|
|
101
|
+
await bot.press()
|
|
102
|
+
}
|
|
593
103
|
|
|
594
|
-
|
|
104
|
+
await switchbot.cleanup()
|
|
105
|
+
```
|
|
595
106
|
|
|
596
|
-
|
|
107
|
+
### Hybrid BLE + API Mode
|
|
597
108
|
|
|
598
|
-
|
|
109
|
+
Use BLE first, with automatic API fallback when needed:
|
|
599
110
|
|
|
600
|
-
|
|
111
|
+
```typescript
|
|
112
|
+
import { LogLevel, SwitchBot } from 'node-switchbot'
|
|
601
113
|
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
114
|
+
const switchbot = new SwitchBot({
|
|
115
|
+
token: 'YOUR_TOKEN',
|
|
116
|
+
secret: 'YOUR_SECRET',
|
|
117
|
+
enableBLE: true,
|
|
118
|
+
enableFallback: true,
|
|
119
|
+
enableConnectionIntelligence: true,
|
|
120
|
+
enableCircuitBreaker: true,
|
|
121
|
+
enableRetry: true,
|
|
122
|
+
logLevel: LogLevel.INFO,
|
|
607
123
|
})
|
|
608
|
-
.then(() => {
|
|
609
|
-
console.log("Done.");
|
|
610
|
-
})
|
|
611
|
-
.catch((error) => {
|
|
612
|
-
console.error(error);
|
|
613
|
-
});
|
|
614
|
-
```
|
|
615
124
|
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
621
|
-
|
|
622
|
-
When the Bot receives this command, the Bot's arm will be put up (retracted) regardless of the mode setting.
|
|
623
|
-
|
|
624
|
-
```Typescript
|
|
625
|
-
switchbot
|
|
626
|
-
.discover({ model: "H", quick: true })
|
|
627
|
-
.then((device_list) => {
|
|
628
|
-
return device_list[0].up();
|
|
629
|
-
})
|
|
630
|
-
.then(() => {
|
|
631
|
-
console.log("Done.");
|
|
125
|
+
await switchbot.discover({
|
|
126
|
+
scanBLE: true,
|
|
127
|
+
fetchAPI: true,
|
|
128
|
+
timeout: 10_000,
|
|
632
129
|
})
|
|
633
|
-
.catch((error) => {
|
|
634
|
-
console.error(error);
|
|
635
|
-
});
|
|
636
|
-
```
|
|
637
|
-
|
|
638
|
-
#### Password Protection
|
|
639
130
|
|
|
640
|
-
|
|
131
|
+
const curtain = switchbot.devices.get('YOUR_CURTAIN_ID')
|
|
132
|
+
if (curtain) {
|
|
133
|
+
await curtain.open()
|
|
134
|
+
const status = await curtain.getStatus()
|
|
135
|
+
console.log(status)
|
|
136
|
+
}
|
|
641
137
|
|
|
642
|
-
|
|
138
|
+
await switchbot.cleanup()
|
|
139
|
+
```
|
|
643
140
|
|
|
644
|
-
|
|
645
|
-
- Alphanumeric only (letters and numbers)
|
|
646
|
-
- Case-sensitive
|
|
141
|
+
## Discovery Options
|
|
647
142
|
|
|
648
|
-
|
|
143
|
+
`switchbot.discover()` accepts the following v4 options:
|
|
649
144
|
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
145
|
+
| Property | Type | Description |
|
|
146
|
+
| :-- | :-- | :-- |
|
|
147
|
+
| `scanBLE` | `boolean` | Enable BLE discovery for this call |
|
|
148
|
+
| `fetchAPI` | `boolean` | Fetch devices from OpenAPI for this call |
|
|
149
|
+
| `timeout` | `number` | Discovery timeout in milliseconds |
|
|
150
|
+
| `deviceId` | `string` | Filter by SwitchBot device ID |
|
|
151
|
+
| `mac` | `string` | Filter by MAC address |
|
|
152
|
+
| `deviceType` | `string` | Filter by device type |
|
|
656
153
|
|
|
657
|
-
|
|
658
|
-
await bot.setPassword('A1b2')
|
|
659
|
-
```
|
|
154
|
+
## Device Access Pattern
|
|
660
155
|
|
|
661
|
-
|
|
156
|
+
After discovery, use the device manager:
|
|
662
157
|
|
|
663
|
-
```typescript
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
158
|
+
```typescript
|
|
159
|
+
const devices = switchbot.devices.list()
|
|
160
|
+
const bot = switchbot.devices.get('YOUR_DEVICE_ID')
|
|
161
|
+
const curtains = switchbot.devices.getByType('WoCurtain')
|
|
162
|
+
```
|
|
667
163
|
|
|
668
|
-
|
|
164
|
+
Common device helpers include:
|
|
669
165
|
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
}
|
|
675
|
-
```
|
|
166
|
+
- `getInfo()`
|
|
167
|
+
- `getName()`
|
|
168
|
+
- `getDeviceType()`
|
|
169
|
+
- `getStatus()`
|
|
676
170
|
|
|
677
|
-
|
|
171
|
+
Commands vary by device class. Examples:
|
|
678
172
|
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
.then((device_list) => {
|
|
683
|
-
const bot = device_list[0]
|
|
684
|
-
// Set password for protected Bot
|
|
685
|
-
bot.setPassword('MyP4')
|
|
686
|
-
return bot.press()
|
|
687
|
-
})
|
|
688
|
-
.then(() => {
|
|
689
|
-
console.log('Password-protected Bot pressed successfully')
|
|
690
|
-
})
|
|
691
|
-
.catch((error) => {
|
|
692
|
-
console.error(error)
|
|
693
|
-
})
|
|
694
|
-
```
|
|
173
|
+
- Bot: `press()`, `turnOn()`, `turnOff()`, `handUp()`, `handDown()`
|
|
174
|
+
- Curtain: `open()`, `close()`, `pause()`, `setPosition()`
|
|
175
|
+
- Plug: `turnOn()`, `turnOff()`, `toggle()`
|
|
695
176
|
|
|
696
|
-
|
|
177
|
+
## Bot Password Protection
|
|
697
178
|
|
|
698
|
-
|
|
699
|
-
- All control methods (press, turnOn, turnOff, up, down) automatically use encrypted commands when password is set
|
|
700
|
-
- Password is stored in memory only and must be set each time the application starts
|
|
701
|
-
- If the wrong password is configured, BLE commands will fail silently (Bot will not respond)
|
|
179
|
+
Bot (`WoHand`) devices support password-protected BLE commands in v4.
|
|
702
180
|
|
|
703
|
-
###
|
|
181
|
+
### What It Adds
|
|
704
182
|
|
|
705
|
-
|
|
183
|
+
- Password validation for exactly 4 alphanumeric characters
|
|
184
|
+
- CRC32-based encrypted BLE command construction
|
|
185
|
+
- Automatic encrypted command execution when a password is configured
|
|
186
|
+
- Runtime helpers: `setPassword()`, `clearPassword()`, `hasPassword()`
|
|
706
187
|
|
|
707
|
-
|
|
188
|
+
### Supported Commands
|
|
708
189
|
|
|
709
|
-
|
|
190
|
+
When a password is set, these BLE Bot commands use the encrypted flow:
|
|
710
191
|
|
|
711
|
-
|
|
192
|
+
- `press()`
|
|
193
|
+
- `turnOn()`
|
|
194
|
+
- `turnOff()`
|
|
195
|
+
- `handUp()`
|
|
196
|
+
- `handDown()`
|
|
712
197
|
|
|
713
|
-
|
|
198
|
+
### Example
|
|
714
199
|
|
|
715
|
-
|
|
200
|
+
```typescript
|
|
201
|
+
import { LogLevel, SwitchBot, WoHand } from 'node-switchbot'
|
|
716
202
|
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
.discover({ model: "c", quick: true })
|
|
722
|
-
.then((device_list) => {
|
|
723
|
-
return device_list[0].open();
|
|
724
|
-
})
|
|
725
|
-
.then(() => {
|
|
726
|
-
console.log("Done.");
|
|
203
|
+
const switchbot = new SwitchBot({
|
|
204
|
+
enableBLE: true,
|
|
205
|
+
enableFallback: false,
|
|
206
|
+
logLevel: LogLevel.INFO,
|
|
727
207
|
})
|
|
728
|
-
.catch((error) => {
|
|
729
|
-
console.error(error);
|
|
730
|
-
});
|
|
731
|
-
```
|
|
732
|
-
|
|
733
|
-
#### `close()` method
|
|
734
208
|
|
|
735
|
-
|
|
209
|
+
await switchbot.discover({ scanBLE: true, fetchAPI: false })
|
|
736
210
|
|
|
737
|
-
|
|
211
|
+
const bot = switchbot.devices.get('YOUR_DEVICE_ID') as WoHand | undefined
|
|
212
|
+
if (bot) {
|
|
213
|
+
bot.setPassword('A1b2')
|
|
738
214
|
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
215
|
+
if (bot.hasPassword()) {
|
|
216
|
+
await bot.press()
|
|
217
|
+
}
|
|
742
218
|
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
.discover({ model: "c", quick: true })
|
|
746
|
-
.then((device_list) => {
|
|
747
|
-
return device_list[0].close();
|
|
748
|
-
})
|
|
749
|
-
.then(() => {
|
|
750
|
-
console.log("Done.");
|
|
751
|
-
})
|
|
752
|
-
.catch((error) => {
|
|
753
|
-
console.error(error);
|
|
754
|
-
});
|
|
755
|
-
```
|
|
219
|
+
bot.clearPassword()
|
|
220
|
+
}
|
|
756
221
|
|
|
757
|
-
|
|
222
|
+
await switchbot.cleanup()
|
|
223
|
+
```
|
|
758
224
|
|
|
759
|
-
|
|
225
|
+
Notes:
|
|
760
226
|
|
|
761
|
-
|
|
227
|
+
- Passwords are stored in memory only
|
|
228
|
+
- The password must be configured again when your application starts
|
|
229
|
+
- Password-protected Bot commands require BLE and do not use OpenAPI fallback for the encrypted write path
|
|
762
230
|
|
|
763
|
-
|
|
231
|
+
## Reliability Features in BLE Workflows
|
|
764
232
|
|
|
765
|
-
|
|
766
|
-
switchbot
|
|
767
|
-
.discover({ model: "c", quick: true })
|
|
768
|
-
.then((device_list) => {
|
|
769
|
-
return device_list[0].pause();
|
|
770
|
-
})
|
|
771
|
-
.then(() => {
|
|
772
|
-
console.log("Done.");
|
|
773
|
-
})
|
|
774
|
-
.catch((error) => {
|
|
775
|
-
console.error(error);
|
|
776
|
-
});
|
|
777
|
-
```
|
|
233
|
+
The v4 BLE path includes the resilience features introduced in the 4.0.0 release:
|
|
778
234
|
|
|
779
|
-
|
|
235
|
+
- Automatic retry with exponential backoff and jitter
|
|
236
|
+
- Circuit breaker state management to avoid repeated failing connections
|
|
237
|
+
- Connection intelligence that can prefer the more reliable path over time
|
|
238
|
+
- Fallback hooks for custom logging, metrics, or alerting
|
|
780
239
|
|
|
781
|
-
|
|
240
|
+
These behaviors are primarily exposed through the unified `SwitchBot` and `SwitchBotDevice` flow rather than through manual low-level BLE orchestration.
|
|
782
241
|
|
|
783
|
-
|
|
242
|
+
## Low-Level BLE APIs
|
|
784
243
|
|
|
785
|
-
|
|
244
|
+
If you need raw scanning or connection control, v4 exports `BLEScanner` and `BLEConnection` directly.
|
|
786
245
|
|
|
787
|
-
|
|
246
|
+
### `BLEScanner`
|
|
788
247
|
|
|
789
|
-
|
|
248
|
+
Use this for advertisement scanning and device discovery without going through `SwitchBot`.
|
|
790
249
|
|
|
791
|
-
|
|
250
|
+
```typescript
|
|
251
|
+
import { BLEScanner } from 'node-switchbot'
|
|
792
252
|
|
|
793
|
-
|
|
794
|
-
| :-------- | :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
795
|
-
| `percent` | Integer | Required | The percentage of target position (`0-100`). (e.g., `50`) |
|
|
796
|
-
| `mode` | Integer | Optional | The running mode of Curtain. <br/>`0x00` - Performance mode.<br/> `0x01` - Silent mode. <br/>`0xff` - Default. Unspecified, from Curtain's settings. |
|
|
253
|
+
const scanner = new BLEScanner()
|
|
797
254
|
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
.discover({ model: "c", quick: true })
|
|
801
|
-
.then((device_list) => {
|
|
802
|
-
return device_list[0].runToPos(50);
|
|
803
|
-
})
|
|
804
|
-
.then(() => {
|
|
805
|
-
console.log("Done.");
|
|
255
|
+
scanner.on('discover', (advertisement) => {
|
|
256
|
+
console.log(advertisement)
|
|
806
257
|
})
|
|
807
|
-
.catch((error) => {
|
|
808
|
-
console.error(error);
|
|
809
|
-
});
|
|
810
|
-
```
|
|
811
|
-
|
|
812
|
-
### `WoPlugMini` Object
|
|
813
|
-
|
|
814
|
-
The `WoPlugMini ` object represents a PlugMini, which is created through the discovery process triggered by the [`switchBotBLE.discover()`](#discover-method) method.
|
|
815
|
-
|
|
816
|
-
Actually, the `WoPlugMini ` is an object inherited from the [`SwitchbotDevice`](#SwitchbotDevice-object). You can use not only the method described in this section but also the properties and methods implemented in the [`SwitchbotDevice`](#SwitchbotDevice-object) object.
|
|
817
|
-
|
|
818
|
-
#### `turnOn()` method
|
|
819
|
-
|
|
820
|
-
The `turnOn()` method sends a turn-on command to the PlugMini. This method returns a `Promise` object. A `boolean` value indicating whether the PlugMini is on (`true`), is passed to the `resolve()` method of the Promise.
|
|
821
|
-
|
|
822
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
823
|
-
|
|
824
|
-
#### `turnOff()` method
|
|
825
|
-
|
|
826
|
-
The `turnOff()` method sends a turn-off command to the PlugMini. This method returns a `Promise` object. A `boolean` value indicating whether the PlugMini is off (`false`), is passed to the `resolve()` method of the Promise.
|
|
827
|
-
|
|
828
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
829
|
-
|
|
830
|
-
#### `toggle()` method
|
|
831
|
-
|
|
832
|
-
The `toggle()` method sends a toggle command to the PlugMini, toggling between the on and off state. This method returns a `Promise` object. A `boolean` value indicating whether the PlugMini is on (`true`) or off (`false`), is passed to the `resolve()` method of the Promise.
|
|
833
|
-
|
|
834
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
835
|
-
|
|
836
|
-
### `WoSmartLock` Object
|
|
837
258
|
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
Actually, the `WoSmartLock ` is an object inherited from the [`SwitchbotDevice`](#SwitchbotDevice-object). You can use not only the method described in this section but also the properties and methods implemented in the [`SwitchbotDevice`](#SwitchbotDevice-object) object.
|
|
841
|
-
|
|
842
|
-
#### `setKey()` method
|
|
843
|
-
|
|
844
|
-
The `setKey()` method initialises the key information required for encrypted communication with the SmartLock
|
|
845
|
-
|
|
846
|
-
This must be set before any control commands are sent to the device. To obtain the key information you will need to use an external tool - see [`pySwitchbot`](https://github.com/Danielhiversen/pySwitchbot/tree/master?tab=readme-ov-file#obtaining-locks-encryption-key) project for an example script.
|
|
847
|
-
Or, use [`switchbot-get-encryption-key`](https://www.npmjs.com/package/switchbot-get-encryption-key) npm script.
|
|
848
|
-
|
|
849
|
-
| Property | Type | Description |
|
|
850
|
-
| :-------------- | :----- | :----------------------------------------------------------------------------------------------- |
|
|
851
|
-
| `keyId` | String | unique2 character ID for the key. (e.g., `"ff"`) returned from the SwitchBot api for your device |
|
|
852
|
-
| `encryptionKey` | String | the unique encryption key returned from the SwitchBot api for your device |
|
|
853
|
-
|
|
854
|
-
#### `lock()` method
|
|
855
|
-
|
|
856
|
-
The `lock()` method sends a lock command to the SmartLock. This method returns a `Promise` object. A `boolean` value indicating whether the SmartLock is locked (`true`), is passed to the `resolve()` method of the Promise.
|
|
857
|
-
|
|
858
|
-
If no connection is established with the device, this method automatically establishes a connection with the device, then finally closes the connection. You don't have to call the [`connect()`](#SwitchbotDevice-connect-method) method in advance.
|
|
859
|
-
|
|
860
|
-
#### `unlock()` method
|
|
861
|
-
|
|
862
|
-
The `unlock()` method sends an unlock command to the SmartLock. This method returns a `Promise` object. A `boolean` value indicating whether the SmartLock is locked (`false`), is passed to the `resolve()` method of the Promise.
|
|
259
|
+
await scanner.startScan({ duration: 10_000, active: true })
|
|
260
|
+
```
|
|
863
261
|
|
|
864
|
-
|
|
262
|
+
Public methods:
|
|
865
263
|
|
|
866
|
-
|
|
264
|
+
- `startScan(options?)`
|
|
265
|
+
- `stopScan()`
|
|
266
|
+
- `getDiscoveredDevices()`
|
|
267
|
+
- `getDevice(mac, bleId?)`
|
|
268
|
+
- `waitForDevice(mac, timeoutMs?, bleId?)`
|
|
269
|
+
- `destroy()`
|
|
867
270
|
|
|
868
|
-
|
|
271
|
+
Events:
|
|
869
272
|
|
|
870
|
-
|
|
273
|
+
- `ready`
|
|
274
|
+
- `state-change`
|
|
275
|
+
- `scan-start`
|
|
276
|
+
- `scan-stop`
|
|
277
|
+
- `discover`
|
|
871
278
|
|
|
872
|
-
|
|
279
|
+
### `BLEConnection`
|
|
873
280
|
|
|
874
|
-
|
|
281
|
+
Use this for low-level connection, write, and notification handling.
|
|
875
282
|
|
|
876
|
-
|
|
283
|
+
```typescript
|
|
284
|
+
import { BLEConnection } from 'node-switchbot'
|
|
285
|
+
import { Buffer } from 'node:buffer'
|
|
877
286
|
|
|
878
|
-
|
|
287
|
+
const connection = new BLEConnection()
|
|
879
288
|
|
|
880
|
-
|
|
289
|
+
await connection.connect('AA:BB:CC:DD:EE:FF')
|
|
290
|
+
await connection.write('AA:BB:CC:DD:EE:FF', Buffer.from([0x57, 0x01, 0x00]))
|
|
291
|
+
const response = await connection.read('AA:BB:CC:DD:EE:FF')
|
|
881
292
|
|
|
882
|
-
|
|
883
|
-
// Load the node-switchbot and get a `Switchbot` constructor object
|
|
884
|
-
import { SwitchBotBLE } from 'node-switchbot';
|
|
885
|
-
// Create a `Switchbot` object
|
|
886
|
-
const switchBotBLE = new SwitchBotBLE();
|
|
293
|
+
console.log(response)
|
|
887
294
|
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
await switchBotBLE.startScan();
|
|
891
|
-
// Set an event handler
|
|
892
|
-
switchBotBLE.onadvertisement = (ad) => {
|
|
893
|
-
console.log(JSON.stringify(ad, null, ' '));
|
|
894
|
-
};
|
|
895
|
-
// Wait 10 seconds
|
|
896
|
-
await switchBotBLE.wait(10000);
|
|
897
|
-
// Stop to monitor
|
|
898
|
-
switchBotBLE.stopScan();
|
|
899
|
-
process.exit();
|
|
900
|
-
})();
|
|
901
|
-
```
|
|
902
|
-
|
|
903
|
-
An object containing the properties as follows will be passed to the event handler:
|
|
904
|
-
|
|
905
|
-
| Property | Type | Description |
|
|
906
|
-
| :------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
907
|
-
| `id` | String | ID of the device. (e.g., `"cb4eb903c96d"`) |
|
|
908
|
-
| `address` | String | MAC address of the device. Basically it is as same as the value of the `id` except that this value includes `:` in the string. (e.g., `"cb:4e:b9:03:c9:6d"`) |
|
|
909
|
-
| `rssi` | Integer | RSSI. (e.g., `-62`) |
|
|
910
|
-
| `serviceData` | Object | An object including the device-specific data. |
|
|
911
|
-
|
|
912
|
-
The structures of the `serviceData` are described in the following sections.
|
|
295
|
+
await connection.disconnectAll()
|
|
296
|
+
```
|
|
913
297
|
|
|
914
|
-
|
|
298
|
+
Key public methods:
|
|
915
299
|
|
|
916
|
-
|
|
300
|
+
- `connect(mac)`
|
|
301
|
+
- `write(mac, data)`
|
|
302
|
+
- `read(mac)`
|
|
303
|
+
- `disconnectAll()`
|
|
304
|
+
- `setPersistentConnectionTimeout(timeoutMs)`
|
|
305
|
+
- `setEncryption(mac, keyHex, ivHex, mode?)`
|
|
306
|
+
- `clearEncryption(mac)`
|
|
917
307
|
|
|
918
|
-
|
|
919
|
-
{
|
|
920
|
-
"id": "c12e453e2008",
|
|
921
|
-
"address": "c1:2e:45:3e:20:08",
|
|
922
|
-
"rssi": -61,
|
|
923
|
-
"serviceData": {
|
|
924
|
-
"model": "H",
|
|
925
|
-
"modelName": "WoHand",
|
|
926
|
-
"mode": true,
|
|
927
|
-
"state": false,
|
|
928
|
-
"battery": 100
|
|
929
|
-
}
|
|
930
|
-
}
|
|
931
|
-
```
|
|
308
|
+
## BLE-Supported Device Families
|
|
932
309
|
|
|
933
|
-
|
|
310
|
+
v4 BLE support includes, among others:
|
|
934
311
|
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
312
|
+
- Bot
|
|
313
|
+
- Curtain and Roller Shade
|
|
314
|
+
- Blind Tilt
|
|
315
|
+
- Meter family
|
|
316
|
+
- Plug Mini family
|
|
317
|
+
- Lock family
|
|
318
|
+
- Humidifier family
|
|
319
|
+
- Bulb and light families
|
|
320
|
+
- Leak, contact, and presence sensors
|
|
321
|
+
- Relay switch family
|
|
942
322
|
|
|
943
|
-
|
|
323
|
+
Exact per-device behavior still depends on what the physical device exposes over BLE.
|
|
944
324
|
|
|
945
|
-
|
|
325
|
+
## Summary
|
|
946
326
|
|
|
947
|
-
|
|
948
|
-
| :----------------------------- | :------------------- | :------------ | :-------------------- |
|
|
949
|
-
| disabled | `true` | OFF | Up (retracted) |
|
|
950
|
-
| | `false` | ON | Down (stretched) |
|
|
327
|
+
Use `SwitchBot` for almost all v4 BLE workflows. Reach for `BLEScanner` and `BLEConnection` only when you need direct advertisement scanning or manual low-level BLE control.
|
|
951
328
|
| enabled | `true` | OFF | Down (stretched) |
|
|
952
329
|
| | `false` | ON | Up (retracted) |
|
|
953
330
|
|