Switchbot

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: 1. Open SwitchBot App on their phone 2. Go to Profile (bottom right) 3. Tap Preferences (or Settings) 4. Find About → Developer Options 5. 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 /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 /scripts/switchbot.py list

Curtain Control

# Open curtain (position 0 = fully open)
python3 /scripts/switchbot.py curtain  open
Close curtain (position 100 = fully closed)
python3 /scripts/switchbot.py curtain  close
Set specific position (0-100)
python3 /scripts/switchbot.py curtain  50

Plug/Light Control

python3 /scripts/switchbot.py plug  on
python3 /scripts/switchbot.py plug  off

Check Sensor Status

python3 /scripts/switchbot.py status 

Generic Command

python3 /scripts/switchbot.py 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

1. First interaction: If no credentials exist, guide the human through setup 2. Device aliases: Create friendly names in TOOLS.md (e.g., "living room" → device ID) 3. Batch operations: Multiple devices can be controlled in sequence 4. Status checks: Use status command before reporting sensor readings 5. Error recovery: If device is offline (151), suggest checking Hub connection

Security Notes

List All Devices

python3 /scripts/switchbot.py list

Curtain Control

# Open curtain (position 0 = fully open)
python3 /scripts/switchbot.py curtain  open
Close curtain (position 100 = fully closed)
python3 /scripts/switchbot.py curtain  close
Set specific position (0-100)
python3 /scripts/switchbot.py curtain  50

Plug/Light Control

python3 /scripts/switchbot.py plug  on
python3 /scripts/switchbot.py plug  off

Check Sensor Status

python3 /scripts/switchbot.py status 

Generic Command

python3 /scripts/switchbot.py command   [parameter]