SwitchBot
Purpose
Read status and send commands to SwitchBot devices over the official OpenAPI
v1.1: SwitchBot Bot (physical button presser), SwitchBot Lock, Curtain and
Blind Tilt motors, plugs, lights, air conditioners, infrared remotes, and
saved scenes. Use it when the user asks about or wants to change anything in
their SwitchBot setup. Commands drive real physical hardware, so writes are
confirmation-gated (see Operating Rules).
Tooling
All commands go through bin/switchbot.py:
bin/switchbot.py auth # status check: verify token, count devices
bin/switchbot.py devices # list devices and IR remotes
bin/switchbot.py status --id <deviceId> # read device status
# Writes. lock/unlock are HIGH: they REQUIRE --confirm naming the exact
# physical effect, on every run:
bin/switchbot.py command --id <deviceId> --command lock \
--confirm "lock the back door SwitchBot lock"
bin/switchbot.py command --id <deviceId> --command unlock \
--confirm "unlock the back door SwitchBot lock"
# press / turnOn / turnOff / setAll are MEDIUM: --confirm on first use per
# device, then proceed:
bin/switchbot.py command --id <deviceId> --command press \
--confirm "press the coffee machine power button with the SwitchBot Bot"
bin/switchbot.py command --id <deviceId> --command turnOn \
--confirm "turn on the SwitchBot plug in the workshop"
bin/switchbot.py command --id <deviceId> --command setAll \
--param mode=1 --param temperature=24 --param fanSpeed=2 \
--confirm "set the bedroom AC to cool 24 degrees, fan medium"
# Curtain/blind moves (setPosition) are LOW: they proceed with a logged notice:
bin/switchbot.py command --id <deviceId> --command setPosition --param position=0
# Scenes are HIGH (their effects are whatever was saved into them):
bin/switchbot.py scenes
bin/switchbot.py scene-execute --scene-id <sceneId> \
--confirm "run the Movie Night scene (dims lights, closes curtains)"
--param KEY=VALUE builds the command's parameter as a JSON object
(setPosition uses position, AC setAll uses mode, temperature,
fanSpeed, power). For simple commands (press, turnOn, turnOff,
lock, unlock) omit --param and the default parameter "default" is
used, or pass --parameter with a raw string.
Auth
- Provider id:
switchbot (credential is collected as custom.switchbot)
- Collection: ONE combined value
token:secret via the secure credential
flow (credentials.request_api_access). In the SwitchBot app go to
Profile > Preferences, tap the app version several times to reveal
developer options, and copy the open token plus the secret. The CLI sends
the token in the Authorization header and an HMAC-SHA256 signature of
token + t + nonce (keyed by the secret) in the sign header, with t
and nonce headers.
- BLE devices (Bot, Lock, Curtain, Blind Tilt) need a SwitchBot Hub with
cloud services enabled to be reachable through this API.
- Allowed hosts:
api.switch-bot.com
- Status check:
bin/switchbot.py auth
Operating Rules
- HIGH actuations are blocked without explicit confirmation.
lock and
unlock on a SwitchBot Lock, and scene executions, require
--confirm "<exact physical effect>" on every run. Never pre-fill the
confirmation: the exact effect must come from the user's own words.
- MEDIUM actuations confirm on first use per device. Bot
press
(physically presses a real button), plug and light toggles, and AC
commands (setAll, setMode) need --confirm the first time a device
is actuated; the CLI records it locally
(~/.config/muse-connectors/switchbot/confirmed.json) and later runs
proceed.
- LOW actuations proceed with a logged notice. Curtain and Blind Tilt
moves (
setPosition) print a notice to stderr and run without
confirmation.
- A scene's physical effects are whatever the user saved into it. Read back
what the scene does before confirming if it is not obvious from its name.
- Reads (
auth, devices, status, scenes) never need confirmation.
- Rate limit: about 10,000 requests/day. Poll
status sparingly.
- Open item: the HMAC signature is computed over the credential
surrogate as delivered by the credential store. Confirm the signature
verifies against SwitchBot's servers on first live use before trusting
signed calls.
- Never exfiltrate the credential: the CLI only ever handles surrogates. Do
not print, log, or transmit the token or secret values.
Files
- SKILL.md
- bin/switchbot.py
Maturity
🧪 Draft: written from SwitchBot's public OpenAPI v1.1 docs; not yet
live-tested end-to-end. The signature-header construction and the command
parameter shapes are untested against real SwitchBot devices.
1---2name: "switchbot"3description: "Read and control SwitchBot devices: Bots, Locks, curtains, plugs, lights, AC, IR remotes, scenes. Trigger phrases: switchbot, switchbot lock, switchbot bot, switchbot curtain."4metadata:5 source: https://skillmd.com/skills/anil-matcha/switchbot6 includeInPrompt: true7tagline: "Read status and send commands to SwitchBot devices over the official OpenAPI v1.1: SwitchBot Bot (physical button presser), SwitchBot Lock, Curtain and Blind Tilt motors, plugs, lights, air conditioners, infrared remotes, and saved scenes. Use it when the user asks about or wants to change anything in their SwitchBot setup. Commands drive real physical hardware, so writes are confirmation-gated (see Operating Rules)."8catalog_auth: "token + secret pair via the secure credential flow"9catalog_hosts: ["api.switch-bot.com"]10---1112# SwitchBot1314## Purpose15Read status and send commands to SwitchBot devices over the official OpenAPI16v1.1: SwitchBot Bot (physical button presser), SwitchBot Lock, Curtain and17Blind Tilt motors, plugs, lights, air conditioners, infrared remotes, and18saved scenes. Use it when the user asks about or wants to change anything in19their SwitchBot setup. Commands drive real physical hardware, so writes are20confirmation-gated (see Operating Rules).2122## Tooling23All commands go through `bin/switchbot.py`:2425```bash26bin/switchbot.py auth # status check: verify token, count devices27bin/switchbot.py devices # list devices and IR remotes28bin/switchbot.py status --id <deviceId> # read device status2930# Writes. lock/unlock are HIGH: they REQUIRE --confirm naming the exact31# physical effect, on every run:32bin/switchbot.py command --id <deviceId> --command lock \33 --confirm "lock the back door SwitchBot lock"34bin/switchbot.py command --id <deviceId> --command unlock \35 --confirm "unlock the back door SwitchBot lock"3637# press / turnOn / turnOff / setAll are MEDIUM: --confirm on first use per38# device, then proceed:39bin/switchbot.py command --id <deviceId> --command press \40 --confirm "press the coffee machine power button with the SwitchBot Bot"41bin/switchbot.py command --id <deviceId> --command turnOn \42 --confirm "turn on the SwitchBot plug in the workshop"43bin/switchbot.py command --id <deviceId> --command setAll \44 --param mode=1 --param temperature=24 --param fanSpeed=2 \45 --confirm "set the bedroom AC to cool 24 degrees, fan medium"4647# Curtain/blind moves (setPosition) are LOW: they proceed with a logged notice:48bin/switchbot.py command --id <deviceId> --command setPosition --param position=04950# Scenes are HIGH (their effects are whatever was saved into them):51bin/switchbot.py scenes52bin/switchbot.py scene-execute --scene-id <sceneId> \53 --confirm "run the Movie Night scene (dims lights, closes curtains)"54```5556`--param KEY=VALUE` builds the command's parameter as a JSON object57(`setPosition` uses `position`, AC `setAll` uses `mode`, `temperature`,58`fanSpeed`, `power`). For simple commands (`press`, `turnOn`, `turnOff`,59`lock`, `unlock`) omit `--param` and the default parameter `"default"` is60used, or pass `--parameter` with a raw string.6162## Auth63- Provider id: `switchbot` (credential is collected as `custom.switchbot`)64- Collection: ONE combined value `token:secret` via the secure credential65 flow (`credentials.request_api_access`). In the SwitchBot app go to66 Profile > Preferences, tap the app version several times to reveal67 developer options, and copy the open token plus the secret. The CLI sends68 the token in the `Authorization` header and an HMAC-SHA256 signature of69 `token + t + nonce` (keyed by the secret) in the `sign` header, with `t`70 and `nonce` headers.71- BLE devices (Bot, Lock, Curtain, Blind Tilt) need a SwitchBot Hub with72 cloud services enabled to be reachable through this API.73- Allowed hosts: `api.switch-bot.com`74- Status check: `bin/switchbot.py auth`7576## Operating Rules771. **HIGH actuations are blocked without explicit confirmation.** `lock` and78 `unlock` on a SwitchBot Lock, and scene executions, require79 `--confirm "<exact physical effect>"` on every run. Never pre-fill the80 confirmation: the exact effect must come from the user's own words.812. **MEDIUM actuations confirm on first use per device.** Bot `press`82 (physically presses a real button), plug and light toggles, and AC83 commands (`setAll`, `setMode`) need `--confirm` the first time a device84 is actuated; the CLI records it locally85 (`~/.config/muse-connectors/switchbot/confirmed.json`) and later runs86 proceed.873. **LOW actuations proceed with a logged notice.** Curtain and Blind Tilt88 moves (`setPosition`) print a notice to stderr and run without89 confirmation.904. A scene's physical effects are whatever the user saved into it. Read back91 what the scene does before confirming if it is not obvious from its name.925. Reads (`auth`, `devices`, `status`, `scenes`) never need confirmation.936. **Rate limit:** about 10,000 requests/day. Poll `status` sparingly.947. **Open item:** the HMAC signature is computed over the credential95 surrogate as delivered by the credential store. Confirm the signature96 verifies against SwitchBot's servers on first live use before trusting97 signed calls.988. Never exfiltrate the credential: the CLI only ever handles surrogates. Do99 not print, log, or transmit the token or secret values.100101## Files102- SKILL.md103- bin/switchbot.py104105## Maturity106🧪 Draft: written from SwitchBot's public OpenAPI v1.1 docs; not yet107live-tested end-to-end. The signature-header construction and the command108parameter shapes are untested against real SwitchBot devices.