|
8 | 8 | </span> |
9 | 9 |
|
10 | 10 | The node-switchbot is a Node.js module which allows you to move your [Switchbot (Bot)'s](https://www.switch-bot.com/bot) arm |
11 | | -and [Switchbot Curtain](https://www.switch-bot.com/products/switchbot-curtain), |
| 11 | +and [Switchbot Curtain](https://www.switch-bot.com/products/switchbot-curtain), operate your [Switchbot Lock](https://www.switch-bot.com/products/switchbot-lock), |
12 | 12 | also monitor the temperature/humidity from [SwitchBot Thermometer & Hygrometer (Meter)](https://www.switch-bot.com/meter) |
13 | 13 | as well as the status from [SwitchBot Motion Sensor](https://www.switch-bot.com/products/motion-sensor) |
14 | 14 | and [SwitchBot Contact Sensor](https://www.switch-bot.com/products/contact-sensor) |
@@ -43,21 +43,26 @@ But some functionalities of this module were developed through trial and error. |
43 | 43 | - [`disconnect()` method](#disconnect-method) |
44 | 44 | - [`onconnect` event handler](#onconnect-event-handler) |
45 | 45 | - [`ondisconnect` event handler](#ondisconnect-event-handler) |
46 | | - - [`WoHand` object](#switchbotdevicewohand-object) |
| 46 | + - [`WoHand` object](#wohand-object) |
47 | 47 | - [`press()` method](#press-method) |
48 | 48 | - [`turnOn()` method](#turnon-method) |
49 | 49 | - [`turnOff()` method](#turnoff-method) |
50 | 50 | - [`down()` method](#down-method) |
51 | 51 | - [`up()` method](#up-method) |
52 | | - - [`WoCurtain` object](#switchbotdevicewocurtain-object) |
| 52 | + - [`WoCurtain` object](#wocurtain-object) |
53 | 53 | - [`open()` method](#open-method) |
54 | 54 | - [`close()` method](#close-method) |
55 | 55 | - [`pause()` method](#pause-method) |
56 | 56 | - [`runToPos()` method](#runtopos-method) |
57 | | - - [`WoPlugMini` object](#switchbotdevicewoplugmini-object) |
| 57 | + - [`WoPlugMini` object](#woplugmini-object) |
58 | 58 | - [`turnOn()` method](#turnon-method) |
59 | 59 | - [`turnOff()` method](#turnoff-method) |
60 | 60 | - [`toggle()` method](#toggle-method) |
| 61 | + - [`WoSmartLock` object](#wosmartlock-object) |
| 62 | + - [`lock()` method](#lock-method) |
| 63 | + - [`unlock()` method](#unlock-method) |
| 64 | + - [`unlock_no_unlatch()` method](#unlock_no_unlatch-method) |
| 65 | + - [`info()` method](#info-method) |
61 | 66 | - [Advertisement data](#advertisement-data) |
62 | 67 | - [Bot (WoHand)](#bot-wohand) |
63 | 68 | - [Meter (WoSensorTH)](#meter-wosensorth) |
@@ -876,6 +881,49 @@ If no connection is established with the device, this method automatically estab |
876 | 881 |
|
877 | 882 | --- |
878 | 883 |
|
| 884 | +--- |
| 885 | +## `WoSmartLock` object |
| 886 | + |
| 887 | +The `WoSmartLock ` object represents a SmartLock, which is created through the discovery process triggered by the [`Switchbot.discover()`](#Switchbot-discover-method) method. |
| 888 | + |
| 889 | +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. |
| 890 | + |
| 891 | +### `setKey()` method |
| 892 | + |
| 893 | +The `setKey()` method initialises the key information required for encrypted communication with the SmartLock |
| 894 | + |
| 895 | +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. |
| 896 | + |
| 897 | +| Property | Type | Description | |
| 898 | +| :--------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------- | |
| 899 | +| `keyId` | String | unique2 character ID for the key. (e.g., `"ff"`) returned from the SwitchBot api for your device | |
| 900 | +| `encryptionKey` | String | the unique encryption key returned from the SwitchBot api for your device | |
| 901 | + |
| 902 | +### `lock()` method |
| 903 | + |
| 904 | +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. |
| 905 | + |
| 906 | +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. |
| 907 | + |
| 908 | +### `unlock()` method |
| 909 | + |
| 910 | +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. |
| 911 | + |
| 912 | +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. |
| 913 | + |
| 914 | +### `unlockNoUnlatch()` method |
| 915 | + |
| 916 | +The `unlockNoUnlatch()` method sends a partial unlock command to the SmartLock, unlocking without the full unlatch. |
| 917 | + |
| 918 | +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. |
| 919 | + |
| 920 | +### `info()` method |
| 921 | + |
| 922 | +The `info()` method retreieves state information from the SmartLock, This method returns a `Promise` object. An `object` value indicating with the state infor, is passed to the `resolve()` method of the Promise. |
| 923 | + |
| 924 | +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. |
| 925 | + |
| 926 | + |
879 | 927 | ## Advertisement data |
880 | 928 |
|
881 | 929 | After the [`startScan()`](#startscan-method) method is invoked, the [`onadvertisement`](#Switchbot-onadvertisement-event-handler) event handler will be called whenever an advertising packet comes from the switchbot devices. An object containing the properties as follows will be passed to the event handler: |
@@ -1101,6 +1149,53 @@ Structure of the `serviceData`: |
1101 | 1149 |
|
1102 | 1150 | --- |
1103 | 1151 |
|
| 1152 | +### SmartLock (WoSmartLock) |
| 1153 | + |
| 1154 | +Example of the advertisement data: |
| 1155 | + |
| 1156 | +```json |
| 1157 | +{ |
| 1158 | + "id: 'd30864110b8c', |
| 1159 | + "address": 'd3:08:64:11:0b:8c', |
| 1160 | + "rssi": -52, |
| 1161 | + "serviceData": { |
| 1162 | + "model": "o", |
| 1163 | + "modelName": "WoSmartLock", |
| 1164 | + "battery": 100, |
| 1165 | + "calibration": true, |
| 1166 | + "status": "LOCKED", |
| 1167 | + "update_from_secondary_lock": false, |
| 1168 | + "door_open": false, |
| 1169 | + "double_lock_mode": false, |
| 1170 | + "unclosed_alarm": false, |
| 1171 | + "unlocked_alarm": false, |
| 1172 | + "auto_lock_paused": false |
| 1173 | + } |
| 1174 | +} |
| 1175 | + |
| 1176 | +``` |
| 1177 | + |
| 1178 | +Structure of the `serviceData`: |
| 1179 | + |
| 1180 | +| Property | Type | Description | |
| 1181 | +| :---------------------------- | :------ | :---------------------------------------------------------------------------------- | |
| 1182 | +| `model` | String | This value is `"o"`, which means "Lock (WoSmartLock)". | |
| 1183 | +| `modelName` | String | This value is always `"WoSmartLock"`, which means "Lock". | |
| 1184 | +| `battery` | Integer | This value indicates the battery level (`1-100`, `%`). | |
| 1185 | +| `calibration` | Boolean | This value indicates the calibration status (`true` or `false`). | |
| 1186 | +| `status` | String | This value indicates the current locked state. Possible values: | |
| 1187 | +| | | `"LOCKED"`, `"UNLOCKED"`, `"LOCKING"`, `"UNLOCKING"` | |
| 1188 | +| | | `"LOCKING_STOP"`, `"UNLOCKING_STOP"` (stuck when locking or unlocking respectively) | |
| 1189 | +| | | `"NOT_FULLY_LOCKED"` (eu model only), `"UNKNOWN"` (fallback: must be some error) | |
| 1190 | +| `update_from_secondary_lock` | Boolean | ?? | |
| 1191 | +| `door_open` | Boolean | door open status - whether the door is not detecting the sensor magnet | |
| 1192 | +| `double_lock_mode` | Boolean | dual lock mode enabled status - two locks working simultaneously | |
| 1193 | +| `unclosed_alarm` | Boolean | enabled status for door ajar alarm function | |
| 1194 | +| `unlocked_alarm` | Boolean | whether the alarm function is enabled for door left unlocked | |
| 1195 | +| `auto_lock_paused` | Boolean | auto lock mode paused | |
| 1196 | +| `night_latch` | Boolean | night latch mode enabled (eu firmware only) | |
| 1197 | + |
| 1198 | + |
1104 | 1199 | ## References |
1105 | 1200 |
|
1106 | 1201 | - [Switchbot official global site](https://www.switch-bot.com/) |
|
0 commit comments