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

[hsakoh]

Summary

I verified the documentation against actual API responses and webhook payloads captured from real devices (29 physical device types I own, covering device list, status polling, and webhook changeReport events), and fixed the differences that were directly observed.

• 17 fix commits to existing device pages (one commit per device for traceability)
• 5 commits adding documentation for devices/features that were previously undocumented

Methodology

• Captured GET /devices, GET /devices/{id}/status, and webhook payloads from real devices over roughly a day, plus targeted status polling.
• Only differences directly observed on the corresponding device/API surface were changed. Spec values that could not be observed (e.g. enum values such as jammed, event-dependent fields such as overload) were left untouched.

Notable fixes

• Lock Ultra: the deviceType strings for status (Smart Lock Ultra) and webhook (Lock Ultra) were documented the other way around; lockState/doorState values corrected to the observed past-participle forms (unlocked/closed); missing onlineStatus (status) and doorState (webhook) added.
• Video Doorbell: the webhook does not use the documented flat detectionState/press fields. Observed payloads use nested humanEvent/ringEvent/motionEvent objects ({detectionType, eventTime, id, img}); the section was rewritten accordingly.
• Pan/Tilt Cam Plus 3K: the device does respond to status and does send webhooks (deviceType WoCamKvs5mp, nested motionEvent/humanEvent); documented both and updated the support table.
• Relay Switch 2PM: webhook keys are switch1Status/switch2Status (only the changed switch is included) and timeOfSample is present; the table/example were inconsistent with each other and with observed payloads.
• Smart Lock / Motion Sensor: missing webhook fields (doorState, brightness) added.
• Presence Sensor: the status key is detected (lowercase, was Detected), and the webhook example deviceType was WoContact.
• Relay Switch 1: status also returns voltage/power/usedElectricity/electricCurrent, always 0 since the device has no power monitoring.
• Lighting (Ceiling Light / Color Bulb / Strip Light / Strip Light 3 / RGBIC Neon Wire Rope Light) and Plug Mini (JP): webhook payloads include online (Boolean), which was undocumented; also added missing status fields (power, onlineStatus, colorTemperature) and fixed a wrong webhook example deviceType (RGBICWW Strip Light → RGBIC Wire Neon Rope Light).
• Curtain: slidePosition is a number, not a String.
• Circulator Fan: missing chargingStatus/hubDeviceId and wrong nightStatus type in the webhook table.
• Keypad Touch: status also returns battery and version. Observed webhooks include undocumented keyName/battery, and the "deleteKey " trailing space in the example was confirmed to be a typo.
• Mini Robot Vacuum K10+ Pro: full-width colon in the webhook example JSON.

New device documentation

• Outdoor Pan/Tilt Cam 3K — deviceType Outdoor PTC 3K; webhook deviceType W1156000 with nested humanEvent/motionEvent.
• Universal Remote — deviceType remote with screen (all lowercase); status returns version/battery/chargingStatus.
• Wallet Finder Card — listed in the device list; status responds with an empty body.
• Video Doorbell Add-on Monitor — appears in the device list without a deviceType key; status responds with an empty body.

All observed sample payloads were captured with SwitchBot API v1.1 on 2026-07-22/23 (JP region).

[hsakoh]

Open question: documented fields that were never observed

The following fields are documented but never appeared in any response or webhook from my devices. I have not removed them in this PR because absence alone is not proof. Could you confirm whether they should be removed, or whether the condition under which they are returned (firmware version, device configuration, trigger source) should be noted?

Page / line	Surface	Field	What I observed
ceiling-light.md#L28	Status	onlineStatus	Never returned (firmware V2.3-1.2)
strip-light.md#L28	Status	onlineStatus	Never returned (firmware V1.1-1.1; may be an old-firmware issue)
circulator-fan.md#L22	Status	deviceName	Never returned by GET /devices/{id}/status
mini-robot-vacuum-k10-pro.md#L22	Status	deviceName	Never returned by GET /devices/{id}/status
circulator-fan.md#L59 (table), #L76 (example)	Webhook	version	Not present in any WoFan2 webhook
roller-shade.md#L12	Device list	bleVersion	Not present in the device list entry
lock-ultra.md#L16	Device list	groupName	Not present for a non-grouped lock (group: false); possibly only returned when grouped
keypad-touch.md#L80 (table), #L96 / #L115 (examples)	Webhook	commandId	Not present in observed createKey / deleteKey webhooks; possibly only returned when the key was created via the API createKey command

If any of these are confirmed obsolete I am happy to remove them in a follow-up commit.

[hsakoh]

Pushed two more commits based on a new capture (2026-09-15/16, same devices):

• Pan/Tilt Cam Plus 3K (bbad36d): latestImage is no longer always empty on my device. It is { "imageUrl": "<pre-signed URL>", "expireAt": <unix seconds> }, where the URL points to the snapshot of the latest motion event and expires about 10 minutes after the request (expireAt matches the URL's X-Amz-Date + X-Amz-Expires). Documented the structure with an example.
• Video Doorbell (ecddf57): in the status response, hubDeviceId is the device ID of the paired indoor monitor (base station), not a Hub. deviceId is the outdoor doorbell unit. Clarified both descriptions and added a status example.

No other differences from the documentation were found in the new capture.

[hsakoh]

Pushed one more commit (fc56c93): Keypad Vision Pro

• Status: added battery (Integer, 0-100) and version (String, e.g. V3.0).
• Webhook: added battery to the context table.

Unlike the rest of this PR, this change is not based on my own captures. It comes from logs of a user's Keypad Vision Pro (firmware V3.0) reported in hsakoh/switchbot-mqtt#121:

• GET /devices/{id}/status returned version ("V3.0") and battery (e.g. 83, 84) on every poll.
• A webhook from the device included battery (83).

According to the reporter, SwitchBot support (case #1363398) confirmed that version and battery are valid status fields for Keypad Vision Pro and that the documentation will be updated.

The logs do not show which event the webhook with battery belonged to, so I only added it to the key table and left the createKey / deleteKey examples unchanged. The added fields match what Keypad Touch returns (700c440).

[Minsheng]

@hsakoh I will go over your commits. Thanks bro!

[hsakoh]

@Minsheng Thanks for taking a look!

I pushed one more commit (2abf09e): Keypad Vision

• Status: added battery (Integer, 0-100) and version (String, e.g. V2.5).
• Webhook: added battery to the context table.

Like the Keypad Vision Pro commit (fc56c93), this is not based on my own captures. A user reported the status response of their Keypad Vision (firmware V2.5) in hsakoh/switchbot-mqtt#121 (device IDs redacted by the reporter):

{"statusCode":100,"body":{"version":"V2.5","battery":98,"deviceId":"myserialnumber","deviceType":"Keypad Vision","hubDeviceId":"hubid"},"message":"success"}

Only the status side was observed. No webhook from this device was captured, so the webhook battery row is an assumption based on Keypad Touch (700c440, my own captures) and Keypad Vision Pro (fc56c93, user logs), which both send it. Could you confirm whether Keypad Vision webhooks include battery? If they do not, I will drop that row.