ecovacs-skills-pet-control

Other

Control Ecovacs FAMIBOT (pet) robots via the Open Platform Access Key (AK) and the gateway endpoint POST /robot/skill/pet/cmd, by sending a business cmd plus data. Covers device discovery, the cmd allowlist (PET_CMD_ALLOWLIST), common queries / settings / display, and troubleshooting.

Install

openclaw skills install ecovacs-skills-pet-control

Ecovacs Pet (FAMIBOT) Control

What you need

You provide	Notes
AK (Access Key)	Get one from the Ecovacs Open Platform “Service Overview” (CN: `https://open.ecovacs.cn/`, INTL: `https://open.ecovacs.com/`) and put it in your env or pass to `set-ak`. Do not hand the skill a username/password to log in on your behalf.
Device nickname fragment	Used to fuzzy-match `nick` or `name` returned by the device list.

Three-step flow

Configure AK (export ECOVACS_AK=... or python3 scripts/ecovacs.py set-ak <ak>)
List devices: python3 scripts/ecovacs.py devices
Control: Use POST /robot/skill/pet/cmd or the script's cmd / display subcommands; cmd must be in the gateway allowlist, otherwise the gateway returns command not enabled.

Run from the repository root: python3 scripts/ecovacs.py .... You may set ECOVACS_PORTAL_URL to a custom gateway base URL; when unset, the default is the CN Open Platform domain.

Usage constraints

Only cmd (string) + data (object) are supported; for invalid parameters, trust the error message returned by the cloud.
cmd not in the allowlist is rejected; to expose more cmd values, ask a maintainer (or configure PET_CMD_ALLOWLIST).

Response field notes and common `set*` inputs (externalized)

For field explanations and common set* inputs, see references/schema.md.

Capabilities currently exposed

Name-level only; data is validated by the cloud; actual availability depends on the allowlist check.

Queries

Description	cmd
Pet state / emotion / achievements / persona / gender / location & weather / initialization	`getPetState`, `getEmotion`, `getAchievement`, `getPerson`, `getPetGender`, `getLocationInfo`, `getInitiateState`
Microphone / camera / volume / eye brightness / language / wake idle timeout	`getMicro`, `getCamera`, `getVolume`, `getEyesLight`, `getLanguage`, `getWakeTimeout`
Latest diary entry	`getLatestDiary`

Deebot-style cmd (battery, work status, consumables, etc.) are not enabled by default; ask a maintainer to enable them if required.

Settings

Description	cmd
Microphone / camera / volume / eye brightness / language / wake idle timeout / wake word / gender / initialization	`setMicro`, `setCamera`, `setVolume`, `setEyesLight`, `setLanguage`, `setWakeTimeout`, `setNickname`, `setPetGender`, `setInitiateState`

Note: setEyesLight currently returns parameter error (20011) on some hardware, and setCamera may time out (errno=500) on some hardware. Both are not enabled by default; if needed, ask a maintainer to temporarily add them to PET_CMD_ALLOWLIST and verify on a real device.

Control

Description	cmd
Display / action sequences (persona, motion sequences, etc.)	`display`
Play sound (high-level wrapper, no raw `file`)	`playSound`

Before sending any display motion/persona action through scripts/ecovacs.py display ..., the script checks getCamera. If enable != 1, it wakes the pet through the skill gateway with setCamera {"enable":1}, waits until getCamera.enable=1, switches work mode back to standard with setWorkMode {"mode":"standard"}, and only then sends the action. Set ECOVACS_SKIP_WAKE_CHECK=1 only for debugging when you intentionally want to bypass this guard.

Not enabled by default (OTA, Wi-Fi, persona maintenance, data wipe, etc.): adjust the allowlist before invoking.

Script examples

SCRIPT="./scripts/ecovacs.py"

python3 "$SCRIPT" cmd <nickname-fragment> getPetState '{}'
python3 "$SCRIPT" cmd <nickname-fragment> getCamera '{}'
python3 "$SCRIPT" cmd <nickname-fragment> setWakeTimeout '{"timeout":180}'

# Actions go through display; data is the business object
python3 "$SCRIPT" display <nickname-fragment> personality 127
python3 "$SCRIPT" display <nickname-fragment> sequence '{"actions":[{"type":"nod_head","angle":"20","moveTimeMs":"800","count":"1","delay":"0","ctrlpoint":""}]}'

# Sound: prefer playSound (server picks a random file and fills moveTimeMs; raw voice file is not exposed)
python3 "$SCRIPT" cmd <nickname-fragment> playSound '{"category":"happy","count":10}'

HTTP calls (no Python available)

Default gateways: CN https://open.ecovacs.cn, INTL https://open.ecovacs.com (override with ECOVACS_PORTAL_URL if needed).

Device list

curl -sS "${BASE_URL}/robot/skill/deviceList?ak=YOUR_AK"

Pet control

curl -sS -X POST "${BASE_URL}/robot/skill/pet/cmd" -H 'Content-Type: application/json' \
  -d "{\"ak\":\"${AK}\",\"nickName\":\"nickname-fragment\",\"cmd\":\"getPetState\",\"data\":{}}"

The field name must be nickName exactly as above (uppercase N).

Compatibility path: POST /robot/skill/ctl + ctl is still accepted for pet devices and is also subject to the cmd allowlist.

Recommended verification order

Use the script and HTTP examples earlier in this document (get* first, then set* / display) to confirm nickName resolution and allowlist behavior before relying on higher-risk writes.

Errors and troubleshooting (summary)

Case	What to do
Outer `code != 0`	Read `msg` (invalid AK, device not found, not FAMIBOT, command not enabled)
`command not enabled`	Add the `cmd` to `PET_CMD_ALLOWLIST` or ask a maintainer to enable it
`setCamera` / `setWorkMode` blocked before a display action	Automatic wake-up could not fully run; enable both in the gateway allowlist or wake the pet manually
Token errors like 4504	Check / rotate the AK
3003	Verify nickname matches the right device and that the model supports the capability

More detailed troubleshooting (including "why was this judged not-pet") lives in references/troubleshooting.md.

Doc map

File	Audience	Content
This SKILL.md	Agent / user	AK, device list, `pet/cmd` usage, public capability name-level notes
references/api.md	User	Gateway URLs and request body fields
references/schema.md	User	Common response fields, `set*` input names and compatibility rules
references/troubleshooting.md	User	Common error branches and resolution paths

Convention: capability boundaries are defined by the gateway allowlist.