ecovacs-skills-pet-control — ecovacs-技能s-pet-control

Ecovacs Pet (FAMI机器人) Control What you need You provide Notes AK (访问 Key) 获取 one from the Ecovacs Open 平台 “服务 Overview” (CN: https://open.ecovacs.cn/, INTL: https://open.ecovacs.com/) and put it in your env or pass to 设置-ak. Do not hand the 技能 a username/password to 记录 in on your behalf. Device nickname fragment Used to fuzzy-match nick or name returned by the device 列出. Three-step flow 配置 AK (导出 ECOVACS_AK=... or python3 scripts/ecovacs.py 设置-ak ) 列出 devices: python3 scripts/ecovacs.py devices Control: Use POST /ro机器人/技能/pet/cmd or the script's cmd / display subcommands; cmd must be in the gateway allow列出, otherwise the gateway returns command not enabled.

运行 from the 仓库 root: python3 scripts/ecovacs.py .... You may 设置 ECOVACS_PORTAL_URL to a custom gateway base URL; when un设置, the default is the CN Open 平台 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 allow列出 is rejected; to expose more cmd values, ask a mAIntAIner (or 配置 PET_CMD_ALLOW列出). 响应 field notes and common 设置 输入s (externalized)

For field explanations and common 设置 输入s, see references/模式.md.

Capabilities currently exposed

Name-level only; data is 验证d by the cloud; actual avAIlability depends on the allow列出 检查.

Queries Description cmd Pet 状态 / emotion / achievements / persona / gender / location & weather / initialization 获取Pet状态, 获取Emotion, 获取Achievement, 获取Person, 获取PetGender, 获取Location信息, 获取Initiate状态 Microphone / camera / volume / eye brightness / language / wake idle timeout 获取Micro, 获取Camera, 获取Volume, 获取EyesLight, 获取Language, 获取WakeTimeout Latest diary entry 获取LatestDiary

Dee机器人-style cmd (battery, work 状态, consumables, etc.) are not enabled by default; ask a mAIntAIner to enable them if required.

设置tings Description cmd Microphone / camera / volume / eye brightness / language / wake idle timeout / wake word / gender / initialization 设置Micro, 设置Camera, 设置Volume, 设置EyesLight, 设置Language, 设置WakeTimeout, 设置Nickname, 设置PetGender, 设置Initiate状态

Note: 设置EyesLight currently returns parameter error (20011) on some hardware, and 设置Camera may time out (errno=500) on some hardware. 机器人h are not enabled by default; if needed, ask a mAIntAIner to temporarily 添加 them to PET_CMD_ALLOW列出 and 验证 on a real device.

Control Description cmd Display / action sequences (persona, motion sequences, etc.) display Play sound (high-level wr应用er, no raw file) playSound

Before 发送ing any display motion/persona action through scripts/ecovacs.py display ..., the script 检查s 获取Camera. If enable != 1, it wakes the pet through the 技能 gateway with 设置Camera {"enable":1}, wAIts until 获取Camera.enable=1, switches work mode back to standard with 设置WorkMode {"mode":"standard"}, and only then 发送s the action. 设置 ECOVACS_SKIP_WAKE_检查=1 only for 调试ging when you intentionally want to bypass this 防护.

Not enabled by default (OTA, Wi-Fi, persona mAIntenance, data wipe, etc.): adjust the allow列出 before invoking.

Script examples SCRIPT="./scripts/ecovacs.py"

python3 "$SCRIPT" cmd 获取Pet状态 '{}' python3 "$SCRIPT" cmd 获取Camera '{}' python3 "$SCRIPT" cmd 设置WakeTimeout '{"timeout":180}'

# Actions go through display; data is the business object python3 "$SCRIPT" display personality 127 python3 "$SCRIPT" display 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 playSound '{"category":"h应用y","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 列出

curl -sS "${BASE_URL}/ro机器人/技能/device列出?ak=YOUR_AK"

Pet control

curl -sS -X POST "${BASE_URL}/ro机器人/技能/pet/cmd" -H 'Content-Type: 应用/json' \ -d "{\"ak\":\"${AK}\",\"nickName\":\"nickname-fragment\",\"cmd\":\"获取Pet状态\",\"data\":{}}"

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

Compatibility path: POST /ro机器人/技能/ctl + ctl is still accepted for pet devices and is also subject to the cmd allow列出.

Recommended verification order

Use the script and HTTP examples earlier in this document (获取 first, then 设置 / display) to confirm nickName resolution and allow列出 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 FAMI机器人, command not enabled) command not enabled 添加 the cmd to PET_CMD_ALLOW列出 or ask a mAIntAIner to enable it 设置Camera / 设置WorkMode block