88 lines
4.5 KiB
Markdown
88 lines
4.5 KiB
Markdown
---
|
|
name: switchbot-control
|
|
description: Gated SwitchBot Cloud device control via the local reference CLI (tmp/reference/switchbot-control-reference) — turn-on/off, fan/AC/lock commands, and custom IR buttons. Always resolves and inspects the target first, always dry-runs before a real send, always requires explicit user approval before executing.
|
|
---
|
|
|
|
# SwitchBot Control (gated)
|
|
|
|
This wraps `tmp/reference/switchbot-control-reference/scripts/switchbotctl`,
|
|
the full control CLI. Every real control call fires a real signal at real
|
|
hardware (an actual IR blast, an actual lock toggle) — treat every non-dry-run
|
|
invocation as something you are asking permission to do, not something you
|
|
just do.
|
|
|
|
## Required sequence, every time
|
|
|
|
1. **Resolve the device.** Use the `switchbot-read` skill (`list all` /
|
|
`list remotes` / `list switches` / `list locks`) to find the exact
|
|
`deviceId` for the device the user named. Never guess an ID or reuse one
|
|
from memory without re-confirming it still matches — if more than one
|
|
device could match the name, ask which one; never pick one silently.
|
|
2. **Inspect the interface.** Run `switchbot-read interface DEVICE_ID` and
|
|
confirm the command you're about to send is actually in its documented
|
|
`commands` list (or, for a custom button, that the device is an infrared
|
|
remote where `customize`-type commands apply).
|
|
3. **Dry-run first.** Always construct and check the exact call with
|
|
`--dry-run` before ever running it for real:
|
|
```bash
|
|
cd tmp/reference/switchbot-control-reference
|
|
GOWORK=off ./scripts/switchbotctl ac DEVICE_ID 24 cool medium on --dry-run
|
|
```
|
|
Confirm the echoed `command`/`parameter`/`commandType` in the dry-run
|
|
output is exactly what you intend.
|
|
4. **Ask for explicit approval** before running the same command without
|
|
`--dry-run`. State the exact device (name + ID) and the exact action in
|
|
plain language. Do not treat a general "go ahead with the plan" from
|
|
earlier in the conversation as approval for a specific real control call —
|
|
ask again, per command, right before running it.
|
|
5. **Execute once.** Run the approved command exactly once. Do not retry
|
|
automatically on failure or on an ambiguous result — a repeated lock,
|
|
toggle, Bot press, or custom IR command can produce a real second action
|
|
(e.g. re-toggling something back off). If it needs retrying, ask first.
|
|
6. **Treat success as API acceptance, not physical confirmation.** SwitchBot
|
|
Cloud's infrared control is fire-and-forget — a `200`/`statusCode: 100`
|
|
response means the cloud accepted the command, not that the appliance
|
|
actually received or acted on the IR signal.
|
|
|
|
## Custom IR buttons (`button`) need the user, not a guess
|
|
|
|
```bash
|
|
GOWORK=off ./scripts/switchbotctl button DEVICE_ID "Exact Button Name" --dry-run
|
|
```
|
|
|
|
SwitchBot's API cannot enumerate a device's learned custom button names —
|
|
they only exist as case-sensitive labels in the SwitchBot app. Never
|
|
approximate, guess, or case-fold a button name. If you don't have the exact
|
|
label from the user, stop and ask for it rather than trying a plausible
|
|
guess.
|
|
|
|
## Command reference (see `tmp/reference/switchbot-control-reference/README.md` for the full list)
|
|
|
|
```bash
|
|
switchbotctl turn-on DEVICE_ID [--dry-run]
|
|
switchbotctl turn-off DEVICE_ID [--dry-run]
|
|
switchbotctl press DEVICE_ID [--dry-run]
|
|
switchbotctl lock DEVICE_ID [--dry-run]
|
|
switchbotctl unlock DEVICE_ID [--dry-run]
|
|
switchbotctl fan DEVICE_ID swing|timer|lowSpeed|middleSpeed|highSpeed [--dry-run]
|
|
switchbotctl ac DEVICE_ID TEMPERATURE MODE FAN_SPEED POWER [--dry-run]
|
|
switchbotctl button DEVICE_ID "Exact Button Name" [--dry-run]
|
|
switchbotctl send DEVICE_ID COMMAND PARAMETER COMMAND_TYPE [--dry-run] # generic escape hatch
|
|
```
|
|
|
|
Always run from `tmp/reference/switchbot-control-reference/` with
|
|
`GOWORK=off` prefixed (this repo's root `go.work` doesn't include this nested
|
|
module — see the `switchbot-read` skill for why not to fix that by editing
|
|
`go.work`).
|
|
|
|
## Hard rules
|
|
|
|
- Never read, print, edit, source, or expose `.env` in this directory.
|
|
- Never add an automatic hook, cron, or script that calls `switchbotctl`
|
|
without a human in the loop for that specific invocation.
|
|
- This CLI is a **development/testing aid only** — it is not a dependency of
|
|
`ha-gateway`. The actual `RemoteService` implementation in `ha-gateway` has
|
|
its own hand-rolled SwitchBot HTTP client (see `plan.md`); use this CLI to
|
|
discover device IDs and verify command behavior during development, not as
|
|
something the running services call at runtime.
|