From f94cb537e530ea39057b3fa932d3ddb7fb4954d5 Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Wed, 3 Jan 2024 13:13:05 -0700 Subject: [PATCH] add some more docs --- CONFIG.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ DOCKER.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 5 +++++ 3 files changed, 120 insertions(+) create mode 100644 CONFIG.md create mode 100644 DOCKER.md diff --git a/CONFIG.md b/CONFIG.md new file mode 100644 index 0000000..0148f78 --- /dev/null +++ b/CONFIG.md @@ -0,0 +1,60 @@ +# Configuration Options + +## Govee Credentials + +While `govee2mqtt` can run without any govee credentials, it can only discover +and control the devices for which you have already enabled LAN control. + +It is recommended that you configure at least your Govee username and password +prior to your first run, as that is the only way for `govee2mqtt` to determine +room names to pre-assign your lights into the appropriate Home Assistant areas. + +For scene control, at the time of writing, you need a Govee API Key. +If you don't already have one, [you can find instructions on obtaining one +here](https://developer.govee.com/reference/apply-you-govee-api-key). + +|CLI|ENV|AddOn|Purpose| +|---|---|-----|-------| +|`--govee-email`|`GOVEE_EMAIL`|`govee_email`|The email address you registered with your govee account| +|`--govee-password`|`GOVEE_PASSWORD`|`govee_password`|The password you registered for your govee account| +|`--api-key`|`GOVEE_API_KEY`|`govee_api_key`|The API key you requested from Govee support| + +## LAN API Control + +A number of Govee's devices support a local control protocol that doesn't require +your primary internet connection to be online. This offers the lowest latency +for control and is the preferred way for `govee2mqtt` to interact with your +devices. + +The [Govee LAN API is described in more detail +here](https://app-h5.govee.com/user-manual/wlan-guide), including a list of +supported devices. + +*Note that you must use the Govee Home app to enable the LAN API for each +individual device before it will be possible for `govee2mqtt` to control +it via the LAN API.* + +In theory the LAN API is zero-configuration and auto-discovery, but this +relies on your network supporting multicast-UDP, which is challenging +on some networks, especially across wifi access points and routers. + +|CLI|ENV|AddOn|Purpose| +|`--no-multicast`|`GOVEE_LAN_NO_MULTICAST=true`|`no_multicast`|Do not multicast discovery packets to the Govee multicast group `239.255.255.250`. It is not recommended to use this option.| +|`--broadcast-all`|`GOVEE_LAN_BROADCAST_ALL=true`|`broadcast_all`|Enumerate all non-loopback network interfaces and send discovery packets to the broadcast address of each one, individually. This may be a good option if multicast-UDP doesn't work well on your network| +|`--global-broadcast`|`GOVEE_LAN_BROADCAST_GLOBAL=true`|`global_broadcast`|Send discovery packets to the global broadcast address `255.255.255.255`. This may be a possible solution if multicast-UDP doesn't work well on your network.| +|`--scan`|`GOVEE_LAN_SCAN=10.0.0.1,10.0.0.2`|`scan`|Specify a list of addresses that should be scanned by sending them discovery packets. Each element in the list can be an individual IP address (eg: the address of a specific device: be sure to assign it a static IP in your DHCP or other network setup!) or a network broadcast address like `10.0.0.255` for networks that are reachable but not directly plumbed on the machine where `govee2mqtt` is running.| + +## MQTT Configuration + +In order to make your devices appear in Home Assistant, you will need to have configured Home Assistant with an MQTT broker. + + * [follow these steps](https://www.home-assistant.io/integrations/mqtt/#configuration) + +You will also need to configure `govee2mqtt` to use the same broker: + +|CLI|ENV|AddOn|Purpose| +|`--mqtt-host`|`GOVEE_MQTT_HOST`|`mqtt_host`|The host name or IP address of your mqtt broker. This should be the same broker that you have configured in Home Assistant.| +|`--mqtt-port`|`GOVEE_MQTT_PORT`|`mqtt_port`|The port number of the mqtt broker. The default is `1883`| +|`--mqtt-username`|`GOVEE_MQTT_USER`|`mqtt_username`|If your broker requires authentication, the username to use| +|`--mqtt-password`|`GOVEE_MQTT_PASSWORD`|`mqtt_password`|If your broker requires authentication, the password to use| + diff --git a/DOCKER.md b/DOCKER.md new file mode 100644 index 0000000..91ac1d8 --- /dev/null +++ b/DOCKER.md @@ -0,0 +1,55 @@ +# Running govee2mqtt in Docker + +To deploy in docker: + +1. Ensure that you have configured the MQTT integration in Home Assistant. + + * [follow these steps](https://www.home-assistant.io/integrations/mqtt/#configuration) + +2. Set up a `.env` file. Here's a skeleton file; you will need to populate + the values with things that make sense in your environment. + See [CONFIG.md](CONFIG.md) for more details. + +```bash +# Optional, but strongly recommended +GOVEE_EMAIL=user@example.com +GOVEE_PASSWORD=secret +# Optional, but recommended +GOVEE_API_KEY=UUID + +GOVEE_MQTT_HOST=mqtt +GOVEE_MQTT_PORT=1883 +# Uncomment if your mqtt broker requires authentication +#GOVEE_MQTT_USER=user +#GOVEE_MQTT_PASSWORD=password + +# Always use colorized output +RUST_LOG_STYLE=always + +# If you need to debug, uncomment this line +#RUST_LOG=trace + +# Set the timezone for timestamps in the log +TZ=America/Phoenix +``` + +3. Set up your `docker-compose.yml`: + +```yaml +version: '3.8' +services: + pv2mqtt: + image: ghcr.io/wez/govee2mqtt:latest + container_name: govee2mqtt + restart: unless-stopped + env_file: + - .env + # Host networking is required + network_mode: host +``` + +4. Launch it: + +```console +$ docker compose up -d +``` diff --git a/README.md b/README.md index 79e4208..27494a4 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ via the [Home Assistant MQTT Integration](https://www.home-assistant.io/integrat API](https://developer.govee.com/reference/get-you-devices) in case the AWS IoT or LAN control is unavailable. +## Usage + +* [Running it in Docker](DOCKER.md) +* [Configuration](CONFIG.md) + ## Credits This work is based on my earlier work with [Govee LAN