Add readme and example config

2025-09-09 03:43:13 -07:00
parent 504edf23e9
commit 08d0fdfc4b
2 changed files with 140 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,136 @@
+# Table of Contents <!-- omit in toc -->
+
+- [Requirements](#requirements)
+- [Obtaining device credentials](#obtaining-device-credentials)
+  - [tl;dr](#tldr)
+  - [Instructions:](#instructions)
+    - [With docker](#with-docker)
+      - [1. Enter a shell within an ubuntu docker container](#1-enter-a-shell-within-an-ubuntu-docker-container)
+      - [2. Set up your environment](#2-set-up-your-environment)
+      - [3. Clone the repo](#3-clone-the-repo)
+      - [4. Install requirements](#4-install-requirements)
+      - [5. Get your credentials](#5-get-your-credentials)
+- [Configuration](#configuration)
+  - [Examples](#examples)
+    - [Config file](#config-file)
+- [Usage](#usage)
+
+
+# eufy_robovac <!-- omit in toc -->
+
+This is a cli script adapted from [Richard Mitchell's work](https://github.com/mitchellrj/eufy_robovac_). It abandons all the code for integrating with homeassistant in lieu of creating a portable binary to control the thing - either manually or with cron job.
+
+# Requirements
+
+- git
+- python 3.12 or higher
+- python-cryptography package
+- docker to compile (alternatively: pipenv and pyinstaller)
+- device credentials
+
+# Obtaining device credentials
+
+## tl;dr
+
+use [this](https://github.com/markbajaj/eufy-device-id-python) repo and follow the instructions.
+
+## Instructions:
+
+You'll need to install git, python3, build-essential, pipenv, libffi-dev, python3-dev, and libssl-dev with your package manager. Then you can do
+
+```
+git clone https://github.com/markbajaj/eufy-device-id-python
+cd eufy-device-id-python
+pipenv install
+pipenv shell
+python -m eufy_local_id_grabber "YOUR_EUFY_EMAIL" "YOUR_EUFY_PASSWORD"
+```
+
+This might not work and requires installing packages you may or may not want/need on your base os. We can do better.
+
+### With docker
+
+#### 1. Enter a shell within an ubuntu docker container
+
+```
+docker run -it ubuntu:latest bash
+```
+
+#### 2. Set up your environment
+
+```
+export DEBIAN_FRONTEND=noninteractive
+apt update
+apt install -y git python3 python3-venv python3-pip build-essential pipenv libffi-dev python3-dev libssl-dev
+```
+
+#### 3. Clone the repo
+
+```
+git clone https://github.com/markbajaj/eufy-device-id-python.git
+cd eufy-device-id-python
+```
+
+#### 4. Install requirements
+
+```
+pipenv install
+```
+
+#### 5. Get your credentials
+
+```
+pipenv shell
+python -m eufy_local_id_grabber "YOUR_EUFY_EMAIL" "YOUR_EUFY_PASSWORD"
+```
+
+Output:
+
+```
+Home: <home ID>
+Device: RoboVac, device ID <DEVICE_ID>, local key <LOCAL_KEY>
+```
+
+# Configuration
+
+The device ID, ip address, and local code are required for this to work. They may be passed as arguments, or through a config file. The defalt path for the config file is `/etc/robovac.conf`. This can be altered with the `-c` or `--config` flags.
+
+## Examples
+
+[example config](config/robovac.conf.example)
+
+- arbitrary config file: `robovac --config=/home/user/robovac.conf`
+- argments: `robovac --device_id=DEVICE_ID --ip=192.168.1.1 --local_code=LOCAL_CODE`
+
+### Config file
+
+```
+[robovac]
+device_id=DEVICE_ID
+ip=192.168.1.1
+local_code=LOCAL_CODE
+```
+
+# Usage
+
+```
+usage: vac [-h] [-c CONFIG] [--device_id DEVICE_ID] [--ip IP] [--local_code LOCAL_CODE] [--time TIME] [--pause] [--home] [--debug] [--verbose] [--quiet]
+
+Control a Robovac device.
+
+options:
+  -h, --help            show this help message and exit
+  -c CONFIG, --config CONFIG
+                        Path to config file
+  --device_id DEVICE_ID
+                        Device ID
+  --ip IP               Device IP address
+  --local_code LOCAL_CODE
+                        Secret key obtained from eufy
+  --time TIME, -t TIME  Cleaning time in minutes
+  --pause, -p           Pause vacuum
+  --home, -b            Go home
+  --debug, -d           Enter debugging mode (won't send commands to vacuum)
+  --verbose, -v         Enable verbose logs
+  --quiet, -q           Quiet logs
+```
--- a/config/robovac.conf.example
+++ b/config/robovac.conf.example
@@ -0,0 +1,4 @@
+[robovac]
+device_id=DEVICE_ID
+ip=192.168.1.1
+local_code=LOCAL_CODE