ecovacs-skills-deebot-control

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

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