66 lines
3.0 KiB
Markdown
66 lines
3.0 KiB
Markdown
---
|
|
name: switchbot-read
|
|
description: Read-only SwitchBot Cloud discovery via the local reference CLI (tmp/reference/switchbot-control-reference) — list devices/infrared remotes and inspect a device's documented command interface. Never sends control commands and never touches .env.
|
|
---
|
|
|
|
# SwitchBot Read-Only Discovery
|
|
|
|
Use this whenever you need to find a SwitchBot device ID, confirm a device's
|
|
type, or see which commands are documented for it — e.g. resolving "the
|
|
Dyson" or "the AC" to an exact `deviceId` before building or running any
|
|
control call in `ha-gateway`'s `RemoteService`.
|
|
|
|
This wraps `tmp/reference/switchbot-control-reference/scripts/switchbot-read`,
|
|
a wrapper that only accepts `list` and `interface` — it has no code path that
|
|
can send a device command, so it's safe to run freely.
|
|
|
|
## Why `GOWORK=off` is required
|
|
|
|
This reference tool is nested inside the `home-service` repo but is its own
|
|
Go module, not a member of the root `go.work`. Running it from inside the
|
|
workspace fails with "directory prefix . does not contain modules listed in
|
|
go.work" unless you disable workspace mode for that one subprocess:
|
|
|
|
```bash
|
|
cd tmp/reference/switchbot-control-reference
|
|
GOWORK=off ./scripts/switchbot-read list all
|
|
```
|
|
|
|
Do not add this tool to the root `go.work` — that file is committed, `tmp/`
|
|
is gitignored, and pointing a committed file at a gitignored path would break
|
|
every other clone of this repo.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
GOWORK=off ./scripts/switchbot-read list all
|
|
GOWORK=off ./scripts/switchbot-read list physical
|
|
GOWORK=off ./scripts/switchbot-read list remotes # infrared/virtual remotes — Dyson, AC live here
|
|
GOWORK=off ./scripts/switchbot-read list switches
|
|
GOWORK=off ./scripts/switchbot-read list locks
|
|
GOWORK=off ./scripts/switchbot-read interface DEVICE_ID
|
|
```
|
|
|
|
Output is JSON: `{filter, count, devices: [...]}` for `list`, or a single
|
|
`deviceView` object for `interface`. Each device includes a `commands` array
|
|
of documented `{name, parameter, commandType, description}` entries derived
|
|
from the device's type — this is a **static catalog**, not something
|
|
dynamically read from the appliance, and it does not include learned custom
|
|
IR button names (SwitchBot's API has no endpoint for that — see
|
|
`CustomButtonNamesDiscoverable: false` on infrared entries).
|
|
|
|
## Rules
|
|
|
|
1. Never read, print, or expose `tmp/reference/switchbot-control-reference/.env`
|
|
yourself — the CLI reads it internally via `os.Getenv`, you never need to.
|
|
(A project hook already blocks `Read`/`Edit`/`Write` on real `.env` files
|
|
and Bash commands referencing them, but don't rely on the hook — just
|
|
don't try.)
|
|
2. This skill is discovery-only. If you need to send a command, use the
|
|
`switchbot-control` skill instead — never shell out to `switchbotctl`
|
|
(the full CLI) from here.
|
|
3. Treat `commands` in the output as "what SwitchBot's documented API
|
|
supports for this device type," not confirmation the physical appliance
|
|
will respond correctly to every listed command — some DIY/customized
|
|
remotes reject a documented standard command with error 160.
|