From 95578fa57a9bc79c89f1dbe29ddcd4736adb65f0 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 01/24] Lock Ultra: fix deviceType mix-up, lockState/doorState values, add onlineStatus and webhook doorState --- devices/locks-security/lock-ultra.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/devices/locks-security/lock-ultra.md b/devices/locks-security/lock-ultra.md index ca24e57..9b9900d 100644 --- a/devices/locks-security/lock-ultra.md +++ b/devices/locks-security/lock-ultra.md @@ -22,14 +22,15 @@ | Key | Value Type | Description | | ----------- | ---------- | ---------------------------------------------------------- | -| deviceId | String | device ID | -| deviceType | String | device type. _Lock Ultra_ | -| hubDeviceId | String | device's parent Hub ID | -| battery | Integer | the current battery level, 0-100 | -| version | String | the current firmware version, e.g. V6.3 | -| lockState | String | jammed, unlock, lock, latchBoltLocked | -| doorState | String | open, close | -| calibrate | Boolean | determines if Lock has been calibrated or not | +| deviceId | String | device ID | +| deviceType | String | device type. _Smart Lock Ultra_ | +| hubDeviceId | String | device's parent Hub ID | +| battery | Integer | the current battery level, 0-100 | +| version | String | the current firmware version, e.g. V6.3 | +| onlineStatus | String | the online status of the device. _online_ or _offline_ | +| lockState | String | jammed, unlocked, locked, latchBoltLocked | +| doorState | String | open, closed | +| calibrate | Boolean | determines if Lock has been calibrated or not | --- @@ -53,6 +54,7 @@ | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | | lockState | String | the state of the device, "LOCKED" stands for the motor is rotated to locking position; "UNLOCKED" stands for the motor is rotated to unlocking position; "JAMMED" stands for the motor is jammed while rotating | +| doorState | String | the state of the door, "OPENED" or "CLOSED" | | battery | Integer | the battery level | | timeOfSample | Long | the time stamp when the event is sent | @@ -61,9 +63,10 @@ "eventType": "changeReport", "eventVersion": "1", "context": { - "deviceType": "Smart Lock Ultra", + "deviceType": "Lock Ultra", "deviceMac": DEVICE_MAC_ADDR, "lockState": "LOCKED", + "doorState": "CLOSED", "battery": 90, "timeOfSample": 123456789 } From 9194ad642411f67f05595a6bf0793d7526d4131b Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 02/24] Lock: add doorState to webhook events --- devices/locks-security/lock.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/devices/locks-security/lock.md b/devices/locks-security/lock.md index 44a1754..fa0ee25 100644 --- a/devices/locks-security/lock.md +++ b/devices/locks-security/lock.md @@ -53,6 +53,7 @@ | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | | lockState | String | the state of the device, "LOCKED" stands for the motor is rotated to locking position; "UNLOCKED" stands for the motor is rotated to unlocking position; "JAMMED" stands for the motor is jammed while rotating | +| doorState | String | the state of the door, e.g. "OPENED" | | battery | Integer | the current battery level, `0-100` | | timeOfSample | Long | the time stamp when the event is sent | @@ -64,6 +65,7 @@ "deviceType": "WoLock", "deviceMac": DEVICE_MAC_ADDR, "lockState": "LOCKED", + "doorState": "OPENED", "battery":100, "timeOfSample": 123456789 } From 700c440143191449f7cd8f27080213c36b6cba8d Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 03/24] Keypad Touch: add battery/version to status, keyName/battery to webhook, fix deleteKey trailing space --- devices/locks-security/keypad-touch.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/devices/locks-security/keypad-touch.md b/devices/locks-security/keypad-touch.md index 92b1952..da5ccdc 100644 --- a/devices/locks-security/keypad-touch.md +++ b/devices/locks-security/keypad-touch.md @@ -30,11 +30,13 @@ ## Device Status -| Key | Value Type | Description | -| ----------- | ---------- | --------------------------- | -| deviceId | String | device ID | -| deviceType | String | device type. _Keypad Touch_ | -| hubDeviceId | String | device's parent Hub ID | +| Key | Value Type | Description | +| ----------- | ---------- | ------------------------------------ | +| deviceId | String | device ID | +| deviceType | String | device type. _Keypad Touch_ | +| hubDeviceId | String | device's parent Hub ID | +| battery | Integer | the current battery level, `0-100` | +| version | String | the current firmware version, e.g. V3.1 | --- @@ -76,7 +78,9 @@ The following table describes the parameter object for `deleteKey`, | deviceMac | String | attributes of the context object. the MAC address of the device | | eventName | String | attributes of the context object. the name of the command being sent | | commandId | String | attributes of the context object. the command id | +| keyName | String | attributes of the context object. the name of the passcode | | result | String | attributes of the context object. the result of the command. _success_, _failed_, or _timeout_. timeout duration is 1 minute | +| battery | Integer | attributes of the context object. the current battery level, `0-100` | | timeOfSample | Long | attributes of the context object. the time stamp when the event is sent | ##### Create a passcode @@ -90,7 +94,9 @@ The following table describes the parameter object for `deleteKey`, "deviceMac": DEVICE_MAC_ADDR, "eventName": "createKey", "commandId": "CMD-1663558451952-01", + "keyName": "passcode name", "result": "success", + "battery": 84, "timeOfSample": 123456789 } } @@ -105,9 +111,11 @@ The following table describes the parameter object for `deleteKey`, "context": { "deviceType": "WoKeypadTouch", "deviceMac": DEVICE_MAC_ADDR, - "eventName": "deleteKey ", + "eventName": "deleteKey", "commandId": "CMD-1663558451952-01", + "keyName": "passcode name", "result": "success", + "battery": 84, "timeOfSample": 123456789 } } From 12b601765829f58d0dc8842efbf7e0f1700c7e36 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 04/24] Video Doorbell: document actual nested webhook event structure --- devices/cameras/video-doorbell.md | 44 ++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/devices/cameras/video-doorbell.md b/devices/cameras/video-doorbell.md index e2ca1bb..2bc3769 100644 --- a/devices/cameras/video-doorbell.md +++ b/devices/cameras/video-doorbell.md @@ -21,7 +21,7 @@ | deviceId | String | device ID | | deviceType | String | device type. _Video Doorbell_ | | hubDeviceId | String | device's parent Hub ID | -| version | String | the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3 | +| version | String | the current firmware version, e.g. V2.02.033 | | battery | Integer | the current battery level | | online | Boolean | the connection status of the device. _true_ or _false_ | @@ -38,17 +38,27 @@ ## Webhook Events -| Key Name | Value Type | Description | -| -------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| eventType | String | the type of events | -| eventVersion | String | the current event version | -| context | Object | the detail info of the event | -| deviceType | String | the type of the device | -| deviceMac | String | the MAC address of the device | -| battery | Integer | the battery level | -| detectionState | String | the motion state of the device, "DETECTED" stands for motion is detected; "NOT_DETECTED" stands for motion has not been detected for some time | -| timeOfSample | Long | the time stamp when the event is sent | -| press | Boolean | the Doorbell button was pressed | +| Key Name | Value Type | Description | +| ------------ | ---------- | -------------------------------------------------------------------------------------------------------- | +| eventType | String | the type of events | +| eventVersion | String | the current event version | +| context | Object | the detail info of the event | +| deviceType | String | the type of the device | +| deviceMac | String | the MAC address of the device | +| battery | Integer | the battery level | +| humanEvent | Object | sent when a human is detected. contains `detectionType`, `eventTime`, `id`, and `img` | +| ringEvent | Object | sent when the doorbell button is pressed. contains `detectionType`, `eventTime`, `id`, and `img` | +| motionEvent | Object | sent when motion is detected. contains `detectionType`, `eventTime`, `id`, and `img` | +| timeOfSample | Long | the time stamp when the event is sent | + +Each event object (`humanEvent`, `ringEvent`, or `motionEvent`) has the following attributes. Only one event object is included per webhook message. + +| Key | Value Type | Description | +| ------------- | ---------- | -------------------------------------------------------------------- | +| detectionType | String | the type of the detection, e.g. "human" or "motion" | +| eventTime | Long | the time stamp (in seconds) when the event occurred | +| id | String | the unique ID of the event | +| img | String | a pre-signed URL of the snapshot image taken when the event occurred | ```js { @@ -57,9 +67,13 @@ "context": { "deviceType": "Video Doorbell", "deviceMac": DEVICE_MAC_ADDR, - "battery": 80, - "detectionState": "DETECTED", - "press": true, + "battery": 100, + "ringEvent": { + "detectionType": "human", + "eventTime": 1784716196, + "id": "a1fbf2a3-f6ca-4b81-9c1a-021a1f17c041", + "img": "https://..." + }, "timeOfSample": 123456789 } } From ba27ca3ae27d5401a017d24ad97e8db0a620fb52 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 05/24] Presence Sensor: fix detected key casing and webhook example deviceType --- devices/sensors/presence-sensor.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/devices/sensors/presence-sensor.md b/devices/sensors/presence-sensor.md index eed41b6..b42e632 100644 --- a/devices/sensors/presence-sensor.md +++ b/devices/sensors/presence-sensor.md @@ -24,7 +24,7 @@ | battery | Integer | Four-segment battery level division,`<10%, shown as 10;10%~20%, shown as 20;20%~60%, shown as 60;≥60%, shown as 100` | | version | String | the current firmware version, e.g. V4.2 | | lightLevel | Integer | the level of illuminance of the ambience light, 1~20 | -| Detected | Boolean | determines if human is detected | +| detected | Boolean | determines if human presence is detected | --- @@ -37,7 +37,7 @@ | context | Object | the detail info of the event | | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | -| detectionState | String | the motion state of the device, "DETECTED" stands for motion is detected; "NOT_DETECTED" stands for motion has not been detected for some time | +| detectionState | String | the presence state of the device, "DETECTED" stands for human presence is detected; "NOT_DETECTED" stands for human presence has not been detected for some time | | battery | Integer | the current battery level, `0-100` | | lightLevel | Integer | the level of illuminance of the ambience light, 1~20 | | timeOfSample | Long | the time stamp when the event is sent | @@ -47,7 +47,7 @@ "eventType": "changeReport", "eventVersion": "1", "context": { - "deviceType": "WoContact", + "deviceType": "Presence Sensor", "deviceMac": DEVICE_MAC_ADDR, "detectionState": "NOT_DETECTED", "battery":100, From c40cbf7279e135612fd157ca4daf4d756ec86f13 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 06/24] Motion Sensor: add brightness to webhook events --- devices/sensors/motion-sensor.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/devices/sensors/motion-sensor.md b/devices/sensors/motion-sensor.md index a5f289f..4b7ac23 100644 --- a/devices/sensors/motion-sensor.md +++ b/devices/sensors/motion-sensor.md @@ -38,6 +38,7 @@ | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | | detectionState | String | the motion state of the device, "DETECTED" stands for motion is detected; "NOT_DETECTED" stands for motion has not been detected for some time | +| brightness | String | the ambient brightness picked up by the sensor. _bright_ or _dim_ | | battery | Integer | the current battery level, `0-100` | | timeOfSample | Long | the time stamp when the event is sent | @@ -49,6 +50,7 @@ "deviceType": "WoPresence", "deviceMac": DEVICE_MAC_ADDR, "detectionState": "NOT_DETECTED", + "brightness": "dim", "battery":100, "timeOfSample": 123456789 } From b177e815d176e48d334618ec5bcf21083919264d Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 07/24] Ceiling Light: add online to webhook events --- devices/lighting/ceiling-light.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/devices/lighting/ceiling-light.md b/devices/lighting/ceiling-light.md index eb88a11..05a25a5 100644 --- a/devices/lighting/ceiling-light.md +++ b/devices/lighting/ceiling-light.md @@ -51,6 +51,7 @@ | deviceType | String | attributes of the context object. the type of the device | | deviceMac | String | attributes of the context object. the MAC address of the device | | powerState | String | attributes of the context object. ON/OFF state | +| online | Boolean | attributes of the context object. determines if the device is connected to the internet | | brightness | Integer | attributes of the context object. the brightness value, range from 1 to 100 | | colorTemperature | Integer | attributes of the context object. the color temperature value, range from 2700 to 6500 | | timeOfSample | Long | attributes of the context object. the time stamp when the event is sent | @@ -63,6 +64,7 @@ "deviceType": "WoCeiling", "deviceMac": DEVICE_MAC_ADDR, "powerState": "ON", + "online": true, "brightness": 10, "colorTemperature": 3500, "timeOfSample": 123456789 From aa9ccee5e58313fec0e95e5aa3f543fef3b913c3 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 08/24] Color Bulb: add online to webhook events --- devices/lighting/color-bulb.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/devices/lighting/color-bulb.md b/devices/lighting/color-bulb.md index 5dc92de..f41ef67 100644 --- a/devices/lighting/color-bulb.md +++ b/devices/lighting/color-bulb.md @@ -52,6 +52,7 @@ | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | | powerState | String | the current power state of the device, "ON" or "OFF" | +| online | Boolean | determines if the device is connected to the internet | | brightness | Integer | the brightness value, range from 1 to 100 | | color | String | the color value, in the format of RGB value, "255:255:255" | | colorTemperature | Integer | the color temperature value, range from 2700 to 6500 | @@ -65,6 +66,7 @@ "deviceType": "WoBulb", "deviceMac": DEVICE_MAC_ADDR, "powerState": "ON", + "online": true, "brightness": 10, "color":"255:245:235", "colorTemperature":3500, From 6453fb1300b2f1db00a639a4fb51d4def363dd19 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:38 +0900 Subject: [PATCH 09/24] Strip Light: add online to webhook events --- devices/lighting/strip-light.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/devices/lighting/strip-light.md b/devices/lighting/strip-light.md index 10beeec..9ff6f9f 100644 --- a/devices/lighting/strip-light.md +++ b/devices/lighting/strip-light.md @@ -51,6 +51,7 @@ | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | | powerState | String | the current power state of the device, "ON" or "OFF" | +| online | Boolean | determines if the device is connected to the internet | | brightness | Integer | the brightness value, range from 1 to 100 | | color | String | the color value, in the format of RGB value, "255:255:255" | | timeOfSample | Long | the time stamp when the event is sent | @@ -63,6 +64,7 @@ "deviceType": "WoStrip", "deviceMac": DEVICE_MAC_ADDR, "powerState": "ON", + "online": true, "brightness": 10, "color": "255:245:235", "timeOfSample": 123456789 From 0b0ca549584083cdfa4c6df877cf4b2fc4c3d778 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 10/24] Strip Light 3: add onlineStatus/online, fix brightness range --- devices/lighting/strip-light-3.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/devices/lighting/strip-light-3.md b/devices/lighting/strip-light-3.md index 2e87055..3d40703 100644 --- a/devices/lighting/strip-light-3.md +++ b/devices/lighting/strip-light-3.md @@ -23,7 +23,8 @@ | hubDeviceId | String | device's parent Hub ID | | version | String | the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3 | | power | String | ON/OFF state | -| brightness | Integer | the brightness value, range from 1 to 100 | +| onlineStatus | String | the connection status of the device. _online_ or _offline_ | +| brightness | Integer | the brightness value, range from 0 to 100 | | color | String | the color value, RGB "255:255:255" | | colorTemperature | Integer | the color temperature value, range from 2700 to 6500 | @@ -52,6 +53,7 @@ | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | | powerState | String | ON/OFF state | +| online | Boolean | determines if the device is connected to the internet | | brightness | Integer | attributes of the context object. the brightness value, range from 1 to 100 | | colorTemperature | Integer | attributes of the context object. the color temperature value, range from 2700 to 6500 | | color | String | the color value, in the format of RGB value, "255:255:255" | @@ -65,6 +67,7 @@ "deviceType": "Strip Light 3", "deviceMac": DEVICE_MAC_ADDR, "powerState": "ON",//"ON"or"OFF" + "online": true, "brightness": 10, "color": "255:255:0", "colorTemperature": 3500, From e4ad1c82222081ff193c9927581b738e022fb00a Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 11/24] RGBIC Neon Wire Rope Light: add colorTemperature/online, fix webhook example deviceType --- devices/lighting/rgbic-neon-wire-rope-light.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/devices/lighting/rgbic-neon-wire-rope-light.md b/devices/lighting/rgbic-neon-wire-rope-light.md index d372ff7..d93f013 100644 --- a/devices/lighting/rgbic-neon-wire-rope-light.md +++ b/devices/lighting/rgbic-neon-wire-rope-light.md @@ -24,8 +24,9 @@ | version | String | the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3 | | power | String | ON/OFF state | | onlineStatus | String | the connection status of the device. _online_ or _offline_ | -| brightness | Integer | the brightness value, range from 1 to 100 | +| brightness | Integer | the brightness value, range from 0 to 100 | | color | String | the color value, RGB "255:255:255" | +| colorTemperature | Integer | the color temperature value | --- @@ -51,8 +52,10 @@ | deviceType | String | attributes of the context object. the type of the device | | deviceMac | String | attributes of the context object. the MAC address of the device | | powerState | String | attributes of the context object. ON/OFF state | +| online | Boolean | attributes of the context object. determines if the device is connected to the internet | | brightness | Integer | attributes of the context object. the brightness value, range from 1 to 100 | | color | String | the color value, in the format of RGB value, "255:255:255" | +| colorTemperature | Integer | the color temperature value | | timeOfSample | Long | attributes of the context object. the time stamp when the event is sent | ```js @@ -60,11 +63,13 @@ "eventType": "changeReport", "eventVersion": "1", "context": { - "deviceType": "RGBICWW Strip Light", + "deviceType": "RGBIC Wire Neon Rope Light", "deviceMac": DEVICE_MAC_ADDR, "powerState": "ON",//"ON"or"OFF" + "online": true, "brightness": 10, "color": "255:255:0", + "colorTemperature": 4410, "timeOfSample": 123456789 } } From 11097708bbaf533be62d2a6f992b9d968c5ca16b Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 12/24] Curtain: fix slidePosition value type to Integer --- devices/curtains-blinds/curtain.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/devices/curtains-blinds/curtain.md b/devices/curtains-blinds/curtain.md index 8f33f3d..918972e 100644 --- a/devices/curtains-blinds/curtain.md +++ b/devices/curtains-blinds/curtain.md @@ -31,7 +31,7 @@ | moving | Boolean | determines if a Curtain is moving or not | | battery | Integer | Four-segment battery level division,`<10%, shown as 5;10%~20%, shown as 15;20%~60%, shown as 40;≥60%, shown as 80` | | version | String | the current firmware version, e.g. V4.2 | -| slidePosition | String | the percentage of the distance between the calibrated open position and closed position that Curtain has traversed | +| slidePosition | Integer | the percentage of the distance between the calibrated open position and closed position that Curtain has traversed | --- From 7f1529da466048e9487facea50d93e76b66f262b Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 13/24] Plug Mini (JP): add power to status and online to webhook, fix hubDeviceId description --- devices/plugs-switches/plug-mini-jp.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/devices/plugs-switches/plug-mini-jp.md b/devices/plugs-switches/plug-mini-jp.md index 6062268..a64d524 100644 --- a/devices/plugs-switches/plug-mini-jp.md +++ b/devices/plugs-switches/plug-mini-jp.md @@ -20,7 +20,8 @@ | ---------------- | ---------- | -------------------------------------------------------------------------------------------------------- | | deviceId | String | device ID | | deviceType | String | device type. _Plug Mini (JP)_ | -| hubDeviceId | String | device's parent Hub ID. _000000000000_ when the device itself is a Hub or it is connected through Wi-Fi. | +| hubDeviceId | String | device's parent Hub ID, equivalent to device ID when the device is connected through Wi-Fi | +| power | String | ON/OFF state | | voltage | Float | the voltage of the device, measured in Volt | | version | String | the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3 | | weight | Float | the power consumed in a day, measured in Watts | @@ -49,6 +50,7 @@ | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | | powerState | String | the current power state of the device, "ON" or "OFF" | +| online | Boolean | determines if the device is connected to the internet | | timeOfSample | Long | the time stamp when the event is sent | ```js @@ -59,6 +61,7 @@ "deviceType": "WoPlugJP", "deviceMac": DEVICE_MAC_ADDR, "powerState": "ON", + "online": true, "timeOfSample": 123456789 } } From d2cb0d7d590278cbecc5fc8bdddc712c1078bbcc Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 14/24] Relay Switch 1: document power-related status fields returned as 0 --- devices/plugs-switches/relay-switch-1.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/devices/plugs-switches/relay-switch-1.md b/devices/plugs-switches/relay-switch-1.md index ad11ee9..9ff880b 100644 --- a/devices/plugs-switches/relay-switch-1.md +++ b/devices/plugs-switches/relay-switch-1.md @@ -18,11 +18,15 @@ | Key | Value Type | Description | | ------------ | ---------- | --------------------------------------------------------- | -| deviceId | String | device ID | -| deviceType | String | device type. _Relay Switch 1_ | -| switchStatus | Integer | the current switch state. `0`, off; `1`, on | -| version | String | the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3 | -| hubDeviceId | String | Hub ID, equivalent to device ID | +| deviceId | String | device ID | +| deviceType | String | device type. _Relay Switch 1_ | +| switchStatus | Integer | the current switch state. `0`, off; `1`, on | +| version | String | the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3 | +| hubDeviceId | String | Hub ID, equivalent to device ID | +| voltage | Float | always returns `0` since the device has no power monitoring capability | +| power | Float | always returns `0` since the device has no power monitoring capability | +| usedElectricity | Integer | always returns `0` since the device has no power monitoring capability | +| electricCurrent | Integer | always returns `0` since the device has no power monitoring capability | --- From e401fb9ecbc6aededb7c356a08e54683c6bbd165 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 15/24] Relay Switch 2PM: fix webhook switch status key names, add timeOfSample --- devices/plugs-switches/relay-switch-2pm.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/devices/plugs-switches/relay-switch-2pm.md b/devices/plugs-switches/relay-switch-2pm.md index d5e0120..caa2c26 100644 --- a/devices/plugs-switches/relay-switch-2pm.md +++ b/devices/plugs-switches/relay-switch-2pm.md @@ -25,7 +25,7 @@ | switch2Status | Integer | the current switch2 state. `0`, off; `1`, on | | switch1Voltage | Float | the switch1 current voltage, measured in Volt | | switch2Voltage | Float | the switch2 current voltage, measured in Volt | -| version | String | the current BLE and Wi-Fi firmware version, e.g. V3.1-6.3 | +| version | String | the current firmware version, e.g. V2.1 | | switch1Power | Float | the switch1 current power, measured in Watts | | switch2Power | Float | the switch2 current power, measured in Watts | | switch1UsedElectricity | Integer | switch1 daily power consumption, measured in watt-minutes | @@ -61,11 +61,13 @@ | deviceType | String | the type of the device | | deviceMac | String | the MAC address of the device | | online | Boolean | determines if the device is connected to the internet or disconnected | -| switchStatus | Integer | the switch state of the device. `1`, on; `0`, off | +| switch1Status | Integer | the switch1 state of the device. `1`, on; `0`, off. only included when the state of switch1 has changed | +| switch2Status | Integer | the switch2 state of the device. `1`, on; `0`, off. only included when the state of switch2 has changed | | overload | Boolean | determines if the device is power overloaded or not | | calibrate | Boolean | determines if the open position and the close position of a device have been properly calibrated or not | | position | Integer | determine the percentage of the device that is open or closed | | isStuck | Boolean | determine if the device is stuck | +| timeOfSample | Long | the time stamp when the event is sent | ```js { @@ -82,7 +84,8 @@ "switch2Overload": true, "calibrate": true, "position": 0, - "isStuck": true + "isStuck": true, + "timeOfSample": 123456789 } } ``` From 85b349b6428e8d3d9bde01bcc0bb80c6da0fc6f9 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 16/24] Circulator Fan: add chargingStatus/hubDeviceId, fix nightStatus type --- devices/climate-control/circulator-fan.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/devices/climate-control/circulator-fan.md b/devices/climate-control/circulator-fan.md index 6250fcc..138efac 100644 --- a/devices/climate-control/circulator-fan.md +++ b/devices/climate-control/circulator-fan.md @@ -27,7 +27,9 @@ | nightStatus | String | set nightlight status. turn off: _off_; mode 1: _1_; mode 2: _2_ | | oscillation | String | set horizontal oscillation. turn on: _on_; turn off: _off_ | | verticalOscillation | String | set vertical oscillation. turn on: _on_; turn off: _off_ | +| chargingStatus | String | battery charge status. _charging_ or _uncharged_ | | fanSpeed | Integer | fan speed. 1~100 | +| hubDeviceId | String | device's parent Hub ID | --- @@ -56,9 +58,10 @@ | mode | String | fan mode. direct mode: _direct_; natural mode: "natural"; sleep mode: "sleep"; ultra quiet mode: "baby" | | version | String | the current firmware version, e.g. V4.2 | | powerState | String | ON/OFF state | -| nightStatus | Integer | set nightlight status. turn off: _off_; mode 1: _1_; mode 2: _2_ | +| nightStatus | String | set nightlight status. turn off: _off_; mode 1: _1_; mode 2: _2_ | | oscillation | String | set horizontal oscillation. turn on: _on_; turn off: _off_ | | verticalOscillation | String | set vertical oscillation. turn on: _on_; turn off: _off_ | +| chargingStatus | String | battery charge status. _charging_ or _uncharged_ | | fanSpeed | Integer | fan speed. 1~100 | | timeOfSample | Long | the time stamp when the event is sent | @@ -75,6 +78,7 @@ "nightStatus": "off", "oscillation": "on", "verticalOscillation": "on", + "chargingStatus": "uncharged", "fanSpeed": 3, "timeOfSample": 123456789 } From 6f78524e762a397b633bc47ae7941f0a871ad56c Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 17/24] Mini Robot Vacuum K10+ Pro: fix full-width colon in webhook example --- devices/robot-vacuum/mini-robot-vacuum-k10-pro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/devices/robot-vacuum/mini-robot-vacuum-k10-pro.md b/devices/robot-vacuum/mini-robot-vacuum-k10-pro.md index e0a2188..b590dba 100644 --- a/devices/robot-vacuum/mini-robot-vacuum-k10-pro.md +++ b/devices/robot-vacuum/mini-robot-vacuum-k10-pro.md @@ -60,7 +60,7 @@ "context": { "deviceType": "WoSweeperMiniPro", "deviceMac": DEVICE_MAC_ADDR, - "workingStatus"："StandBy", + "workingStatus": "StandBy", "onlineStatus": "online", "battery": 100, "timeOfSample": 123456789 From 95f73bb97959a867a6b37b3780c14edbd9dc3946 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 18/24] Pan/Tilt Cam Plus 3K: document device status and webhook events --- README.md | 2 +- devices/cameras/pantilt-cam-plus-3k.md | 53 ++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 37d31f3..0dddea3 100644 --- a/README.md +++ b/README.md @@ -1683,7 +1683,7 @@ Webhook events are sent as POST requests in JSON format. The structure varies by | [Pan/Tilt Cam](devices/cameras/pantilt-cam.md) | ✓ | - | - | ✓ | | [Pan/Tilt Cam 2K](devices/cameras/pantilt-cam-2k.md) | ✓ | - | - | - | | [Pan/Tilt Cam Plus 2K](devices/cameras/pantilt-cam-plus-2k.md) | ✓ | - | - | - | -| [Pan/Tilt Cam Plus 3K](devices/cameras/pantilt-cam-plus-3k.md) | ✓ | - | - | - | +| [Pan/Tilt Cam Plus 3K](devices/cameras/pantilt-cam-plus-3k.md) | ✓ | ✓ | - | ✓ | ### Others diff --git a/devices/cameras/pantilt-cam-plus-3k.md b/devices/cameras/pantilt-cam-plus-3k.md index 52be7a7..5ca1b8d 100644 --- a/devices/cameras/pantilt-cam-plus-3k.md +++ b/devices/cameras/pantilt-cam-plus-3k.md @@ -13,3 +13,56 @@ | hubDeviceId | String | device's parent Hub ID. _000000000000_ when the device itself is a Hub or it is connected through Wi-Fi. | --- + +## Device Status + +| Key | Value Type | Description | +| ----------- | ---------- | ------------------------------------ | +| deviceId | String | device ID | +| deviceType | String | device type. _Pan/Tilt Cam Plus 3K_ | +| hubDeviceId | String | device's parent Hub ID | +| latestImage | Object | the latest snapshot image info. an empty object when no snapshot is available | + +--- + +## Webhook Events + +Note: the `deviceType` in webhook messages is _WoCamKvs5mp_, which is different from the one in the device list and device status. + +| Key Name | Value Type | Description | +| ------------ | ---------- | ------------------------------------------------------------------------ | +| eventType | String | the type of events | +| eventVersion | String | the current event version | +| context | Object | the detail info of the event | +| deviceType | String | the type of the device. _WoCamKvs5mp_ | +| deviceMac | String | the MAC address of the device | +| motionEvent | Object | sent when motion is detected. contains `detectionType`, `img`, and `startTimestamp` | +| humanEvent | Object | sent when a human is detected. contains `detectionType`, `img`, and `startTimestamp` | +| timeOfSample | Long | the time stamp when the event is sent | + +Each event object (`motionEvent` or `humanEvent`) has the following attributes. Only one event object is included per webhook message. + +| Key | Value Type | Description | +| -------------- | ---------- | -------------------------------------------------------------------- | +| detectionType | String | the type of the detection, e.g. "motion" or "human" | +| img | String | a pre-signed URL of the snapshot image taken when the event occurred | +| startTimestamp | Long | the time stamp (in seconds) when the event started | + +```js +{ + "eventType": "changeReport", + "eventVersion": "1", + "context": { + "deviceType": "WoCamKvs5mp", + "deviceMac": DEVICE_MAC_ADDR, + "motionEvent": { + "detectionType": "motion", + "img": "https://...", + "startTimestamp": 1784708706 + }, + "timeOfSample": 123456789 + } +} +``` + +--- From 6847912099cfe3b1c622de53ccf24fa37b375aa5 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 19/24] Add Outdoor Pan/Tilt Cam 3K documentation --- README.md | 3 + devices/cameras/outdoor-pantilt-cam-3k.md | 68 +++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 devices/cameras/outdoor-pantilt-cam-3k.md diff --git a/README.md b/README.md index 0dddea3..bb1b3d9 100644 --- a/README.md +++ b/README.md @@ -618,6 +618,7 @@ The following table provides definitions to the terms to be frequently mentioned | Battery Circulator Fan 2 Pro | Short for SwitchBot Battery Circulator Fan 2 Pro | W9502500, W9502501, W9502502, and W9502503 | | | Kata Friends | Short for SwitchBot Kata Friends | W7912300 | | | AI MindClip | Short for SwitchBot AI MindClip | W6902000 and W6902003 | | +| Outdoor Pan/Tilt Cam 3K | Short for SwitchBot Outdoor Pan/Tilt Cam 3K | | | ### `Legacy` Cloud Services @@ -784,6 +785,7 @@ Physical devices refer to the following SwitchBot products, - `new` [Battery Circulator Fan 2 Pro](devices/climate-control/battery-circulator-fan-2-pro.md) - `new` [Kata Friends](devices/others/kata-friends.md) - `new` [AI MindClip](devices/others/ai-mindclip.md) +- `new` [Outdoor Pan/Tilt Cam 3K](devices/cameras/outdoor-pantilt-cam-3k.md) Virtual infrared remote devices refer to virtual devices that are used to simulate infrared signals of a home appliance remote control. A SwitchBot Hub Plus, Hub Mini, Hub 2, Hub 3 or Ceiling Light is required in order to be able to create these virtual devices within the app. The types of appliances supported include, @@ -1684,6 +1686,7 @@ Webhook events are sent as POST requests in JSON format. The structure varies by | [Pan/Tilt Cam 2K](devices/cameras/pantilt-cam-2k.md) | ✓ | - | - | - | | [Pan/Tilt Cam Plus 2K](devices/cameras/pantilt-cam-plus-2k.md) | ✓ | - | - | - | | [Pan/Tilt Cam Plus 3K](devices/cameras/pantilt-cam-plus-3k.md) | ✓ | ✓ | - | ✓ | +| [Outdoor Pan/Tilt Cam 3K](devices/cameras/outdoor-pantilt-cam-3k.md) | ✓ | ✓ | - | ✓ | ### Others diff --git a/devices/cameras/outdoor-pantilt-cam-3k.md b/devices/cameras/outdoor-pantilt-cam-3k.md new file mode 100644 index 0000000..dcf32a8 --- /dev/null +++ b/devices/cameras/outdoor-pantilt-cam-3k.md @@ -0,0 +1,68 @@ +# Outdoor Pan/Tilt Cam 3K + +SwitchBot Outdoor Pan/Tilt Cam 3K. Note: the `deviceType` string used by the API is the abbreviated form _Outdoor PTC 3K_. + +--- + +## Device List Information + +| Key | Value Type | Description | +| ------------------ | ---------- | -------------------------------------------------------------------------------------------------------- | +| deviceId | String | device ID | +| deviceName | String | device name | +| deviceType | String | device type. _Outdoor PTC 3K_. Note: this key has been observed to be missing in actual device list responses. | +| enableCloudService | Boolean | determines if Cloud Service is enabled or not for the current device | +| hubDeviceId | String | device's parent Hub ID | + +--- + +## Device Status + +| Key | Value Type | Description | +| ----------- | ---------- | ------------------------------------ | +| deviceId | String | device ID | +| deviceType | String | device type. _Outdoor PTC 3K_ | +| hubDeviceId | String | device's parent Hub ID | +| latestImage | Object | the latest snapshot image info. an empty object when no snapshot is available | + +--- + +## Webhook Events + +Note: the `deviceType` in webhook messages is _W1156000_, which is different from the one in the device status. + +| Key Name | Value Type | Description | +| ------------ | ---------- | ------------------------------------------------------------------------ | +| eventType | String | the type of events | +| eventVersion | String | the current event version | +| context | Object | the detail info of the event | +| deviceType | String | the type of the device. _W1156000_ | +| deviceMac | String | the MAC address of the device | +| humanEvent | Object | sent when a human is detected. contains `detectionType`, `img`, and `startTimestamp` | +| motionEvent | Object | sent when motion is detected. contains `detectionType`, `img`, and `startTimestamp` | +| timeOfSample | Long | the time stamp when the event is sent | + +Each event object (`humanEvent` or `motionEvent`) has the following attributes. Only one event object is included per webhook message. + +| Key | Value Type | Description | +| -------------- | ---------- | -------------------------------------------------------------------- | +| detectionType | String | the type of the detection, e.g. "human" or "motion" | +| img | String | a pre-signed URL of the snapshot image taken when the event occurred | +| startTimestamp | Long | the time stamp (in seconds) when the event started | + +```js +{ + "eventType": "changeReport", + "eventVersion": "1", + "context": { + "deviceType": "W1156000", + "deviceMac": DEVICE_MAC_ADDR, + "humanEvent": { + "detectionType": "human", + "img": "https://...", + "startTimestamp": 1784815490 + }, + "timeOfSample": 123456789 + } +} +``` From 0773284bc00f0f5796cb32ba47adf488dd69f276 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 20/24] Add Universal Remote documentation --- README.md | 3 +++ devices/others/universal-remote.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 devices/others/universal-remote.md diff --git a/README.md b/README.md index bb1b3d9..7316804 100644 --- a/README.md +++ b/README.md @@ -619,6 +619,7 @@ The following table provides definitions to the terms to be frequently mentioned | Kata Friends | Short for SwitchBot Kata Friends | W7912300 | | | AI MindClip | Short for SwitchBot AI MindClip | W6902000 and W6902003 | | | Outdoor Pan/Tilt Cam 3K | Short for SwitchBot Outdoor Pan/Tilt Cam 3K | | | +| Universal Remote | Short for SwitchBot Universal Remote | | | ### `Legacy` Cloud Services @@ -786,6 +787,7 @@ Physical devices refer to the following SwitchBot products, - `new` [Kata Friends](devices/others/kata-friends.md) - `new` [AI MindClip](devices/others/ai-mindclip.md) - `new` [Outdoor Pan/Tilt Cam 3K](devices/cameras/outdoor-pantilt-cam-3k.md) +- `new` [Universal Remote](devices/others/universal-remote.md) Virtual infrared remote devices refer to virtual devices that are used to simulate infrared signals of a home appliance remote control. A SwitchBot Hub Plus, Hub Mini, Hub 2, Hub 3 or Ceiling Light is required in order to be able to create these virtual devices within the app. The types of appliances supported include, @@ -1699,6 +1701,7 @@ Webhook events are sent as POST requests in JSON format. The structure varies by | [Virtual infrared remote devices](devices/others/virtual-infrared-remote-devices.md) | ✓ | - | ✓ | - | | [Kata Friends](devices/others/kata-friends.md) | ✓ | ✓ | ✓ | ✓ | | [AI MindClip](devices/others/ai-mindclip.md) | ✓ | ✓ | - | ✓ | +| [Universal Remote](devices/others/universal-remote.md) | ✓ | ✓ | - | - | ---- diff --git a/devices/others/universal-remote.md b/devices/others/universal-remote.md new file mode 100644 index 0000000..e5f5cf3 --- /dev/null +++ b/devices/others/universal-remote.md @@ -0,0 +1,28 @@ +# Universal Remote + +SwitchBot Universal Remote (screen-equipped learning remote). Note: the `deviceType` string is all lowercase, _remote with screen_. + +--- + +## Device List Information + +| Key | Value Type | Description | +| ------------------ | ---------- | -------------------------------------------------------------------------------------------------------- | +| deviceId | String | device ID | +| deviceName | String | device name | +| deviceType | String | device type. _remote with screen_ | +| enableCloudService | Boolean | determines if Cloud Service is enabled or not for the current device | +| hubDeviceId | String | device's parent Hub ID. _000000000000_ when the device itself is a Hub or it is connected through Wi-Fi. | + +--- + +## Device Status + +| Key | Value Type | Description | +| -------------- | ---------- | ------------------------------------------------- | +| deviceId | String | device ID | +| deviceType | String | device type. _remote with screen_ | +| hubDeviceId | String | device's parent Hub ID | +| version | String | the current firmware version, e.g. V4.8 | +| battery | Integer | the current battery level, `0-100` | +| chargingStatus | String | battery charge status. _charging_ or _uncharged_ | From ed3ccd0f407224f005e615c2c39d908d7ae07e53 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:39 +0900 Subject: [PATCH 21/24] Add Wallet Finder Card documentation --- README.md | 3 +++ devices/others/wallet-finder-card.md | 27 +++++++++++++++++++++++++++ 2 files changed, 30 insertions(+) create mode 100644 devices/others/wallet-finder-card.md diff --git a/README.md b/README.md index 7316804..e7b8eb1 100644 --- a/README.md +++ b/README.md @@ -620,6 +620,7 @@ The following table provides definitions to the terms to be frequently mentioned | AI MindClip | Short for SwitchBot AI MindClip | W6902000 and W6902003 | | | Outdoor Pan/Tilt Cam 3K | Short for SwitchBot Outdoor Pan/Tilt Cam 3K | | | | Universal Remote | Short for SwitchBot Universal Remote | | | +| Wallet Finder Card | Short for SwitchBot Wallet Finder Card | | | ### `Legacy` Cloud Services @@ -788,6 +789,7 @@ Physical devices refer to the following SwitchBot products, - `new` [AI MindClip](devices/others/ai-mindclip.md) - `new` [Outdoor Pan/Tilt Cam 3K](devices/cameras/outdoor-pantilt-cam-3k.md) - `new` [Universal Remote](devices/others/universal-remote.md) +- `new` [Wallet Finder Card](devices/others/wallet-finder-card.md) Virtual infrared remote devices refer to virtual devices that are used to simulate infrared signals of a home appliance remote control. A SwitchBot Hub Plus, Hub Mini, Hub 2, Hub 3 or Ceiling Light is required in order to be able to create these virtual devices within the app. The types of appliances supported include, @@ -1702,6 +1704,7 @@ Webhook events are sent as POST requests in JSON format. The structure varies by | [Kata Friends](devices/others/kata-friends.md) | ✓ | ✓ | ✓ | ✓ | | [AI MindClip](devices/others/ai-mindclip.md) | ✓ | ✓ | - | ✓ | | [Universal Remote](devices/others/universal-remote.md) | ✓ | ✓ | - | - | +| [Wallet Finder Card](devices/others/wallet-finder-card.md) | ✓ | - | - | - | ---- diff --git a/devices/others/wallet-finder-card.md b/devices/others/wallet-finder-card.md new file mode 100644 index 0000000..87bba03 --- /dev/null +++ b/devices/others/wallet-finder-card.md @@ -0,0 +1,27 @@ +# Wallet Finder Card + +--- + +## Device List Information + +| Key | Value Type | Description | +| ------------------ | ---------- | -------------------------------------------------------------------------------------------------------- | +| deviceId | String | device ID | +| deviceName | String | device name | +| deviceType | String | device type. _Wallet Finder Card_ | +| enableCloudService | Boolean | determines if Cloud Service is enabled or not for the current device | +| hubDeviceId | String | device's parent Hub ID. _000000000000_ when the device itself is a Hub or it is connected through Wi-Fi. | + +--- + +## Device Status + +The get device status endpoint responds with `statusCode` 100 and an empty `body` object for this device. + +```js +{ + "statusCode": 100, + "body": {}, + "message": "success" +} +``` From 95c4368d586757c1c934d7eb967b11f0c9104ebf Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Fri, 24 Jul 2026 00:24:40 +0900 Subject: [PATCH 22/24] Add Video Doorbell Add-on Monitor documentation --- README.md | 3 ++ .../cameras/video-doorbell-add-on-monitor.md | 39 +++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 devices/cameras/video-doorbell-add-on-monitor.md diff --git a/README.md b/README.md index e7b8eb1..463c7fa 100644 --- a/README.md +++ b/README.md @@ -621,6 +621,7 @@ The following table provides definitions to the terms to be frequently mentioned | Outdoor Pan/Tilt Cam 3K | Short for SwitchBot Outdoor Pan/Tilt Cam 3K | | | | Universal Remote | Short for SwitchBot Universal Remote | | | | Wallet Finder Card | Short for SwitchBot Wallet Finder Card | | | +| Video Doorbell Add-on Monitor | Short for SwitchBot Video Doorbell Add-on Monitor | | | ### `Legacy` Cloud Services @@ -790,6 +791,7 @@ Physical devices refer to the following SwitchBot products, - `new` [Outdoor Pan/Tilt Cam 3K](devices/cameras/outdoor-pantilt-cam-3k.md) - `new` [Universal Remote](devices/others/universal-remote.md) - `new` [Wallet Finder Card](devices/others/wallet-finder-card.md) +- `new` [Video Doorbell Add-on Monitor](devices/cameras/video-doorbell-add-on-monitor.md) Virtual infrared remote devices refer to virtual devices that are used to simulate infrared signals of a home appliance remote control. A SwitchBot Hub Plus, Hub Mini, Hub 2, Hub 3 or Ceiling Light is required in order to be able to create these virtual devices within the app. The types of appliances supported include, @@ -1691,6 +1693,7 @@ Webhook events are sent as POST requests in JSON format. The structure varies by | [Pan/Tilt Cam Plus 2K](devices/cameras/pantilt-cam-plus-2k.md) | ✓ | - | - | - | | [Pan/Tilt Cam Plus 3K](devices/cameras/pantilt-cam-plus-3k.md) | ✓ | ✓ | - | ✓ | | [Outdoor Pan/Tilt Cam 3K](devices/cameras/outdoor-pantilt-cam-3k.md) | ✓ | ✓ | - | ✓ | +| [Video Doorbell Add-on Monitor](devices/cameras/video-doorbell-add-on-monitor.md) | ✓ | - | - | - | ### Others diff --git a/devices/cameras/video-doorbell-add-on-monitor.md b/devices/cameras/video-doorbell-add-on-monitor.md new file mode 100644 index 0000000..6f6d39b --- /dev/null +++ b/devices/cameras/video-doorbell-add-on-monitor.md @@ -0,0 +1,39 @@ +# Video Doorbell Add-on Monitor + +[SwitchBot Video Doorbell Add-on Monitor](https://www.switch-bot.com/products/switchbot-smart-video-doorbell-add-on-monitor). Appears in the device list as a separate entry from the [Video Doorbell](video-doorbell.md) it is paired with. + +--- + +## Device List Information + +Note: no `deviceType` key has been observed in the device list entry for this device. + +| Key | Value Type | Description | +| ------------------ | ---------- | -------------------------------------------------------------------- | +| deviceId | String | device ID | +| deviceName | String | device name | +| enableCloudService | Boolean | determines if Cloud Service is enabled or not for the current device | +| hubDeviceId | String | device's parent Hub ID | + +```js +{ + "deviceId": "FFFFFFFFFFFF", + "deviceName": "Add-on Monitor 40", + "enableCloudService": false, + "hubDeviceId": "000000000000" +} +``` + +--- + +## Device Status + +The get device status endpoint responds with `statusCode` 100 and an empty `body` object for this device. + +```js +{ + "statusCode": 100, + "body": {}, + "message": "success" +} +``` From bbad36d8b5bb9b1e8593a814f7be1dd56f76aed6 Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Wed, 16 Sep 2026 18:35:43 +0900 Subject: [PATCH 23/24] Pan/Tilt Cam Plus 3K: document latestImage structure (imageUrl/expireAt) --- devices/cameras/pantilt-cam-plus-3k.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/devices/cameras/pantilt-cam-plus-3k.md b/devices/cameras/pantilt-cam-plus-3k.md index 5ca1b8d..582f025 100644 --- a/devices/cameras/pantilt-cam-plus-3k.md +++ b/devices/cameras/pantilt-cam-plus-3k.md @@ -21,7 +21,26 @@ | deviceId | String | device ID | | deviceType | String | device type. _Pan/Tilt Cam Plus 3K_ | | hubDeviceId | String | device's parent Hub ID | -| latestImage | Object | the latest snapshot image info. an empty object when no snapshot is available | +| latestImage | Object | the latest snapshot image info. contains `imageUrl` and `expireAt`. an empty object when no snapshot is available | + +The `latestImage` object has the following attributes. + +| Key | Value Type | Description | +| -------- | ---------- | ----------------------------------------------------------------------------------------------- | +| imageUrl | String | a pre-signed URL of the latest snapshot image (taken when the latest motion event occurred) | +| expireAt | Long | the time stamp (in seconds) when the pre-signed URL expires. about 10 minutes after the request | + +```js +{ + "deviceId": "FFFFFFFFFFFF", + "deviceType": "Pan/Tilt Cam Plus 3K", + "hubDeviceId": "000000000000", + "latestImage": { + "imageUrl": "https://...", + "expireAt": 1789445322 + } +} +``` --- From ecddf57ed324334e2ba6fdf006d4044827dd9fdb Mon Sep 17 00:00:00 2001 From: hsakoh <20980395+hsakoh@users.noreply.github.com> Date: Wed, 16 Sep 2026 18:35:43 +0900 Subject: [PATCH 24/24] Video Doorbell: describe hubDeviceId as the paired indoor monitor's device ID, add status example --- devices/cameras/video-doorbell.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/devices/cameras/video-doorbell.md b/devices/cameras/video-doorbell.md index 2bc3769..092727e 100644 --- a/devices/cameras/video-doorbell.md +++ b/devices/cameras/video-doorbell.md @@ -16,14 +16,25 @@ ## Device Status -| Key | Value Type | Description | -| ----------- | ---------- | --------------------------------------------------------- | -| deviceId | String | device ID | -| deviceType | String | device type. _Video Doorbell_ | -| hubDeviceId | String | device's parent Hub ID | -| version | String | the current firmware version, e.g. V2.02.033 | -| battery | Integer | the current battery level | -| online | Boolean | the connection status of the device. _true_ or _false_ | +| Key | Value Type | Description | +| ----------- | ---------- | ---------------------------------------------------------------------------------------------- | +| deviceId | String | device ID of the doorbell (outdoor unit) | +| deviceType | String | device type. _Video Doorbell_ | +| hubDeviceId | String | device ID of the indoor monitor (base station) that the doorbell is paired with | +| version | String | the current firmware version, e.g. V2.02.033 | +| battery | Integer | the current battery level | +| online | Boolean | the connection status of the device. _true_ or _false_ | + +```js +{ + "version": "V2.02.033", + "battery": 100, + "online": true, + "deviceId": "FFFFFFFFFFFF", + "deviceType": "Video Doorbell", + "hubDeviceId": "EEEEEEEEEEEE" +} +``` ---