Ecovacs Robot Control#

Auth Flow#

Three-step flow: Login → Device List → Send Command

Full API details in references/api.md. Core script in scripts/ecovacs.py.

Session Management#

Session (token + userid + resource) is stored in ~/.ecovacs_session.json after login. Always load_session() before calling device APIs. Re-login if token expired (errno 3000).

Critical Rule#

toType = device's class field from device list (e.g. o0lqjm).

NOT "device" or "USER" — this is the #1 cause of errno:3003 permission denied.

---

Using the Script#

bash

# First time login
python3 scripts/ecovacs.py login <phone> <md5_or_plain_password>

# List all devices (shows did, status, name)
python3 scripts/ecovacs.py devices

# Check battery (use did or nick)
python3 scripts/ecovacs.py battery <did>

# Check clean status
python3 scripts/ecovacs.py status <did>

# Start full-house auto clean
python3 scripts/ecovacs.py clean <did> start

# Pause / resume / stop
python3 scripts/ecovacs.py clean <did> pause
python3 scripts/ecovacs.py clean <did> resume
python3 scripts/ecovacs.py clean <did> stop

# Return to dock
python3 scripts/ecovacs.py charge <did>

# Send any arbitrary command
python3 scripts/ecovacs.py cmd <did> getLifeSpan '{"type":"brush,sideBrush,heap"}'
python3 scripts/ecovacs.py cmd <did> setSpeed '{"speed":1}'
python3 scripts/ecovacs.py cmd <did> getWorkMode '{}'

---

Direct API Calls#

When using tools directly (not script), follow this pattern:

python

# 1. Login
session = login(phone, md5(password))

# 2. Get devices
devices = get_devices(session)
device = next(d for d in devices if "T50" in d["deviceName"])

# 3. Send command
result = send_cmd(session, device, "clean_V2", {
    "act": "start",
    "content": {"type": "auto", "count": 1}
})

See references/api.md for full protocol reference:

• Auth & device discovery — login, resource generation, device list fields
• All command payloads — clean_V2, charge, battery, stats, speed, water, workmode, lifespan, autoEmpty, maps, schedules
• State/event codes — error codes, evt codes, clean states

---

Common Protocols Quick Reference#

GoalcmdNamekey body.data fields开始全屋清扫clean_V2``{act:"start", content:{type:"auto",count:1}}区域清扫clean_V2``{act:"start", content:{type:"spotArea",value:"mssid1,mssid2"}}暂停/继续/停止clean_V2``{act:"pause/resume/stop"}回充charge``{act:"go"}查电量getBattery``{}查清扫状态getCleanInfo_V2``{}查本次面积时长getStats``{}查/设吸力getSpeed/ setSpeed``{speed:0} (1000静音/0标准/1强劲/2超强)查/设水量getWaterInfo/ setWaterInfo``{amount:2} (1低/2中/3高/4超高)查/设扫拖模式getWorkMode/ setWorkMode``{mode:0} (0边扫边拖/1仅扫/2仅拖/3先扫后拖)查耗材getLifeSpan``{type:"brush,sideBrush,heap,filter"}手动集尘setAutoEmpty``{act:"start"}查地图列表getCachedMapInfo``{}查房间区域getMapSet``{mid:"<map_id>",type:"ar"}查预约getSched_V2``{type:1}

---

Error Handling#

errnomeaning3000Token expired → re-login3003Permission denied → check toType = device class30000Device response timeout → device offline0 (body.code)Success

---

Accounts (China domestic)#

• Login URL: https://api-app.dc-cn.cn.ecouser.net/api/users/user.do
• org: ECOCN, country: CN
• Password: MD5 hex of plaintext