Skip to content
MVladislavPublic
forked from edenhaus/bumper

About

A standalone and self-hosted implementation of the central server used by Ecovacs vacuum robots.

Resources

Code of conduct

Security policy

Stars

108 stars

Watchers

1 watching

Forks

 
 

Latest commit

 

History

832 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bumper

License GPLv3 CI Status CodeQL Codecov pre-commit.ci status Release Docker Release Drafter

Bumper is a self-hosted central server for Ecovacs robots, including DEEBOT vacuums and GOAT mowers. It replaces the Ecovacs cloud, giving you full local control through a privacy-first, high-performance stack: Python + uv, Docker Swarm, and NGINX.

Web-UI Preview

🔑 Key Features

  • Self-Hosted: Operate without Ecovacs cloud servers.
  • Privacy-First: All data stays within your network.
  • High Performance: Python 3.13+ (3.15 by default) with asyncio, aiohttp, slixmpp, and amqtt; uv keeps the environment and lockfile reproducible.
  • Docker Swarm & Compose: One-command startup with turnkey NGINX configuration.
  • Modular: Easily extend protocols and add integrations.

⚠️ Warning: Branches main/dev are under active development and may be unstable. Use at your own risk.


🚀 Quickstart

🔧 Prerequisites

TLS certificates:

The checked-in Compose/Swarm files load certificates from $PWD/certs/* as read-only Docker configs, so create and install them before deployment:

bash scripts/certs/create-cert.sh
# add --rsa if your robot requires RSA keys

Use the generated certs/ca.crt on the app and clients; Certificates covers key types, SANs, and startup generation.

Environment variables:

Create a .env file with at least the following:

# 'overlay' for Docker Swarm, 'bridge' for plain Docker Compose
NETWORK_MODE=overlay

# required by the Compose file
BUMPER_ANNOUNCE_IP=192.168.0.100  # your server's local IP

Full configuration options are available in the Environment Variables.

✨ Docker Swarm Deployment

Step 1 - Clone the repository

git clone https://github.com/MVladislav/bumper.git
cd bumper

Step 2 - Initiate Docker in Swarm mode

docker swarm init

Step 3 - Start services

# Docker Swarm: pulls ghcr.io/mvladislav/bumper (tag from VERSION_BUMPER, default "latest")
docker-swarm-compose deebot

# or plain Docker Compose: builds the image from this checkout
docker compose up -d

Step 4 - Open the UI

Visit https://ecovacs.net/ in your browser.


📖 Documentation

In-depth guides and architecture details are available in the docs/ folder or online:


🔄 Compatibility

🤖 Supported Robots

See Model Compatibility for reported working models, known limitations, and cases that still need verification.

📱 Supported Apps

The official Ecovacs app works with Bumper once it is patched, and the patch is not tied to an app version anymore - there is no version table to keep. See Mobile App Integration and Certificate Pinning Bypass (APP).


👥 Community

Join our Gitter channel to discuss features, report issues, and share setups:

Gitter chat

Or use the GitHub Discussions section for longer conversations and proposals.


🤝 Contributing

Contributions are welcome! To get started:

  1. Fork the repo and create a feature branch.

  2. Run the checks CI runs:

    uv run --active prek run --all-files
    uv run --active pytest tests
  3. Submit a pull request against main.

See the Development Guide for the full setup and each linter.


🧪 Testing Needed

Bumper relies on community testing for broader device coverage. If you test Bumper with your robot, please open a discussion with:

  • classid and model (from the app, or match the name in bumper/web/static_api/productIotMap.json)
  • Firmware version
  • Protocol used (MQTT / XMPP / NGIoT)
  • Whether the app works, or only a client such as deebot-client
  • Success or failure details, with DEBUG_BUMPER_LEVEL=DEBUG logs

The confirmed models are tracked on the Model Compatibility page.


📜 License

Released under the GPLv3 License.


🗂 References


🙏 Thanks

Special thanks to:

  • @torbjornaxelsson for the original Bumper implementation.
  • @wpietri and contributors of Sucks for the open-source Ecovacs client.
  • All community members who test and contribute to making Bumper better.

Originally forked from edenhaus/bumper (via bmartin5692) · Maintained by @MVladislav

About

A standalone and self-hosted implementation of the central server used by Ecovacs vacuum robots.

Resources

Code of conduct

Security policy

Stars

108 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages