Ecovacs Pet (FAMIBOT) Control

What you need

Three-step flow

1. Configure AK (export ECOVACS_AK=... or python3 scripts/ecovacs.py set-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 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.