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

mkdocs

Browse source
This commit is contained in:
Brian Martin 2019-12-31 00:37:23 -05:00
parent 2d39ad60a5
commit a5f114872f
9 changed files with 249 additions and 226 deletions
Download patch file Download diff file Expand all files Collapse all files

128
README.md
View file

@ -8,6 +8,8 @@ Bumper is a standalone and self-hosted implementation of the central server used
**Note:** The current master branch is unstable, and in active development.
## Build Status
| Master Branch | Status |
| ------------------- | ---------------------------------------------------------------------- |
| AppVeyor (Win32) | [![AppVeyor](https://img.shields.io/appveyor/ci/bmartin5692/bumper.svg?logo=appveyor)](https://ci.appveyor.com/project/bmartin5692/bumper) |
@ -18,7 +20,8 @@ Bumper is a standalone and self-hosted implementation of the central server used
**Community**:
A Gitter community has been created for Bumper so users can chat and dig into issues outside of Github, join us here:
[Ecovacs-Bumper on Gitter](https://gitter.im/ecovacs-bumper/community)
[![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 compatability as bumper moves forward! If you've tested Bumper with your bot, please open an issue with details on success or issues.
@ -35,110 +38,6 @@ But seriously, there are a several reasons for eliminating the central server:
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
- An Ecovacs wifi-enabled robot
- A computer on your local network to run the Bumper server
- 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.
- See the docs on [Using Bumper with the official Android/iOS App](docs/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](docs/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](docs/DNS_Setup.md) doc.
**Choose Install:**
- Docker - [See Docker Section](#docker)
- Manual/Python
- 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](docs/Use_With_App.md)
- [Using Bumper with Sucks](docs/Use_With_Sucks.md)
### Starting Bumper
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](docs/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.
#### Command-Line Usage
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:
-h, --help show this help message and exit
--listen LISTEN start serving on address
--announce ANNOUNCE announce address to bots on checkin
--debug enable debug logs
````
#### Environment Variables
Bumper looks for a number of Environment Variables at initialization allowing for customizing a number of settings. For more information see the [Environment Variables](docs/Env_Var.md) doc.
## Docker
### Docker Hub
To download the image from Docker Hub you can run the following:
`docker pull bmartin5692/bumper`
[View Bumper on Docker Hub](https://hub.docker.com/r/bmartin5692/bumper)
### Docker build
To build the docker image yourself you can run the following:
`docker build -t bmartin5692/bumper .`
This requires Docker 17.09 or newer, but has also been tested with podman.
### Docker usage
To run the image in docker some environment settings and port mappings are required:
**Ports Required: (-p)**
- 443 - `-p 443:443`
- 8007 - `-p 8007:8007`
- 8883 - `-p 8883:8883`
- 5223 - `-p 5223:5223`
**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"`
**Volume Settings: (-v)**
Optionally you can map existing directories for logs, data, and certs.
- data/logs/certs
- Data - `-v /home/user/bumper/data:/bumper/data`
**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
````
## 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:
@ -147,24 +46,17 @@ As work to reverse the protocols and provide a self-hosted central server is sti
| --------------- | ------------- | --------------------- | -------------------- |
| Deebot 900/901 | MQTT | master | Ecovacs/Ecovacs Home |
| Deebot 600 | MQTT | master | Ecovacs Home |
| Deebot Ozmo 950 | MQTT | master | Ecovacs Home |
| Deebot Ozmo 601 | XMPP | master | Ecovacs |
| Deebot Ozmo 930 | XMPP | master | Ecovacs |
| Deebot M81 Pro | XMPP | v0.1.0 | Ecovacs |
For more information about the protocols and how Bumper works, see the [How does it work?](docs/How_It_Works.md) page in the docs. If you test against another model and it works, please open an issue to report it.
## Documentation and Getting Started
## Thanks
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.
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 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.
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.
Bumper wouldn't exist without [Sucks](https://github.com/wpietri/sucks), an open source client for Ecovacs robots. Thanks to @wpietri and contributors!

13
docs/CmdLine.md Normal file
View file

@ -0,0 +1,13 @@
# Command-Line Usage
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:
-h, --help show this help message and exit
--listen LISTEN start serving on address
--announce ANNOUNCE announce address to bots on checkin
--debug enable debug logs
````

179
docs/Create_Certs.md
View file

@ -31,6 +31,7 @@ Create_Certs was created to ease creation of certificates specifically for Bumpe
Create_Certs is written in Go which allows cross-platform compiling. If the binaries don't work on your platform, install Go.
With Go installed you can:
* Execute the go code - `go run create_certs/src/create_certs.go`
* Build a new binary for your platform - `go build create_certs/src/create_certs.go`
@ -53,110 +54,120 @@ I get it, you don't trust create_certs and want to do it manually. The easiest
### Create a Root CA
1. Create csrconfig.txt for use in later commands
csrconfig.txt
````
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = Bumper CA
organizationName = Bumper
[ req_ext ]
keyUsage=critical,keyCertSign,cRLSign
basicConstraints=critical,CA:true,pathlen:1
````
***csrconfig.txt***
````
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = Bumper CA
organizationName = Bumper
[ req_ext ]
keyUsage=critical,keyCertSign,cRLSign
basicConstraints=critical,CA:true,pathlen:1
````
1. Create certconfig.txt for use in later commands
certconfig.txt
````
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = Bumper CA
organizationName = Bumper
[ req_ext ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
keyUsage=critical,keyCertSign,cRLSign
basicConstraints=critical,CA:true,pathlen:1
````
***certconfig.txt***
````
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = Bumper CA
organizationName = Bumper
[ req_ext ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
keyUsage=critical,keyCertSign,cRLSign
basicConstraints=critical,CA:true,pathlen:1
````
1. Generate the RSA private key
`openssl genpkey -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out priv.key`
`openssl genpkey -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out priv.key`
1. Create the CSR
`openssl req -new -nodes -key priv.key -config csrconfig.txt -out cert.csr`
`openssl req -new -nodes -key priv.key -config csrconfig.txt -out cert.csr`
1. Self-sign your CSR
`openssl req -x509 -nodes -in cert.csr -days 3650 -key priv.key -config certconfig.txt -extensions req_ext -out cert.crt`
`openssl req -x509 -nodes -in cert.csr -days 3650 -key priv.key -config certconfig.txt -extensions req_ext -out cert.crt`
### Create the Server Certificate
1. Create csrconfig.txt for use in later commands
csrconfig.txt
````
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = Bumper Server
organizationName = Bumper
[ req_ext ]
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth,clientAuth
basicConstraints=critical,CA:false
subjectAltName = @alt_names
[ alt_names ]
DNS.0 = ecovacs.com
DNS.1 = *.ecovacs.com
DNS.2 = ecouser.net
DNS.3 = *.ecouser.net
DNS.4 = ecovacs.net
DNS.5 = *.ecovacs.net
````
***csrconfig.txt***
````
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = Bumper Server
organizationName = Bumper
[ req_ext ]
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth,clientAuth
basicConstraints=critical,CA:false
subjectAltName = @alt_names
[ alt_names ]
DNS.0 = ecovacs.com
DNS.1 = *.ecovacs.com
DNS.2 = ecouser.net
DNS.3 = *.ecouser.net
DNS.4 = ecovacs.net
DNS.5 = *.ecovacs.net
````
1. Create certconfig.txt for use in later commands
certconfig.txt
````
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = Bumper Server
organizationName = Bumper
[ req_ext ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth,clientAuth
basicConstraints=critical,CA:false
subjectAltName = @alt_names
[ alt_names ]
DNS.0 = ecovacs.com
DNS.1 = *.ecovacs.com
DNS.2 = ecouser.net
DNS.3 = *.ecouser.net
DNS.4 = ecovacs.net
DNS.5 = *.ecovacs.net
````
***certconfig.txt***
````
[ req ]
default_md = sha256
prompt = no
req_extensions = req_ext
distinguished_name = req_distinguished_name
[ req_distinguished_name ]
commonName = Bumper Server
organizationName = Bumper
[ req_ext ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
keyUsage=critical,digitalSignature,keyEncipherment
extendedKeyUsage=serverAuth,clientAuth
basicConstraints=critical,CA:false
subjectAltName = @alt_names
[ alt_names ]
DNS.0 = ecovacs.com
DNS.1 = *.ecovacs.com
DNS.2 = ecouser.net
DNS.3 = *.ecouser.net
DNS.4 = ecovacs.net
DNS.5 = *.ecovacs.net
````
1. Generate the RSA private key
`openssl genpkey -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out priv.key`
`openssl genpkey -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out priv.key`
1. Create the CSR
`openssl req -new -nodes -key priv.key -config csrconfig.txt -out cert.csr`
`openssl req -new -nodes -key priv.key -config csrconfig.txt -out cert.csr`
1. Sign your CSR with a root CA cert
`openssl x509 -req -in cert.csr -days 3650 -CA ca.crt -CAkey priv.key -extfile certconfig.txt -extensions req_ext -CAserial /tmp/tmp-10593TSH1OlVSxC7C -CAcreateserial -out cert.crt`
`openssl x509 -req -in cert.csr -days 3650 -CA ca.crt -CAkey priv.key -extfile certconfig.txt -extensions req_ext -CAserial /tmp/tmp-10593TSH1OlVSxC7C -CAcreateserial -out cert.crt`
## Using a Custom CA/Self

6
docs/DNS_Setup.md
View file

@ -5,7 +5,7 @@ The easiest way is overriding the main domains used by EcoVacs using DNSMasq/PiH
## Custom DNSMasq Config
Typically written at /etc/dnsmasq.d/{##}-{name}.conf
- Ex: `/etc/dnsmasq.d/02-custom.conf`
- Ex: `/etc/dnsmasq.d/02-custom.conf`
**File Contents:**
````
@ -16,7 +16,8 @@ address=/ecovacs.net/{bumper server 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
@ -27,6 +28,7 @@ If overriding DNS for the top-level domains isn't an option, you'll need to conf
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.
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".

44
docs/Docker.md Normal file
View file

@ -0,0 +1,44 @@
# Docker Hub
To download the image from Docker Hub you can run the following:
`docker pull bmartin5692/bumper`
[View Bumper on Docker Hub](https://hub.docker.com/r/bmartin5692/bumper)
# Build a Docker image
To build the docker image yourself you can run the following:
`docker build -t bmartin5692/bumper .`
This requires Docker 17.09 or newer, but has also been tested with podman.
# Docker usage
To run the image in docker some environment settings and port mappings are required:
**Ports Required: (-p)**
- 443 - `-p 443:443`
- 8007 - `-p 8007:8007`
- 8883 - `-p 8883:8883`
- 5223 - `-p 5223:5223`
**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"`
**Volume Settings: (-v)**
Optionally you can map existing directories for logs, data, and certs.
- data/logs/certs
- Data - `-v /home/user/bumper/data:/bumper/data`
**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
````

37
docs/Use_With_App.md
View file

@ -25,28 +25,23 @@ Bumper *can* be used with the official "Ecovacs" or "Ecovacs Home" app, but with
### 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)
2. Install the profile by clicking "Install", and entering your pass code if prompted
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)
3. Accept the certificate warning by clicking "Install" again
1. Accept the certificate warning by clicking "Install" again
![Example of cert warning on iOS device](images/ios_cert_warning_install.png)
4. Click "Done" to exit the profile installation
5. Go to Settings > General > About
6. Scroll to the bottom and click "Certificate Trust Settings"
7. Enable Full Trust for the Bumper CA Cert, by moving the slider to the right
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)
8. Click continue when prompted
9. That's it, you can now [Use the app](#use-the-app)
1. Click continue when prompted
1. That's it, you can now [Use the app](#use-the-app)
----
@ -80,17 +75,17 @@ After reboot, verify that the certificate was added by checking `Settings > Secu
**Quick Method**
2. Click the cert, and if prompted provide a name
3. Under "Used for", select "VPN and apps"
1. Click the cert, and if prompted provide a name
1. Under "Used for", select "VPN and apps"
**Long Method**
2. Save the attached cert file
3. Go to Settings > Lock screen and security > Other security settings
4. Under "Credential storage", click "Install from device storage"
5. Browse to the downloaded cert, select it, then click "Done"
6. Click the cert, and if prompted provide a name
7. Under "Used for", select "VPN and apps"
1. Save the attached cert file
1. Go to Settings > Lock screen and security > Other security settings
1. Under "Credential storage", click "Install from device storage"
1. Browse to the downloaded cert, select it, then click "Done"
1. Click the cert, and if prompted provide a name
1. Under "Used for", select "VPN and apps"
Now, start [using the app](#use-the-app).

41
docs/index.md Normal file
View file

@ -0,0 +1,41 @@
# Requirements
- An Ecovacs wifi-enabled robot
- A computer on your local network to run the Bumper server
- 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.
- 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.
## 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.
- 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.
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.

9
docs/origins.md Normal file
View file

@ -0,0 +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.
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.

16
mkdocs.yml Normal file
View file

@ -0,0 +1,16 @@
site_name: Bumper Docs
nav:
- Home: index.md
- How It Works: How_It_Works.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
- Origins: origins.md
theme: readthedocs