Metadata

name: ecovacs-deebot-control
description: Control Ecovacs Deebot vacuums via the IoT API and a gateway. Users must obtain and provide an AK from the Open Platform; scripts/ecovacs.py and gateway /robot/skill/*. For control, battery, clean/recharge, nickname matching.

Ecovacs Deebot control

What you need

Input	Notes
AK (Access Key)	Create or view it in the Ecovacs Open Platform “Service overview” (China: `https://open.ecovacs.cn/`, Global: `https://open.ecovacs.com/`), then copy it into env vars, a config file, or chat yourself. Pick the portal region that matches your account. Do not hand account passwords to automation; this skill does not log in on your behalf.
Gateway base URL (optional)	Defaults to the same host as the Open Platform (China `https://open.ecovacs.cn`, Global `https://open.ecovacs.com`). Override with `ECOVACS_PORTAL_URL` for a self-hosted or local gateway (e.g. `mcp_portal_services`).
Device nickname fragment	Used to pick one robot. Take a substring of `nick` or `name` from the device list (fuzzy match).

If the AK is invalid (e.g. errno 3000), refresh it on the Open Platform—do not try to replace user login with other APIs.

Three steps

Configure AK → 2. Device list → 3. Send commands

1. Configure AK (pick one)

export ECOVACS_AK="YOUR_AK"
# or: python3 scripts/ecovacs.py set-ak <ak>
# writes ~/.ecovacs_session.json with {"ak":"..."} only

2. Device list

python3 scripts/ecovacs.py devices

Note the nick / name fragment you will use as <nick> below.

3. Common CLI operations

Let SCRIPT=scripts/ecovacs.py.

Queries

Battery: python3 "$SCRIPT" battery <nick>
Work state (clean / charge / station): python3 "$SCRIPT" status <nick>

Cleaning

Whole-home auto clean: python3 "$SCRIPT" clean <nick> start
Pause / resume / stop: python3 "$SCRIPT" clean <nick> pause or resume / stop

Charging

Go charge / stop go-charge: python3 "$SCRIPT" charge <nick> go or stop

HTTP gateway (no Python)

BASE_URL is the same as ECOVACS_PORTAL_URL (defaults to the regional Open Platform host).

Device list

curl -sS "${BASE_URL}/robot/skill/deviceList?ak=YOUR_AK"

Control: POST /robot/skill/ctl with JSON ak, optional nickName (fuzzy match on list), and ctl.cmd / ctl.data.

curl -sS -X POST "${BASE_URL}/robot/skill/ctl" -H 'Content-Type: application/json' \
  -d "{\"ak\":\"${AK}\",\"nickName\":\"nick-fragment\",\"ctl\":{\"cmd\":\"Charge\",\"data\":{\"act\":\"go\"}}}"

CloudCtl expects Charge, Clean, etc. with official casing—not lowercase charge.

More JSON examples (e.g. zone clean) are in references/api.md.

Errors and enums (troubleshooting)

Responses are usually two layers: outer msg / code; inner cloudctl payload under nested ctl.data with ret (ok/fail), errno, optional error.

Situation	Meaning / next step
Appendix F 5009	Command or parameter combo not supported on this model (casing, firmware); verify model, try `GetWorkState` / `GetBatteryInfo` naming
Appendix F 10004	Offline / timeout / powered off / re-provisioned
Appendix F 10000	Low battery, cannot run
Appendix F 10005	Host fault (lifted, dustbin missing, …)
Clean 10006 / Charge 10006	Internal host fault (appendix C/D)
Appendix F 4000	Malformed JSON
Appendix F 4504	Token check failed—verify AK
`ret=fail`	Read `errno` and `error` together

Water level: In sweep-only mode (no mopping / tank inactive), SetWaterInfo often fails (ret=fail); switch to a mopping-capable mode first.

Clean enums: act = s/p/r/h; workMode 0–3; zone clean uses type=spotarea + aid from GetAreaList mssid. Charge: go / stopGo.

Full tables: see “CloudCtl errors and enums” at the end of references/api.md.

How to read the docs

File	Audience	Contents
This SKILL.md	End users	Inputs, three steps, CLI, HTTP
references/api.md	Integrators	Paths, bodies, enums, curl
references/agent-internal.md	Internal	Smart clean, rooms, polling, `GetWorkState` heuristics

Prefer this page for user-facing guidance; use references/agent-internal.md only when you need implementation-level troubleshooting.

ecovacs-skills-deebot-control

安装技能