Ecovacs Pet (FAMIBOT) Control

What you need

Three-step flow

1. Configure AK (export ECOVACS_AK=... or python3 scripts/ecovacs.py set-ak \x3Cak>)
2. List devices: python3 scripts/ecovacs.py devices
3. 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

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

Settings

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

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 \x3Cnickname-fragment> getPetState '{}'
python3 "$SCRIPT" cmd \x3Cnickname-fragment> getCamera '{}'
python3 "$SCRIPT" cmd \x3Cnickname-fragment> setWakeTimeout '{"timeout":180}'

# Actions go through display; data is the business object
python3 "$SCRIPT" display \x3Cnickname-fragment> personality 127
python3 "$SCRIPT" display \x3Cnickname-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 \x3Cnickname-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)

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

Doc map

Convention: capability boundaries are defined by the gateway allowlist.