Skip to content

Align device docs with observed real-device behavior; add 4 undocumented devices #509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hsakoh wants to merge 24 commits into
base: main
Choose a base branch
from
Open

Align device docs with observed real-device behavior; add 4 undocumented devices #509

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
95578fa
Lock Ultra: fix deviceType mix-up, lockState/doorState values, add on…
hsakoh Jul 23, 2026
9194ad6
Lock: add doorState to webhook events
hsakoh Jul 23, 2026
700c440
Keypad Touch: add battery/version to status, keyName/battery to webho…
hsakoh Jul 23, 2026
12b6017
Video Doorbell: document actual nested webhook event structure
hsakoh Jul 23, 2026
ba27ca3
Presence Sensor: fix detected key casing and webhook example deviceType
hsakoh Jul 23, 2026
c40cbf7
Motion Sensor: add brightness to webhook events
hsakoh Jul 23, 2026
b177e81
Ceiling Light: add online to webhook events
hsakoh Jul 23, 2026
aa9ccee
Color Bulb: add online to webhook events
hsakoh Jul 23, 2026
6453fb1
Strip Light: add online to webhook events
hsakoh Jul 23, 2026
0b0ca54
Strip Light 3: add onlineStatus/online, fix brightness range
hsakoh Jul 23, 2026
e4ad1c8
RGBIC Neon Wire Rope Light: add colorTemperature/online, fix webhook …
hsakoh Jul 23, 2026
1109770
Curtain: fix slidePosition value type to Integer
hsakoh Jul 23, 2026
7f1529d
Plug Mini (JP): add power to status and online to webhook, fix hubDev…
hsakoh Jul 23, 2026
d2cb0d7
Relay Switch 1: document power-related status fields returned as 0
hsakoh Jul 23, 2026
e401fb9
Relay Switch 2PM: fix webhook switch status key names, add timeOfSample
hsakoh Jul 23, 2026
85b349b
Circulator Fan: add chargingStatus/hubDeviceId, fix nightStatus type
hsakoh Jul 23, 2026
6f78524
Mini Robot Vacuum K10+ Pro: fix full-width colon in webhook example
hsakoh Jul 23, 2026
95f73bb
Pan/Tilt Cam Plus 3K: document device status and webhook events
hsakoh Jul 23, 2026
6847912
Add Outdoor Pan/Tilt Cam 3K documentation
hsakoh Jul 23, 2026
0773284
Add Universal Remote documentation
hsakoh Jul 23, 2026
ed3ccd0
Add Wallet Finder Card documentation
hsakoh Jul 23, 2026
95c4368
Add Video Doorbell Add-on Monitor documentation
hsakoh Jul 23, 2026
bbad36d
Pan/Tilt Cam Plus 3K: document latestImage structure (imageUrl/expireAt)
hsakoh Sep 16, 2026
ecddf57
Video Doorbell: describe hubDeviceId as the paired indoor monitor's d…
hsakoh Sep 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -618,6 +618,10 @@ 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 | | |
| 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

Expand Down Expand Up @@ -784,6 +788,10 @@ 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)
- `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,

Expand Down Expand Up @@ -1683,7 +1691,9 @@ 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) | ✓ | ✓ | - | ✓ |
| [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

Expand All @@ -1696,6 +1706,8 @@ 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) | ✓ | ✓ | - | - |
| [Wallet Finder Card](devices/others/wallet-finder-card.md) | ✓ | - | - | - |


----
Expand Down
68 changes: 68 additions & 0 deletions devices/cameras/outdoor-pantilt-cam-3k.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
}
}
```
72 changes: 72 additions & 0 deletions devices/cameras/pantilt-cam-plus-3k.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,75 @@
| 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. 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
}
}
```

---

## 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
}
}
```

---
39 changes: 39 additions & 0 deletions devices/cameras/video-doorbell-add-on-monitor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
}
```
69 changes: 47 additions & 22 deletions devices/cameras/video-doorbell.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 BLE and Wi-Fi firmware version, e.g. V3.1-6.3 |
| 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"
}
```

---

Expand All @@ -38,17 +49,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
{
Expand All @@ -57,9 +78,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
}
}
Expand Down
Loading