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 central cloud services locally, so your robots and app work seamlessly within your network. It supports both XMPP and MQTT protocols.
🧩 Services
| Service | Description | Ports | Module Path |
|---|---|---|---|
| Web Server | Handles discovery, login, REST API for commands and status | 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 | 1883, 8883 | bumper.mqtt.server |
🔒 App / 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 three public ids: A for the account, U for the unified
identity, and I for the IoT session. Each app installation has a client id
and resource (K/R), with its own token row. A BumperUser owns its app
devices, while every local account receives the shared robot inventory; legacy
ids are aliases on that same record. This keeps parallel app clients separate
without creating duplicate accounts.
See Authentication for the full flow, the trust model, and the known gaps.
🔒 Login / Authentication / REST API
Bumper’s Web Server module simulates the Ecovacs REST API for login and command routing:
- Discovery: Robots and the mobile app retrieve service endpoints (XMPP broker or MQTT server addresses) via HTTPS requests to the discovery URL exposed on ports 443/8007.
- Authentication: The app submits account data; a normal login creates or finds the local account and returns an access token, while a session check resolves the existing account by the app device. Later calls name the account with that token or with a user id. The HTTP layer does not verify request signatures.
- Command Routing: When the app issues a command (for example, start cleaning), it makes a REST call against Bumper’s web service. The request is enqueued and handed off to the MQTT helper or forwarded to the XMPP server, depending on the robot’s protocol.
- Status Queries: The app can poll for the robot’s latest state via REST endpoints, which query the latest telemetry stored by Bumper.
These paths mirror the patterns the app expects, so the app works unmodified.
🔗 XMPP Protocol
Example Models: Ozmo 601, Ozmo 930
- Discovery
- Robot and app request XMPP server info from
/discover. - Bumper returns its own hostname/IP for XMPP.
- Robot and app request XMPP server info from
- 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 Ecovacs app attempts XMPP first; if no valid messages, it falls back to MQTT models.
☁️ MQTT Protocol
Example Models: Deebot 600, 900, 901, Ozmo 950
- Broker Connection
- Robot connects to Bumper’s MQTT Broker on
8883(TLS) or1883(plain). - Subscribes to
p2p/<device_id>for incoming commands.
- Robot connects to Bumper’s MQTT Broker on
- Telemetry Publishing
- Robot publishes JSON status (battery, location) to
attr/<device_id>at intervals.
- Robot publishes JSON status (battery, location) to
- Command Delivery
- App issues
POST /api/commandto Web Server. - Web Server forwards the command to the Helper Bot.
- Helper Bot publishes the command to
p2p/<device_id>.
- App issues
- Response Handling
- Robot executes the command and publishes results back to
p2p/<device_id>orrsp/<device_id>. - Helper Bot stores responses and makes them available via REST for the app.
- Robot executes the command and publishes results back to
⚙️ Helper Bot
- An internal MQTT client that bridges REST API calls to MQTT topics.
- Connects with a fixed client id that the broker accepts before any other check.
- Correlates request/response pairs by message ID for REST replies.
For further details, see the source modules in bumper/web/server.py, bumper/xmpp/xmpp.py, and bumper/mqtt/server.py.
