mia/bumper
1
0
Fork 0
Code Issues 47 Pull requests 11 Projects Releases Packages Wiki Activity Actions

D901 #2

Merged
bmartin5692 merged 34 commits from D901 into dev 2019-02-22 05:37:44 +01:00
Conversation 0 Commits 34 Files changed 31 +87 -65
1 changed files with 87 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit d8ce4bdfd0 - Show all commits

154
README.md
View file

@ -1,109 +1,131 @@
Bumper
=====
A standalone implementation of the central server used by Ecovacs
Deebot cleaning robots to relay data between the robot and client.
Tested on Ecovacs Deebot M81 Pro but should be compatible with # Bumper
most wifi-enabled robots that use the Ecovacs Android app. A standalone implementation of the central server used by Ecovacs Deebot cleaning robots to relay data between the robot and client.
*Please note: this software is experimental and not ready *Please note: this software is experimental and not ready for production use. Use at your own risk.*
for production use. Use at your own risk.*
## Compatibility
As work to reverse the protocols and provide a self-hosted central server is still in progress, Bumper has had limited testing. There are a number of EcoVacs models and varying protocols that it hasn't been tested against. So far two different protocols have been seen, **XMPP** and **MQTT**. Bumper should be compatible with most wifi-enabled robots that use the Ecovacs Android app, but has only been reported to work on the below:
| Model | Protocol Used |
|--|--|
| Deebot M81 Pro | XMPP |
| Deebot 900/901 | MQTT |
For more information about the protocols and how it works, see the "**How does it work?**" section at the end. If you test against another model and it works, please report it so it can be added to the list.
## Why? ## Why?
For fun, mostly :) For fun, mostly :)
But seriously, there are a serveral reasons for But seriously, there are a several reasons for eliminating the central server:
elminating the central server:
1. Convenience: It works without an internet connection or if
Ecovacs servers are down
2. Performance: No need for messages to travel to Ecovacs server
and back.
3. Security: We can completely isolate the robot from the public
Internet.
1. Convenience: It works without an internet connection or if Ecovacs servers are down
2. Performance: No need for messages to travel to Ecovacs server and back.
3. Security: We can completely isolate the robot from the public Internet.
## Requirements ## Requirements
- An Ecovacs wifi-enabled robot - An Ecovacs wifi-enabled robot
- A computer on your local network to run the Bumper server - A computer on your local network to run the Bumper server
- Python 3 and pipenv - Python 3 and pipenv
- A network router that has functionality for overriding DNS queries - A network router that has functionality for overriding DNS queries
- A client that can connect to Bumper and talk to the robot over the - A client that can connect to Bumper and talk to the robot over the Ecovacs protocol.
Ecovacs protocol. - The Android or iOS apps can be used if configured properly. See "**Using with the official Android/iOS App**" below.
I recomend [Sucks](https://github.com/wpietri/sucks). - [Sucks](https://github.com/wpietri/sucks) can also be used, which can act as a client and control the robots via command-line.
It can run on the same computer and requires only minimal modification
to work with Bumper.
## Usage ## Usage
- Run `pipenv install` to install dependencies
- Configure your Ecovacs vacuum using the official mobile app (if you haven't done this already)
### DNS
You need to configure your router to point DNS locally to where Bumper is running.
The easiest way is overriding the main domains used by EcoVacs using DNSMasq/PiHole, by adding address entries in a custom config:
- Run `pipenv install` to install dependencies address=/ecouser.net/{bumper server ip}
address=/ecovacs.com/{bumper server ip}
- Configure your Ecovacs vacuum using the official mobile app If this isn't an option, you'll need to configure your router DNS to point a number of domains used by the app/robot to the Bumper server.
(if you haven't done this already) **Note:** Depending on country, your phone may be using a different domain. Most of these domains contain country-specific placeholders.
- Example: If you see `eco-{countrycode}-api.ecovacs.com` and you live in the US/North America you would use: `eco-us-api.ecovacs.com`
- Configure your router DNS to point the domain lbo.ecovacs.net to | Address | Description |
the machine that will run the Bumper server |--|--|
| `lbo.ecovacs.net` | Load-balancer that is checked by the app/robot |
| `eco-{countrycode}-api.ecovacs.com` | Used for Login |
| `portal-{countrycode}.ecouser.net` | Used for Login and Rest API |
| `msg-{countrycode}.ecouser.net` | Used for XMPP |
| `mq-{countrycode}.ecovacs.com` | Used for MQTT |
### Starting Bumper
- Start Bumper with `pipenv run python bumper.py` - Start Bumper with `pipenv run python bumper.py`
- Reboot your robot (remove and re-insert the battery pack, - Reboot your robot
then power it on) - **Note:** Some models may require removing and re-inserting the battery pack.
- This doesn't seem to be required for models that don't have easily accessible batteries such as the 900/901.
- If your configuration is correct, the robot will connect to Bumper - If your configuration is correct, the robot will connect to Bumper within about 30 seconds. Bumper will output information about the connection status.
within about 30 seconds. Bumper will output informaiton about the
connection status.
- Configure your client - see below. - Configure your client - see below.
## Using with Sucks ## Using with Sucks
Instructions (verified to work with Sucks 0.8.3) Instructions (verified to work with Sucks 0.8.3)
- Download and install [Sucks](https://github.com/wpietri/sucks) - Download and install [Sucks](https://github.com/wpietri/sucks)
- See the [example script](examples/sucks.py) for how to connect - See the [example script](examples/sucks.py) for how to connect
## Using with the official Android/iOS App ## Using with the official Android/iOS App
Bumper *can* be used with the official app, but with limitations. Your phone needs to use your DNS server with custom settings, and you ***must*** import Bumper's CA cert and trust it before the app will work.
### DNS
- Configure your DNS server as described above in the DNS section.
### Import the Bumper CA Cert
- E-mail yourself the Bumper CA cert (located at `./certs/CA/cacert.pem`)
- Import the cert as a CA, and trust it
- Instructions here are different for iPhone vs Android
Bumper *can* be used with the official app, but with limitations. Your ### Use the app
phone needs to use your DNS server with custom settings, and the app
authenticates via Ecovacs central servers every time you start it.
- Configure your DNS server to point the domains msg-na.ecouser.net and
msg-ww.ecouser.net to the machine running Bumpy. Note: Depending on
country, your phone may be using a different domain.
- Login to the app. It will authenticate and ask for a list of robots
from Ecovacs central servers.
- The app will now connect to Bumper and try to ping the robot. Bumper
responds to this ping to tell the app that the robot is online.
- You should now be able to control the robot from the app.
- Open the app
- At this time there is no authentication layer, you can enter any email address and password (as long as it is 6 characters) and you will be authenticated
- If your robot has already checked into Bumper, then it will be available in the list of robots
- The app now does a ping to the robot to make sure it is online, and if it is you can now control the robot
## How does it work? ## How does it work?
**App/Authentication**
EcoVacs servers provide authentication of accounts and match those up to registered robots. Once authenticated, users can control the robots via the app. ***Bumper*** provides an implementation of the central servers providing authentication and matching.
Ecovacs robots communicate over the XMPP (jabber) protocol. Messages **Robots**
are relayed by a central XMPP server. So far two protocols have been identified that various models of EcoVacs robots use: **XMPP** and **MQTT**. These appear to be mutually exclusive and your robot model will use one of these two protocols for communication. ***Bumper*** provides an implementation of both protocols handling communication between the app and robots.
Bumper exposes a simulated XMPP server that implements the nessecary ----
functions for relaying messages between a robot and a client. **Login/Authentication/RestAPI**
***Bumper*** provides a fully simulated central server that handles login/authentication for the app/clients. At this time no authentication layer is implemented and you can use any e-mail/password when logging in. Future versions should add additional options here for security.
When the robot boots up it sends a HTTP request to lbo.ecovacs.net:8007 This means however, that once a robot has been configured to access your WiFi it never needs to communicate with EcoVac's servers again.
asking for the IP address and port of the XMPP server. Because of our
DNS override, this request will be received by Bumper. We tell the robot
to connect over XMPP to our local machine. Voilá!
----
**XMPP**
*Example Model:* Deebot M81 Pro
The robot utilizes XMPP for control. When the robot boots up it sends a HTTP request to `lbo.ecovacs.net:8007` asking for the IP address and port of the XMPP server. Because of our DNS override, this request will be received by Bumper. We tell the robot to connect over XMPP to our local machine.
Both the app and robot connect to the central XMPP server, which relays messages between the app and robot. The messages contain commands for the robot to execute or responses and statuses of the robot.
***Bumper*** exposes a simulated XMPP server that implements the necessary functions for relaying messages between a robot and a client, acting as the central server.
**Note:** It's been observed that the apps will attempt to utilize XMPP regardless of robot model. For models that utilize MQTT, no activity is performed over XMPP just pings.
----
**MQTT**
*Example Model:* Deebot 900/901
The robot utilizes MQTT for control. On startup it connects to an MQTT broker (`mq-{countrycode}.ecovacs.com`) and subscribes to a `p2p` topic where commands are issued.
The app also connects to the MQTT broker and subscribes to a `attr` topic where the robot will periodically post status and location updates.
The app receives status updates, for example battery status or robot position information, periodically via the `attr` topic.
However, commands issued via the app/client are not published directly to the `p2p` topic that the robot subscribes to. When the app sends a command such as "Clean", this is sent via a Rest API to the server at `portal-{countrycode}.ecouser.net`.
The Rest API provided by `portal-{countrycode}.ecouser.net` receives the command and passes it to a "helper" bot that has permission to publish to the `p2p` topic the robot is subscribed to. The "helper" bot waits for a response to be published by the robot and then passes that response back to the server for the Rest API to send back as a response.
***Bumper*** provides a simulated RestAPI and "helper" bot, performing the same function as the central server above.
## Thanks ## Thanks
Bumper wouldn't exist without [Sucks](https://github.com/wpietri/sucks), an open source client for Ecovacs robots. Big thanks to @wpietri and contributors!
Bumper woulden't exist without [Sucks](https://github.com/wpietri/sucks),
an open source client for Ecovacs robots. Big thanks to @wpietri and
contributors!