| name | switchbot |
| description | Control SwitchBot smart home devices (curtains, plugs, lights, locks, etc.) via SwitchBot Cloud API. Use when user asks to open/close curtains, turn on/off lights/plugs, check temperature/humidity, or control any SwitchBot device. |
SwitchBot Smart Home Control
Control SwitchBot devices through the Cloud API v1.1.
First-Time Setup
Guide your human through these steps:
1. Get API Credentials
Ask your human to:
- Open SwitchBot App on their phone
- Go to Profile (bottom right)
- Tap Preferences (or Settings)
- Find About → Developer Options
- Copy Token and Secret Key
2. Store Credentials Securely
mkdir -p ~/.config/switchbot
chmod 700 ~/.config/switchbot
cat > ~/.config/switchbot/credentials.json << 'EOF'
{
"token": "YOUR_TOKEN_HERE",
"secret": "YOUR_SECRET_HERE"
}
EOF
chmod 600 ~/.config/switchbot/credentials.json
3. Discover Devices
Run the discovery script to find all devices:
python3 <skill_path>/scripts/switchbot.py list
4. Update Your TOOLS.md
After discovery, note your device IDs in TOOLS.md for quick reference:
## SwitchBot Devices
| Device | ID | Type |
|--------|-----|------|
| Living Room Curtain | ABC123 | Curtain3 |
| Bedroom Light | DEF456 | Plug Mini |
Usage
List All Devices
python3 <skill_path>/scripts/switchbot.py list
Curtain Control
python3 <skill_path>/scripts/switchbot.py curtain <device_id> open
python3 <skill_path>/scripts/switchbot.py curtain <device_id> close
python3 <skill_path>/scripts/switchbot.py curtain <device_id> 50
Plug/Light Control
python3 <skill_path>/scripts/switchbot.py plug <device_id> on
python3 <skill_path>/scripts/switchbot.py plug <device_id> off
Check Sensor Status
python3 <skill_path>/scripts/switchbot.py status <device_id>
Generic Command
python3 <skill_path>/scripts/switchbot.py command <device_id> <command> [parameter]
Supported Devices
| Device Type | Commands |
|---|
| Curtain / Curtain3 | open, close, setPosition |
| Plug Mini / Plug | turnOn, turnOff, toggle |
| Bot | press, turnOn, turnOff |
| Light / Strip Light | turnOn, turnOff, setBrightness, setColor |
| Lock | lock, unlock |
| Humidifier | turnOn, turnOff, setMode |
| Meter / MeterPlus | (read-only: temperature, humidity) |
| Hub / Hub Mini / Hub 2 | (gateway only) |
Error Handling
| Status Code | Meaning |
|---|
| 100 | Success |
| 151 | Device offline |
| 152 | Command not supported |
| 160 | Unknown command |
| 161 | Invalid parameters |
| 190 | Internal error |
Tips for Agents
- First interaction: If no credentials exist, guide the human through setup
- Device aliases: Create friendly names in TOOLS.md (e.g., "living room" → device ID)
- Batch operations: Multiple devices can be controlled in sequence
- Status checks: Use
status command before reporting sensor readings
- Error recovery: If device is offline (151), suggest checking Hub connection
Security Notes
- Credentials file should be chmod 600
- Never log or display the token/secret
- API calls are made over HTTPS to api.switch-bot.com
