How It Works¶
Disclaimer
This document is a work in progress and may contain inaccuracies or incomplete sections. Some parts serve as placeholders and require further refinement. Please refer to the source code for authoritative information, and feel free to submit corrections or improvements.
Bumper recreates Ecovacs's cloud services locally, so supported robots and apps can work inside your network. The app uses the web API for discovery, accounts, and Wi-Fi onboarding. For live traffic it uses XMPP with older robots and MQTT with newer ones, and a robot speaks exactly one of the two. Robots authenticate and exchange onboarding messages over their live protocol. Supported robots also POST data to the web API over HTTPS.
The app and the robot reach Bumper over TLS. The app connects to mq*.ecouser.net on port 443, and to the
web hosts on 443 as well, so the shipped nginx/Traefik listener reads the SNI: an mq* host goes to the
MQTT broker, every other Ecovacs host goes to the web server. XMPP keeps its own port 5223. The app
provisions a robot with the same 443 broker endpoint; Bumper also listens on 8883 for robots configured
with that port.
flowchart LR
App["Ecovacs app<br/>official client"]
Robots["Ecovacs robots<br/>MQTT or XMPP"]
subgraph Bumper["Bumper"]
direction TB
Web["Web server<br/>REST API 路 NGIoT 路 web UI<br/>HTTPS 443 路 UI 8007"]
XMPP["XMPP server<br/>XML stanzas<br/>5223"]
MQTT["MQTT broker<br/>telemetry 路 commands<br/>plus the helper bot<br/>MQTTS 443 路 8883 路 1883"]
end
DB[("TinyDB<br/>accounts 路 bots 路 clients 路 logs")]
App -->|"HTTPS"| Web
App -->|"XMPP"| XMPP
App -->|"MQTTS"| MQTT
Robots -.->|"HTTP data upload"| Web
Robots -->|"XMPP"| XMPP
Robots -->|"MQTTS"| MQTT
Web <--> DB
XMPP <--> DB
MQTT <--> DB
The app and the robot never talk to each other directly. XMPP stanzas are relayed by Bumper; MQTT telemetry is routed by the broker, and a REST command reaches the robot through the helper bot inside the broker.
馃З Services¶
| Service | Description | Ports | Module Path |
|---|---|---|---|
| Web Server | Handles discovery, login, REST API, and robot uploads | 443, 8007 | bumper.web.server |
| XMPP Server | Relays XML stanzas between client and robot over XMPP | 5223 | bumper.xmpp.xmpp |
| MQTT Broker | Manages MQTT topics for telemetry and commands | 8883, 1883 | bumper.mqtt.server |
馃攼 Account and Authentication¶
Bumper recreates the account and token plumbing the app expects, but it does not verify Ecovacs request signatures. The app logs in with an account name, receives an opaque access token, exchanges an IoT token for an auth code, and then receives OAuth tokens. The same auth code links the account to the XMPP or MQTT transport.
The account key is separate from the TLS key. The private half stays in the data directory, so Bumper can read the fields the app encrypts and no other server can.
One account has several public names, and each app installation has its own client id and resource with its own token row, so parallel installations stay separate. See Authentication for the full flow, the trust model, the ids and alias rules, and the known gaps.
馃寪 Web Server and REST API¶
Bumper's web server simulates the Ecovacs REST API for login and command routing:
- Discovery: the app retrieves the service endpoints from Bumper over HTTPS. Every endpoint mirrors a service the app expects, and the hostname in the answer picks which Bumper service answers. Robots do not use this discovery; they use the server and broker they were provisioned with.
- Robot HTTP uploads: the robot-originated HTTP path observed in Bumper is
/data_collect/upload/generalData(or/api/idi/data_collect/upload/generalData). It accepts map/job documents and camera pictures; Bumper stores them for the app and web UI. This is separate from the app's HTTP requests for account, discovery, and Wi-Fi onboarding flows. - Authentication: the app submits account/login data expected by the Ecovacs flow. Bumper creates/finds local records as needed and returns compatible tokens/codes; the HTTP layer does not verify Ecovacs request signatures.
- Command routing: when the app issues a command (for example, start cleaning), Bumper accepts the request and hands it to the MQTT helper bot, which publishes it to the robot. XMPP robots are controlled by stanzas the app sends through the XMPP server, not through the web API.
- Status queries: the app can poll REST endpoints for state/telemetry that Bumper has stored or relayed.
These paths mirror the patterns the app expects, so the app works unmodified.
馃敆 XMPP Protocol¶
Example Models: Ozmo 601, Ozmo 930
- Discovery
- The REST service list (
/api/appsvr/service/list) names the XMPP service asmsg-eu.<domain>:5223. - DNS resolves that name to Bumper, which listens on
5223.
- The REST service list (
- Connection
- Both robot and app open TLS on port
5223to Bumper's XMPP Server.
- Both robot and app open TLS on port
- Message Relay
- Bumper maintains separate sessions for each side and forwards XML stanzas.
- Commands (e.g., start/stop) and status (e.g., battery) are exchanged as XMPP messages.
- Keep-Alive
- Bumper responds to XMPP pings and sends heartbeats to prevent timeouts.
Tip
The XMPP listener is its own port. It is not part of the 443 SNI split, so the app and the robot
dial msg-eu.<domain>:5223 directly.
鈽侊笍 MQTT Protocol¶
Example Models: Deebot 600, 900, 901, Ozmo 950
- Broker Connection
- Robot connects to Bumper's MQTT Broker on
8883(TLS),1883(plain), or443through the SNI listener, depending on the endpoint it was provisioned with. - The app connects to
mq*.ecouser.net:443. The host is built into the app, not read from the REST service list, so the443listener must route it to the broker by SNI.
- Robot connects to Bumper's MQTT Broker on
- Telemetry Publishing
- Robot publishes JSON status to
iot/atr/<event>/<did>/<class>/<resource>/<payload type>, for example ononStatsandreportStats. - The broker forwards the message to every subscriber, so the app gets live status and Bumper records it.
- Robot publishes JSON status to
- Command Delivery
- App calls a REST endpoint such as
/api/iot/endpoint/control. - Web Server hands the command to the Helper Bot.
- Helper Bot publishes it to
iot/p2p/<command>/<sender did>/<sender class>/<sender resource>/<receiver did>/<receiver class>/<receiver resource>/q/<request id>/<payload type>.
- App calls a REST endpoint such as
- Response Handling
- Robot answers on an
iot/p2p/...topic withpin the request/response position and the same request id. - Helper Bot matches the answer to the waiting request and returns it to the REST call.
- Robot answers on an
鈿欙笍 Helper Bot¶
- An internal MQTT client that bridges REST API calls to MQTT topics.
- Connects to the broker's plain listener on
1883, with a fixed client id that the broker accepts before any other check. - Subscribes to the robot's
iot/atrtelemetry and to theiot/p2preplies addressed to it, so it can keep the bot record current and match an answer to the waiting REST call by message ID.
For further details, see the source modules in
bumper/web/server.py,
bumper/xmpp/xmpp.py, and
bumper/mqtt/server.py.