Ecovacs Pet (FAMIBOT) Control

What you need

Three-step flow

1. Configure AK (export ECOVACS_AK=... or python3 scripts/ecovacs.py set-ak <ak>)
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 Mainland China Open Platform domain.

Usage constraints

• Requests use cmd (string) + data (object); invalid parameters surface as cloud error messages.
• If the gateway returns command not enabled, that cmd is outside the deployment's supported set — use only commands listed below or ask a maintainer.

Response fields and set* inputs

See references/schema.md.

Supported commands

Queries

Settings

Control

Sound routing (conversation → payload) — see phoenix-single-action.md §2.2:

For action_sequence rows, each play_sound step needs an explicit file (choose using the table above before building JSON).

Dance — single preset in references/dance-routines.md (showcase_custom / 定制秀舞):

Fixed script ~45s; length is ignored. Aliases (cheerful, 点头舞, etc.) all map to the same dance.

Persona / mood (read-only): getPerson, getPetState, getEmotion.

Sleep: display <nick> sleep.

Motion protocols — two paths; do not mix fields between them:

Critical — pick one protocol and its field names only:

Common mistakes: copying a single-action JSON into actions[] (×100 angles, -1 times); using percent in display action wag_tail without letting the script convert (OK in CLI, wrong on raw wire); using angle: "3000" in a dance step (device expects "30").

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.

Dance / timed barks / multi-step shows: one action_sequence per show. Dance: build_dance_sequence() → showcase_custom — see references/dance-routines.md.

Default timing limits (hand-built JSON only; preset dance is exempt — see below):

user_timing is stripped before the gateway sees the payload.

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}'

python3 "$SCRIPT" cmd <nickname-fragment> getPerson '{}'
python3 "$SCRIPT" display <nickname-fragment> dance
python3 "$SCRIPT" display <nickname-fragment> dance showcase_custom

python3 "$SCRIPT" cmd <nickname-fragment> playSound '{"category":"happy","count":1}'

python3 "$SCRIPT" cmd <nickname-fragment> playSound '{"file":"happy-h-3","count":1}'

python3 "$SCRIPT" display <nickname-fragment> sleep
python3 "$SCRIPT" display <nickname-fragment> reset
python3 "$SCRIPT" display <nickname-fragment> action shake_head '{"angle":"30","moveTimeMs":"-1","count":"3"}'

python3 "$SCRIPT" display <nickname-fragment> action wag_tail '{"percent":30,"moveTimeMs":"-1"}'

python3 "$SCRIPT" cmd <nickname-fragment> playSound '{"file":"happy-h-1","count":1,"conditions":{"scheduled":"0","repeat_type":"1","repeat_count":"10"}}'

HTTP calls (no Python available)

Default gateways: Mainland China https://open.ecovacs.cn, non-China regions 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

Supported commands are listed in this SKILL.md; protocol docs describe only those motion paths. Legacy multi-routine names (cheerful_motion, party, 点头舞, …) are aliases to showcase_custom only.