SwitchBot OpenAPI Skill

This skill equips the agent to operate SwitchBot devices via HTTPS requests to the official OpenAPI. It includes ready-to-run scripts and curl templates; use these instead of re-deriving the HMAC signature each time.

Quick Start (Operator)

1. Set environment variables in the OpenClaw Gateway/container:

• SWITCHBOT_TOKEN: your OpenAPI token
• SWITCHBOT_SECRET: your OpenAPI secret
• SWITCHBOT_REGION (optional): default global (api.switch-bot.com). Options: global, na, eu, jp.

1. Test a call (list devices):

• Bash: scripts/list_devices.sh
• Node: node scripts/switchbot_cli.js list

1. Common tasks:

• Get a device status: node scripts/switchbot_cli.js status <deviceId>
• Turn on: node scripts/switchbot_cli.js cmd <deviceId> turnOn
• Turn off: node scripts/switchbot_cli.js cmd <deviceId> turnOff
• Press (bot): node scripts/switchbot_cli.js cmd <deviceId> press
• Curtain 50%: node scripts/switchbot_cli.js cmd <deviceId> setPosition --pos=50
• Lock/Unlock (Lock): node scripts/switchbot_cli.js cmd <deviceId> lock / unlock

API Notes (concise)

Base URL by region:

• global: https://api.switch-bot.com
• na: https://api.switch-bot.com
• eu: https://api.switch-bot.com
• jp: https://api.switch-bot.com

Use path prefix /v1.1.

Headers (required):

• Authorization: <SWITCHBOT_TOKEN>
• sign: HMAC-SHA256 of (token + timestamp + nonce) using SECRET, Base64-encoded
• t: milliseconds epoch as string
• nonce: random UUID
• Content-Type: application/json

Key endpoints:

• GET /v1.1/devices
• GET /v1.1/devices/{deviceId}/status
• POST /v1.1/devices/{deviceId}/commands
  • body: { "command": "turnOn|turnOff|press|lock|unlock|setPosition|setTemperature|setMode|setVolume", "parameter": "<string>", "commandType": "command" }
• Scenes (fallback when a model has no public commands):
  • GET /v1.1/scenes
  • POST /v1.1/scenes/{sceneId}/execute

Notes on limitations:

• Some models (e.g., certain Robot Vacuum lines) do NOT expose direct commands in OpenAPI v1.1. When a command returns {statusCode:160, message:"unknown command"}, create a Scene in the SwitchBot app (e.g., "Vacuum Start") and execute it via the Scenes API.

For command parameters, see references/commands.md. Scenes usage examples are in references/examples.md.

How the Agent Should Use This Skill

• Prefer running the provided scripts. They compute signatures and handle retries.
• Preflight guard: the CLI checks device capabilities before sending commands. For Bluetooth-class devices (e.g., Bot/Lock/Curtain), it requires enableCloudService=true and a non-empty hubDeviceId. If missing, it aborts with a clear fix (bind a Hub and enable Cloud Services in the SwitchBot app).
• If environment variables are missing, ask the user to provide/define them securely (do not log secrets).
• For sensitive actions (e.g., unlock), require explicit confirmation and optionally a one-time code if the user enables it.
• On errors with code 190/TokenInvalid or 100/Unauthorized: re-check token/secret, time drift, or signature composition.

Files

• scripts/switchbot_cli.js — Node CLI for list/status/commands
• scripts/list_devices.sh — curl listing
• scripts/get_status.sh — curl status
• scripts/send_command.sh — curl command
• references/commands.md — parameters for common devices
• references/examples.md — example invocations and JSON outputs

Keep this SKILL.md lean; consult references/ for details.