Skill: ecovacs-ai/ecovacs-skills-pet-control (version 1.0.0)

--- name: ecovacs-pet-control description: 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. --- # 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 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 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 ```bash 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** ```bash curl -sS "${BASE_URL}/robot/skill/deviceList?ak=YOUR_AK" ``` **Pet control** ```bash 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](references/api.md) | User | Gateway URLs and request body fields | | [references/schema.md](references/schema.md) | User | Common response fields, `set*` input names and compatibility rules | | [references/troubleshooting.md](references/troubleshooting.md) | User | Common error branches and resolution paths | **Convention**: capability boundaries are defined by the **gateway allowlist**.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)