Bumper 🤖¶
Bumper is a self-hosted replacement for Ecovacs cloud services. It lets supported Ecovacs robots and apps talk to a server on your local network, instead of the Ecovacs cloud.
Bumper emulates the web, MQTT, and XMPP services that the official app and robots use. Protocol fidelity matters: the app and robots are unmodified clients, so Bumper aims to match the behavior they expect.
Disclaimer
This project is a work in progress. Behavior varies by robot model, firmware, app version, and region. Check the documentation, Model Compatibility, and logs when troubleshooting.
🧩 How it fits together¶
For Bumper to work, app/robot traffic for Ecovacs domains must reach Bumper, and the client must trust the TLS certificate Bumper presents.
Official app / robot
|
| DNS resolves Ecovacs domains to your Bumper server
v
Bumper (web + MQTT + XMPP)
Bumper's web UI shows server status, connected sessions, registered bots/clients, and clean logs.
🚀 Getting started¶
Start with the step-by-step guide:
- Getting Started Overview - the full setup path, in order.
In short:
- Configure DNS so Ecovacs domains resolve to Bumper.
- Create or provide certificates on the host if you use the checked-in Compose files.
- Deploy Bumper (Docker/Compose is recommended, usually behind nginx or Traefik).
- Connect the official app and make it trust Bumper's CA.
- Use robot Wi-Fi setup only when you need the app's onboarding flow.
👀 What to expect¶
ecovacs.netshows only helperbot: normal when no robot or app client is connected. Robots appear after they connect to Bumper's services with working DNS, reachability/proxy routing, and certificate trust. See Getting Started troubleshooting and What to expect.- Model support is empirical: check Model Compatibility. Some models need certificate/key changes or have known limitations.
- Cloud-only features may be missing: Bumper focuses on local control and the APIs needed for that.
If you are stuck, use Discussions and debug logs
(DEBUG_BUMPER_LEVEL=DEBUG).
📚 Documentation¶
| Section | Purpose |
|---|---|
| Getting Started | DNS, certificates, deployment, app connection, robot onboarding |
| Features | Voice languages, work logs/maps, app updates (CodePush) |
| Configuration | Environment variables |
| Reference | Model reports, error codes |
| Internals | Architecture, auth, sniffing, certificate unpinning |
| Development | Local development, API docs, static data, CI |