ecovacs-skills-pet-control

SKILL.md

---
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**.