yeedi-protocol

A clean, dependency-light Python library that reverse-engineers the private Yeedi/Ecovacs cloud protocol, with live tests as the source of truth.

The Yeedi mobile app talks to the cloud via undocumented REST endpoints that aren't part of any public API. The behavior was pieced together from:

• mrbungle64/ecovacs-deebot.js (the only actively maintained client)
• bmartin5692/sucks (older Python RE work)
• Live probing against gl-{country}-api.yeedi.com with real credentials

The Home Assistant integration at Mark/yeedi_awmbuild consumes this library. Building it as a separate package lets us prove the protocol with a clean test runner and decouple the HA scaffolding from the "what does the server actually want" work.

Layout

src/yeedi_protocol/
    auth.py      # 3-step login + 1013 device-verification recovery
    crypto.py    # authSign MD5 + RSA encrypt for verification
    discovery.py # list_user_devices() + probe helpers
    cli.py       # yeedi-probe {login,discover,recovery,full}
    errors.py
tests/
    live/        # scripts that hit the real server, gated on env vars
    unit/        # deterministic tests with mocked HTTP

Run live tests

export YEEDI_EMAIL='you@example.com'
export YEEDI_PASSWORD='your-password'
export YEEDI_COUNTRY='US'    # default if unset
uv run pytest -v

A live test only runs if both env vars are set; otherwise pytest skips it. Every live test prints the actual server response so a failure shows you exactly what came back, not a guess.

What's verified live (2026-10-09)

Step	Endpoint	Status
1. user/login	GET gl-{cc}-api.yeedi.com/v1/private/.../user/login	✅ 0000
2. getAuthCode	GET gl-{cc}-openapi.yeedi.com/v1/global/auth/getAuthCode	✅ 0000
3. loginByItToken	POST api-app.dc-{cc}.ww.ecouser.net/api/users/user.do	✅ result=ok
4. GetDeviceList	POST {api-app.dc-{cc}.ww or portal-{cc}}/users/user.do	✅ result=ok — returns bound bots
5. Commands	POST iot/devmanager.do	✅ body shape verified, 10s timeout — times out cleanly when bot is offline
5b. GetCleanLogs	POST {portal_host}/lg/log.do	✅ result=ok, works even when bot is offline

Bot-offline behavior: iot/devmanager.do holds the HTTP connection open waiting for the device to ACK. When the bot is on the dock and idle, calls time out cleanly with CommandError. Catch it and treat the device as unavailable until the next successful call. The existing HA yeedi_c12_cloud integration has the same behavior.

await async_login(session, email, password, country, device_id) returns (Auth, [Device]) with the user's actual vacuum(s). See PROTOCOL.md for the full writeup.