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

run prettier

Browse source
This commit is contained in:
Robert Resch 2022-03-03 14:10:50 +01:00
parent 1e2d87efda
commit 2f7c7e1aa8
20 changed files with 227 additions and 218 deletions
Download patch file Download diff file Expand all files Collapse all files

19
.github/ISSUE_TEMPLATE/bug_report.md vendored
View file

@ -1,10 +1,9 @@
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''
title: ""
labels: ""
assignees: ""
---
**Describe the bug**
@ -12,6 +11,7 @@ A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
@ -24,14 +24,17 @@ A clear and concise description of what you expected to happen.
If applicable, add screenshots to help explain your problem.
**Desktop (please complete the following information):**
- OS: [e.g. Linux/Mac/Windows]
- OS: [e.g. Linux/Mac/Windows]
**Smartphone (please complete the following information):**
- Device: [e.g. iPhone6]
- OS: [e.g. iOS8.1]
- Device: [e.g. iPhone6]
- OS: [e.g. iOS8.1]
**Vacuum (please complete the following information):**
- Model: [e.g. Deebot 901]
- Model: [e.g. Deebot 901]
**Additional context**
Add any other context about the problem here.

7
.github/ISSUE_TEMPLATE/feature_request.md vendored
View file

@ -1,10 +1,9 @@
---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''
title: ""
labels: ""
assignees: ""
---
**Is your feature request related to a problem? Please describe.**

1
.github/workflows/docker-images.yml vendored
View file

@ -33,7 +33,6 @@ jobs:
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1
- name: Login to docker hub
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin

1
.pre-commit-config.yaml
View file

@ -86,4 +86,3 @@ repos:
types: [python]
require_serial: true
<<: *python-files

26
CODE_OF_CONDUCT.md
View file

@ -14,22 +14,22 @@ appearance, race, religion, or sexual identity and orientation.
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
- The use of sexualized language or imagery and unwelcome sexual attention or
advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic
address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities

32
README.md
View file

@ -1,8 +1,8 @@
![License GPLv3](https://img.shields.io/github/license/bmartin5692/bumper.svg?color=brightgreen)
# Bumper
# Bumper
Bumper is a standalone and self-hosted implementation of the central server used by Ecovacs vacuum robots. Bumper allows you to have full control of your Ecovacs robots, without the robots or app talking to the Ecovacs servers and transmitting data outside of your home.
Bumper is a standalone and self-hosted implementation of the central server used by Ecovacs vacuum robots. Bumper allows you to have full control of your Ecovacs robots, without the robots or app talking to the Ecovacs servers and transmitting data outside of your home.
![Bumper Diagram](./docs/images/BumperDiagram.png "Bumper Diagram")
@ -10,23 +10,21 @@ Bumper is a standalone and self-hosted implementation of the central server used
## Build Status
| Master Branch | Status |
| ------------------- | ---------------------------------------------------------------------- |
| AppVeyor (Win32) | [![AppVeyor branch](https://img.shields.io/appveyor/ci/bmartin5692/bumper/master?logo=appveyor)](https://ci.appveyor.com/project/bmartin5692/bumper/branch/master) |
| TravisCI (Linux) | [![Travis (.org) branch](https://img.shields.io/travis/bmartin5692/bumper/master?logo=travis)](https://travis-ci.com/bmartin5692/bumper/branch/master) |
| Docker Hub | [![Docker Build](https://img.shields.io/docker/cloud/build/bmartin5692/bumper?logo=docker)](https://hub.docker.com/r/bmartin5692/bumper/branch/master) |
| CodeCov Coverage | [![Codecov branch](https://img.shields.io/codecov/c/github/bmartin5692/bumper/master?logo=codecov)](https://codecov.io/gh/bmartin5692/bumper/branch/master) |
| Master Branch | Status |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AppVeyor (Win32) | [![AppVeyor branch](https://img.shields.io/appveyor/ci/bmartin5692/bumper/master?logo=appveyor)](https://ci.appveyor.com/project/bmartin5692/bumper/branch/master) |
| TravisCI (Linux) | [![Travis (.org) branch](https://img.shields.io/travis/bmartin5692/bumper/master?logo=travis)](https://travis-ci.com/bmartin5692/bumper/branch/master) |
| Docker Hub | [![Docker Build](https://img.shields.io/docker/cloud/build/bmartin5692/bumper?logo=docker)](https://hub.docker.com/r/bmartin5692/bumper/branch/master) |
| CodeCov Coverage | [![Codecov branch](https://img.shields.io/codecov/c/github/bmartin5692/bumper/master?logo=codecov)](https://codecov.io/gh/bmartin5692/bumper/branch/master) |
**Community**:
A Gitter community has been created for Bumper so users can chat and dig into issues outside of Github, join us here:
[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/ecovacs-bumper/community)
**_Testing needed_**
Bumper needs users to assist with testing in order to ensure compatibility as bumper moves forward! If you've tested Bumper with your bot, please open an issue with details on success or issues.
***Testing needed***
Bumper needs users to assist with testing in order to ensure compatibility as bumper moves forward! If you've tested Bumper with your bot, please open an issue with details on success or issues.
***Please note**: this software is experimental and not ready for production use. Use at your own risk.*
**\*Please note**: this software is experimental and not ready for production use. Use at your own risk.\*
## Why?
@ -37,10 +35,10 @@ But seriously, there are a several reasons for eliminating 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.
## 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 that it hasn't been tested against. Bumper should be compatible with most wifi-enabled robots that use either the Ecovacs Android/iOS app or the Ecovacs Home Android/iOS app, but has only been reported to work on the below:
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 that it hasn't been tested against. Bumper should be compatible with most wifi-enabled robots that use either the Ecovacs Android/iOS app or the Ecovacs Home Android/iOS app, but has only been reported to work on the below:
| Model | Protocol Used | Bumper Version Tested | EcoVacs App Tested |
| --------------- | ------------- | --------------------- | -------------------- |
@ -56,7 +54,9 @@ As work to reverse the protocols and provide a self-hosted central server is sti
See the documentation on [Read the Docs](https://bumper.readthedocs.io)
---
### Thanks
A big thanks to the original project creator @torbjornaxelsson, without his work this project would have taken much longer to build.
A big thanks to the original project creator @torbjornaxelsson, without his work this project would have taken much longer to build.
Bumper wouldn't exist without [Sucks](https://github.com/wpietri/sucks), an open source client for Ecovacs robots. Thanks to @wpietri and contributors!

4
docs/CmdLine.md
View file

@ -2,7 +2,7 @@
Bumper has a number of available command-line arguments that can be viewed by adding the `-h` flag.
````
```
usage: bumper [-h] [--listen LISTEN] [--announce ANNOUNCE] [--debug]
optional arguments:
@ -10,4 +10,4 @@ optional arguments:
--listen LISTEN start serving on address
--announce ANNOUNCE announce address to bots on checkin
--debug enable debug logs
````
```

72
docs/Create_Certs.md
View file

@ -1,31 +1,32 @@
# Creating Certs
Bumper requires specially crafted certificates to work properly. In the spirit of security, Bumper will not ship with default certificates. Users will need to generate and provide their own certificates.
Bumper requires specially crafted certificates to work properly. In the spirit of security, Bumper will not ship with default certificates. Users will need to generate and provide their own certificates.
Certificates should be placed in the `{bumper_home}/certs` directory. If certificates are located elsewhere [environment variables](Env_Var.md) can be set that point to their location.
Certificates should be placed in the `{bumper_home}/certs` directory. If certificates are located elsewhere [environment variables](Env_Var.md) can be set that point to their location.
Users can generate certificates in the following ways:
| Method | Description |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [OpenSSL](#manually-create-certs-with-openssl) | Users can manually create the same certificates as Create_Certs by utilizing OpenSSL. |
| [Custom CA/Self](#using-a-custom-caself) | If a user has their own CA the certificates can be generated there and used within Bumper. |
| Method | Description |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [OpenSSL](#manually-create-certs-with-openssl) | Users can manually create the same certificates as Create_Certs by utilizing OpenSSL. |
| [Custom CA/Self](#using-a-custom-caself) | If a user has their own CA the certificates can be generated there and used within Bumper. |
**Certificate Requirements:**
* A CA Cert must be provided that can be imported into devices (phones, browsers, etc).
* Server certificate should include [SANs (Subject Alternate Names)](#subject-alternative-name) for all of the *.ecovacs, etc domains.
- A CA Cert must be provided that can be imported into devices (phones, browsers, etc).
- Server certificate should include [SANs (Subject Alternate Names)](#subject-alternative-name) for all of the \*.ecovacs, etc domains.
## Manually create certs with OpenSSL
The easiest way to create the required certs is at https://certificatetools.com/. In fact the below OpenSSL commands come straight from that site, post creation via the GUI.
The easiest way to create the required certs is at https://certificatetools.com/. In fact the below OpenSSL commands come straight from that site, post creation via the GUI.
### Create a Root CA
1. Create csrconfig_ca.txt for use in later commands
***csrconfig_ca.txt***
````
**_csrconfig_ca.txt_**
```
[ req ]
default_md = sha256
prompt = no
@ -37,12 +38,13 @@ organizationName = Bumper
[ req_ext ]
keyUsage=critical,keyCertSign,cRLSign
basicConstraints=critical,CA:true,pathlen:1
````
```
1. Create certconfig_ca.txt for use in later commands
***certconfig_ca.txt***
````
**_certconfig_ca.txt_**
```
[ req ]
default_md = sha256
prompt = no
@ -56,26 +58,27 @@ subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
keyUsage=critical,keyCertSign,cRLSign
basicConstraints=critical,CA:true,pathlen:1
````
```
1. Generate the RSA private key
`openssl genrsa -out ca.key 4096`
1. Generate the RSA private key
`openssl genrsa -out ca.key 4096`
1. Create the CSR
`openssl req -new -nodes -key ca.key -config csrconfig_ca.txt -out ca.csr`
`openssl req -new -nodes -key ca.key -config csrconfig_ca.txt -out ca.csr`
1. Self-sign your CSR
`openssl req -x509 -nodes -in ca.csr -days 1095 -key ca.key -config certconfig_ca.txt -extensions req_ext -out ca.crt`
`openssl req -x509 -nodes -in ca.csr -days 1095 -key ca.key -config certconfig_ca.txt -extensions req_ext -out ca.crt`
### Create the Server Certificate
1. Create csrconfig_bumper.txt for use in later commands
***csrconfig_bumper.txt***
````
**_csrconfig_bumper.txt_**
```
[ req ]
default_md = sha256
prompt = no
@ -100,12 +103,13 @@ DNS.6 = *.ww.ecouser.net
DNS.7 = *.dc-eu.ww.ecouser.net
DNS.8 = *.dc.ww.ecouser.net
DNS.9 = *.area.ww.ecouser.net
````
```
1. Create certconfig_bumper.txt for use in later commands
***certconfig_bumper.txt***
````
**_certconfig_bumper.txt_**
```
[ req ]
default_md = sha256
prompt = no
@ -132,20 +136,20 @@ DNS.6 = *.ww.ecouser.net
DNS.7 = *.dc-eu.ww.ecouser.net
DNS.8 = *.dc.ww.ecouser.net
DNS.9 = *.area.ww.ecouser.net
````
```
1. Generate the RSA private key
`openssl genrsa -out bumper.key 4096`
`openssl genrsa -out bumper.key 4096`
1. Create the CSR
`openssl req -new -nodes -key bumper.key -config csrconfig_bumper.txt -out bumper.csr`
`openssl req -new -nodes -key bumper.key -config csrconfig_bumper.txt -out bumper.csr`
1. Sign your CSR with a root CA cert
`openssl x509 -req -in bumper.csr -days 365 -CA ca.crt -CAkey ca.key -extfile certconfig_bumper.txt -extensions req_ext -CAcreateserial -out bumper.crt`
`openssl x509 -req -in bumper.csr -days 365 -CA ca.crt -CAkey ca.key -extfile certconfig_bumper.txt -extensions req_ext -CAcreateserial -out bumper.crt`
## Using a Custom CA/Self
This should work siimilar to the OpenSSL method. Ensure the server certificate has the proper SANs (see above) in place.
This should work siimilar to the OpenSSL method. Ensure the server certificate has the proper SANs (see above) in place.

97
docs/DNS_Setup.md
View file

@ -1,71 +1,74 @@
# 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.
## Custom DNSMasq Config
Typically written at /etc/dnsmasq.d/{##}-{name}.conf
- Ex: `/etc/dnsmasq.d/02-custom.conf`
Typically written at /etc/dnsmasq.d/{##}-{name}.conf
- Ex: `/etc/dnsmasq.d/02-custom.conf`
**File Contents:**
````
```
address=/ecouser.net/{bumper server ip}
address=/ecovacs.com/{bumper server ip}
address=/ecovacs.net/{bumper server ip}
````
**Note:** *Replace `{bumper server ip}` with your server's IP*
```
**Note:** _Replace `{bumper server ip}` with your server's IP_
If using PiHole, reload FTL to apply changes:
`sudo service pihole-FTL reload`
`sudo service pihole-FTL reload`
## Manual Override
If overriding DNS for the top-level domains 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 overriding DNS for the top-level domains 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.
**Note:** Depending on country, your phone/robot may be using a different domain. Most of these domains contain country-specific placeholders.
**Note:** Depending on country, your phone/robot may be using a different domain. Most of these domains contain country-specific placeholders.
Not all domains have been documented at this point, and this list will be updated as more are identified/seen. The preferred way to ensure Bumper works is to override the full domains as above.
**Note:** The app dynamically gets the required domains from the endpoint `api/appsvr/service/list` and therefore ecovacs can use different domains for different models.
Replacement Examples:
- {countrycode}
- If you see `eco-{countrycode}-api.ecovacs.com` and you live in the US/North America you would use: `eco-us-api.ecovacs.com`
- **Note**: {countrycode} may also be generalized regions such as "EU".
- {region}
- If you see `portal-{region}.ecouser.net` and you live in the US/North America you would use: `portal-na.ecouser.net`
- **Note**: {region} may also be generalized regions such as "EU".
- {countrycode}
- If you see `eco-{countrycode}-api.ecovacs.com` and you live in the US/North America you would use: `eco-us-api.ecovacs.com`
- **Note**: {countrycode} may also be generalized regions such as "EU".
- {region}
- If you see `portal-{region}.ecouser.net` and you live in the US/North America you would use: `portal-na.ecouser.net`
- **Note**: {region} may also be generalized regions such as "EU".
| Address | Description |
| --------------------------------------- | ---------------------------------------------- |
| `lb-{countrycode}.ecovacs.net` | Load-balancer that is checked by the app/robot |
| `lb-{countrycode}.ecouser.net` | Load-balancer that is checked by the app/robot |
| `lbus.ecouser.net` | Load-balancer that is checked by the app/robot |
| `lb{countrycode}.ecouser.net` | Load-balancer that is checked by the app/robot |
| `eco-{countrycode}-api.ecovacs.com` | Used for Login |
| `gl-{countrycode}-api.ecovacs.com` | Used by EcoVacs Home app |
| `gl-{countrycode}-openapi.ecovacs.com` | Used by EcoVacs Home app |
| `portal.ecouser.net` | Used for Login and Rest API |
| `portal-{countrycode}.ecouser.net` | Used for Login and Rest API |
| `portal-{region}.ecouser.net` | Used for Login and Rest API |
| `portal-ww.ecouser.net` | Used for various Rest APIs |
| `msg-{countrycode}.ecouser.net` | Used for XMPP |
| `msg-{region}.ecouser.net` | Used for XMPP |
| `msg-ww.ecouser.net` | Used for XMPP |
| `mq-{countrycode}.ecouser.net` | Used for MQTT |
| `mq-{region}.ecouser.net` | Used for MQTT |
| `mq-ww.ecouser.net` | Used for MQTT |
| `gl-{countrycode}-api.ecovacs.com` | Used by Ecovacs Home app for API |
| `recommender.ecovacs.com` | Used by Ecovacs Home app |
| `bigdata-international.ecovacs.com` | Telemetry/tracking |
| `bigdata-northamerica.ecovacs.com` | Telemetry/tracking |
| `bigdata-europe.ecovacs.com` | Telemetry/tracking |
| `bigdata-{unknown regions}.ecovacs.com` | Telemetry/tracking |
| `api-app.ww.ecouser.net` | Api for App (v2+) |
| `api-app.dc-{region}.ww.ecouser.net` | Api for App (v2+) |
| `users-base.dc-{region}.ww.ecouser.net` | Accounts for App (v2+) |
| `jmq-ngiot-{region}.dc.ww.ecouser.net` | MQTT for App (v2+) |
| `api-rop.dc-{region}.ww.ecouser.net` | App (v2+) |
| `jmq-ngiot-{region}.area.ww.ecouser.net`| App (v2+) |
| Address | Description |
| ---------------------------------------- | ---------------------------------------------- |
| `lb-{countrycode}.ecovacs.net` | Load-balancer that is checked by the app/robot |
| `lb-{countrycode}.ecouser.net` | Load-balancer that is checked by the app/robot |
| `lbus.ecouser.net` | Load-balancer that is checked by the app/robot |
| `lb{countrycode}.ecouser.net` | Load-balancer that is checked by the app/robot |
| `eco-{countrycode}-api.ecovacs.com` | Used for Login |
| `gl-{countrycode}-api.ecovacs.com` | Used by EcoVacs Home app |
| `gl-{countrycode}-openapi.ecovacs.com` | Used by EcoVacs Home app |
| `portal.ecouser.net` | Used for Login and Rest API |
| `portal-{countrycode}.ecouser.net` | Used for Login and Rest API |
| `portal-{region}.ecouser.net` | Used for Login and Rest API |
| `portal-ww.ecouser.net` | Used for various Rest APIs |
| `msg-{countrycode}.ecouser.net` | Used for XMPP |
| `msg-{region}.ecouser.net` | Used for XMPP |
| `msg-ww.ecouser.net` | Used for XMPP |
| `mq-{countrycode}.ecouser.net` | Used for MQTT |
| `mq-{region}.ecouser.net` | Used for MQTT |
| `mq-ww.ecouser.net` | Used for MQTT |
| `gl-{countrycode}-api.ecovacs.com` | Used by Ecovacs Home app for API |
| `recommender.ecovacs.com` | Used by Ecovacs Home app |
| `bigdata-international.ecovacs.com` | Telemetry/tracking |
| `bigdata-northamerica.ecovacs.com` | Telemetry/tracking |
| `bigdata-europe.ecovacs.com` | Telemetry/tracking |
| `bigdata-{unknown regions}.ecovacs.com` | Telemetry/tracking |
| `api-app.ww.ecouser.net` | Api for App (v2+) |
| `api-app.dc-{region}.ww.ecouser.net` | Api for App (v2+) |
| `users-base.dc-{region}.ww.ecouser.net` | Accounts for App (v2+) |
| `jmq-ngiot-{region}.dc.ww.ecouser.net` | MQTT for App (v2+) |
| `api-rop.dc-{region}.ww.ecouser.net` | App (v2+) |
| `jmq-ngiot-{region}.area.ww.ecouser.net` | App (v2+) |

6
docs/Develop.md
View file

@ -1,4 +1,5 @@
# Developing
To start developing and contributing, install in dev mode.
`pipenv install --dev`
@ -8,16 +9,17 @@ Review the [How It Works](How_It_Works.md) doc to understand the basics and then
As features and functions are added, be sure to add tests to keep the test coverage high.
# Testing
Bumper uses pytest for the majority of test cases, review current tests in the /tests directory.
### Running tests
Enter pipenv shell `pipenv shell`
**Run tests**
- `python -m pytest tests`
**Run tests with coverage**
- `python -m pytest --cov=./ tests`
@ -25,4 +27,4 @@ Enter pipenv shell `pipenv shell`
**Run tests with coverage html report**
- `python -m pytest --cov=./ tests --cov-report html:tests/report`
- The report will be output into tests/report/index.html for further analysis.
- The report will be output into tests/report/index.html for further analysis.

9
docs/Docker.md
View file

@ -27,8 +27,8 @@ To run the image in docker some environment settings and port mappings are requi
**Environment Settings: (-e)**
`BUMPER_ANNOUNCE_IP` should be used so the actual host IP is reported to bots that checkin.
- BUMPER_ANNOUNCE_IP - `-e "BUMPER_ANNOUNCE_IP=X.X.X.X"`
- BUMPER_ANNOUNCE_IP - `-e "BUMPER_ANNOUNCE_IP=X.X.X.X"`
**Volume Settings: (-v)**
@ -39,15 +39,16 @@ Optionally you can map existing directories for logs, data, and certs.
**Full Example:**
````
```
docker run -it -e "BUMPER_ANNOUNCE_IP=X.X.X.X" -p 443:443 -p 8007:8007 -p 8883:8883 -p 5223:5223 -v /home/user/bumper/data:/bumper/data --name bumper bmartin5692/bumper
````
```
# Docker-compose
A docker-compose example can be found in the ["example" folder](https://github.com/bmartin5692/bumper/tree/master/example/docker-compose).
The docker-compose starts two services:
- bumper itself
- nginx proxy, which redirects MQTT traffic on port `443` to port `8883`

24
docs/Env_Var.md
View file

@ -1,15 +1,15 @@
# Environment Variables
Bumper has a number of environment variables to help with custom deployments and configuration. These should be set prior to executing Bumper.
Bumper has a number of environment variables to help with custom deployments and configuration. These should be set prior to executing Bumper.
| Setting | Value | Description |
| ------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| BUMPER_LISTEN | {ipv4 address} | IP address to start server listeners on |
| BUMPER_ANNOUNCE_IP | {ipv4 address} | IP address to tell bots when they request the server location. May need to be set in cases such as when LISTEN is 0.0.0.0. |
| BUMPER_CA | {full path to ca.crt location} | The public CA certificate (ca.crt) to be loaded |
| BUMPER_CERT | {full path to bumper.crt location} | The public server certificate (bumper.crt) to be used by the Bumper server |
| BUMPER_KEY | {full path to bumper.key location} | The private server key (bumper.key) to be used by the Bumper server |
| BUMPER_LOGS | {full path to logs directory} | The directory where logs should be stored |
| BUMPER_DATA | {full path to data directory} | The directory where persistent data should be stored (bumper.db) |
| BUMPER_DEBUG | true | Run Bumper with debug mode/logging |
| LOG_TO_STDOUT | true | Instead of logging to logs/, logs to to STDOUT |
| Setting | Value | Description |
| ------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| BUMPER_LISTEN | {ipv4 address} | IP address to start server listeners on |
| BUMPER_ANNOUNCE_IP | {ipv4 address} | IP address to tell bots when they request the server location. May need to be set in cases such as when LISTEN is 0.0.0.0. |
| BUMPER_CA | {full path to ca.crt location} | The public CA certificate (ca.crt) to be loaded |
| BUMPER_CERT | {full path to bumper.crt location} | The public server certificate (bumper.crt) to be used by the Bumper server |
| BUMPER_KEY | {full path to bumper.key location} | The private server key (bumper.key) to be used by the Bumper server |
| BUMPER_LOGS | {full path to logs directory} | The directory where logs should be stored |
| BUMPER_DATA | {full path to data directory} | The directory where persistent data should be stored (bumper.db) |
| BUMPER_DEBUG | true | Run Bumper with debug mode/logging |
| LOG_TO_STDOUT | true | Instead of logging to logs/, logs to to STDOUT |

36
docs/How_It_Works.md
View file

@ -1,4 +1,4 @@
# How does Bumper work?
# How does Bumper work?
![Bumper Diagram](./images/BumperDiagram.png "Bumper Diagram")
@ -14,51 +14,51 @@ Bumper runs multiple services to re-create what the central EcoVacs servers prov
**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 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.
**Robots**
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.
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.
----
---
### Login/Authentication/RestAPI
***Bumper*** provides a fully simulated central server that handles login/authentication for the app/clients.
**_Bumper_** provides a fully simulated central server that handles login/authentication for the app/clients.
The EcoVacs app encrypts the username/password with the public key of EcoVacs when authenticating. Since we don't have the private key to decrypt, there is no way to provide true security and authentication.
The EcoVacs app encrypts the username/password with the public key of EcoVacs when authenticating. Since we don't have the private key to decrypt, there is no way to provide true security and authentication.
Future versions may add additional options here for security.
Bots have no authentication and once a robot has been configured to access your WiFi it never needs to communicate with EcoVac's servers again.
----
---
### XMPP
*Example Model:* Ozmo 601/930
_Example Model:_ Ozmo 601/930
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.
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.
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.
**_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.
**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 600/900/901
_Example Model:_ Deebot 600/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 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`.
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.
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.
**_Bumper_** provides a simulated RestAPI and "helper" bot, performing the same function as the central server above.

15
docs/Sniffing.md
View file

@ -1,7 +1,7 @@
Reverse engineering the protocols and default apps/APIs requires some patience and work. I've found using a Kali Linux VM that hosts an access point with MitMProxy works well. I followed a number of articles in order to get started, which helped in creating the below VM setup and scripts.
Reverse engineering the protocols and default apps/APIs requires some patience and work. I've found using a Kali Linux VM that hosts an access point with MitMProxy works well. I followed a number of articles in order to get started, which helped in creating the below VM setup and scripts.
> References:
>
>
> - https://blog.heckel.xyz/2013/07/01/how-to-use-mitmproxy-to-read-and-modify-https-traffic-of-your-phone/
> - https://docs.mitmproxy.org/stable/howto-wireshark-tls/
> - https://www.yeahhub.com/create-fake-ap-dnsmasq-hostapd-kali-linux/
@ -80,13 +80,11 @@ Run Start_Sniff.sh to begin. Ensure the bot and apps connect via the Wifi networ
- For XMPP/MQTT you will need to use WireShark.
- Ensure you point WireShark at the sslmitmkeylog file in order to decrypt any encrypted communications.
This documentation won't go into the details of reviewing the logs/traffic. The reader will need to identify how to use WireShark etc for this.
This documentation won't go into the details of reviewing the logs/traffic. The reader will need to identify how to use WireShark etc for this.
## XMPPPeek - MITM XMPP traffic between the Android or iOS App and the Ecovacs server
###### *Stolen from the [Sucks Documentation](https://github.com/wpietri/sucks/blob/master/developing.md#mitm-xmpp-traffic-between-the-android-or-ios-app-and-the-ecovacs-server)*
###### _Stolen from the [Sucks Documentation](https://github.com/wpietri/sucks/blob/master/developing.md#mitm-xmpp-traffic-between-the-android-or-ios-app-and-the-ecovacs-server)_
XMPPPeek can also be used to man in the middle the traffic between the Android/iOS App and the Ecovacs server.
@ -100,10 +98,9 @@ XMPPPeek can also be used to man in the middle the traffic between the Android/i
1. Look at the [DNS docs](DNS_Setup.md) for information on which Ecovacs XMPP server is the right one for your Country. For example, a US user will be using `msg-na.ecouser.net`. Find and note the IP address for the server.
1. Make sure the mobile App talks to your machine instead of the server. This can be
accomplished modifying your router's DNS configuration to have the Ecovacs domain
name point to your IP.
accomplished modifying your router's DNS configuration to have the Ecovacs domain
name point to your IP.
1. Run xmppeek as follows.
`python ./xmpppeek.py <ECOVACS XMPP SERVER IP> cert.pem key.pem`

32
docs/Use_With_App.md
View file

@ -1,6 +1,6 @@
# Using Bumper with the official Android/iOS App
# Using Bumper with the official Android/iOS App
Bumper *can* be used with the official "Ecovacs" or "Ecovacs Home" 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.
Bumper _can_ be used with the official "Ecovacs" or "Ecovacs Home" 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.
**Steps**
@ -17,33 +17,33 @@ Bumper *can* be used with the official "Ecovacs" or "Ecovacs Home" app, but with
![Example of emailing CA cert](images/emailcert.png)
- Import the cert as a CA, and trust it
- Instructions for [iOS](#importing-the-ca-cert-on-ios)
- Instruction for [Android](#importing-the-ca-cert-on-android)
- Instructions for [iOS](#importing-the-ca-cert-on-ios)
- Instruction for [Android](#importing-the-ca-cert-on-android)
----
---
### Importing the CA Cert on iOS
1. Open the e-mail on your iOS device, and click the attached cert
![Example of email on iOS device](images/ios_email_cert.png)
![Example of email on iOS device](images/ios_email_cert.png)
1. Install the profile by clicking "Install", and entering your pass code if prompted
![Example of install profile on iOS device](images/ios_install_profile.png)
![Example of install profile on iOS device](images/ios_install_profile.png)
1. Accept the certificate warning by clicking "Install" again
![Example of cert warning on iOS device](images/ios_cert_warning_install.png)
![Example of cert warning on iOS device](images/ios_cert_warning_install.png)
1. Click "Done" to exit the profile installation
1. Go to Settings > General > About
1. Scroll to the bottom and click "Certificate Trust Settings"
1. Enable Full Trust for the Bumper CA Cert, by moving the slider to the right
![Example of enable trust cert on iOS device](images/ios_cert_trust.png)
![Example of enable trust cert on iOS device 2](images/ios_cert_trust_continue.png)
![Example of enable trust cert on iOS device](images/ios_cert_trust.png)
![Example of enable trust cert on iOS device 2](images/ios_cert_trust_continue.png)
1. Click continue when prompted
1. That's it, you can now [Use the app](#use-the-app)
----
---
### Importing the CA Cert on Android
@ -89,11 +89,11 @@ After reboot, verify that the certificate was added by checking `Settings > Secu
Now, start [using the app](#use-the-app).
----
---
### Use the app
- Open the app
- At this time there is no authentication layer, you can enter any e-mail 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
- Open the app
- At this time there is no authentication layer, you can enter any e-mail 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

2
docs/Use_With_Sucks.md
View file

@ -1,6 +1,6 @@
# Using Bumper with Sucks
At this time you'll need to use the bmartin5692 fork of sucks. Especially if you have a newer bot like an Ozmo.
At this time you'll need to use the bmartin5692 fork of sucks. Especially if you have a newer bot like an Ozmo.
- Download and install [Sucks](https://github.com/bmartin5692/sucks)

32
docs/index.md
View file

@ -5,43 +5,45 @@
- Python 3.7 and pipenv OR Docker
- A network router that has functionality for overriding DNS queries
- A client that can connect to Bumper and talk to the robot over the Ecovacs protocol.
- The "Ecovacs" or "Ecovacs Home" Android or iOS apps can be used if configured properly.
- The "Ecovacs" or "Ecovacs Home" Android or iOS apps can be used if configured properly.
- See the docs on [Using Bumper with the official Android/iOS App](Use_With_App.md).
- [Sucks](https://github.com/wpietri/sucks) can also be used, which can act as a client and control the robots via command-line.
- See the doc on [Using Bumper with Sucks](Use_With_Sucks.md)
# Quick Start Usage
- Configure your Ecovacs vacuum using the official mobile app (if you haven't done this already)
- Configure your DNS server as described in the [DNS Setup](DNS_Setup.md) doc.
- Configure your Ecovacs vacuum using the official mobile app (if you haven't done this already)
- Configure your DNS server as described in the [DNS Setup](DNS_Setup.md) doc.
## Choose Installation Type
- Docker - [See Docker Details](Docker.md)
- Manual/Python
- Download bumper then run `pipenv install` to install dependencies
- Start bumper - see the [Starting Bumper](#starting-bumper) section.
- Docker - [See Docker Details](Docker.md)
- Manual/Python
- Control your robots like normal
- [Using Bumper with the official Android/iOS App](Use_With_App.md)
- [Using Bumper with Sucks](Use_With_Sucks.md)
- Download bumper then run `pipenv install` to install dependencies
- Start bumper - see the [Starting Bumper](#starting-bumper) section.
- Control your robots like normal
- [Using Bumper with the official Android/iOS App](Use_With_App.md)
- [Using Bumper with Sucks](Use_With_Sucks.md)
# Starting Bumper
Bumper requires certificates to function. If certificates aren't found it will prompt to generate them for you.
Bumper requires certificates to function. If certificates aren't found it will prompt to generate them for you.
For more information on generating certificates manually, see the [Creating Certs](Create_Certs.md) doc
- Start Bumper with `pipenv run python -m bumper`
- If prompted to generate certificates choose yes or no
- Reboot your robot
- **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 within about 30 seconds. Bumper will output information about the connection status.
- **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 within about 30 seconds. Bumper will output information about the connection status.
# Troubleshooting
Logs are output in the /logs directory.
If there is an issue, enable debug logging with the `--debug` switch for additional detail.
If there is an issue, enable debug logging with the `--debug` switch for additional detail.

6
docs/origins.md
View file

@ -1,9 +1,9 @@
### Bumper Origins
@torbjornaxelsson created Bumper originally in 2017 and the project reached its original goal and remained in a stable, but stale state with the last commit in Dec 2017.
@torbjornaxelsson created Bumper originally in 2017 and the project reached its original goal and remained in a stable, but stale state with the last commit in Dec 2017.
Since the original release of Bumper newer bots have been released that use different protocols, and in early 2019 it was decided that @bmartin5692 would take over development moving forward. This fork was detached and all future development of bumper will take place here.
Since the original release of Bumper newer bots have been released that use different protocols, and in early 2019 it was decided that @bmartin5692 would take over development moving forward. This fork was detached and all future development of bumper will take place here.
#### Archive
The original bumper code base has been branched off as [v0.1.0](https://github.com/bmartin5692/bumper/tree/v0.1.0) and will remain in the original state. This branch *may* work for older models (M81 Pro, N79S, etc.), but the master branch should be tried first as it contains many changes and fixes over the original with active development moving forward.
The original bumper code base has been branched off as [v0.1.0](https://github.com/bmartin5692/bumper/tree/v0.1.0) and will remain in the original state. This branch _may_ work for older models (M81 Pro, N79S, etc.), but the master branch should be tried first as it contains many changes and fixes over the original with active development moving forward.

2
example/docker-compose/docker-compose.yaml
View file

@ -42,4 +42,4 @@ services:
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
- ./config:/bumper/data
- ./certs:/bumper/certs
- ./certs:/bumper/certs

22
mkdocs.yml
View file

@ -1,19 +1,19 @@
site_name: Bumper Docs
nav:
- Home: index.md
- Using:
- "Command-Line": CmdLine.md
- "Docker": Docker.md
- "Using with Apps": Use_With_App.md
- "Using with Sucks": Use_With_Sucks.md
- Using:
- "Command-Line": CmdLine.md
- "Docker": Docker.md
- "Using with Apps": Use_With_App.md
- "Using with Sucks": Use_With_Sucks.md
- Certs: Create_Certs.md
- DNS: DNS_Setup.md
- Configuration:
- "Environment Variables": Env_Var.md
- Configuration:
- "Environment Variables": Env_Var.md
- Developing:
- "Reversing The Protocols": Sniffing.md
- "Developing and Testing": Develop.md
- "How It Works": How_It_Works.md
- "Reversing The Protocols": Sniffing.md
- "Developing and Testing": Develop.md
- "How It Works": How_It_Works.md
- Origins: origins.md
theme: readthedocs
theme: readthedocs