switchbot

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

1. 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.
2. 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.
3. LOW actuations proceed with a logged notice. Curtain and Blind Tilt moves (setPosition) print a notice to stderr and run without confirmation.
4. 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.
5. Reads (auth, devices, status, scenes) never need confirmation.
6. Rate limit: about 10,000 requests/day. Poll status sparingly.
7. 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.
8. 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.