Govee to MQTT

Govee2MQTT is designed to keep your data local. No usage data or device information is sent to the maintainers. All data remains on your device, with the exception of data required by Govee's cloud servers (AWS) to control your devices.

Key Privacy Points:

• Credentials: Any credentials configured in govee2mqtt are used exclusively for authentication with Govee's cloud servers.
• Local Caching: To prevent hitting Govee API rate limits, information regarding your Govee device list and their configurations is cached locally on your filesystem.

Control over device segments is subject to the limitations of the Govee API and the specific hardware:

• Power State: The Govee API for segments only supports brightness and color, not power state. While Home Assistant shows a power control for segments (as it assumes all lights have one), clicking it will do nothing.
• Control Flexibility: Govee to MQTT acts as a bridge; it cannot override device-specific behaviors. For example, some devices may not allow setting a segment brightness to 0, or may bind segment brightness to the overall light brightness.

Govee devices with the LAN protocol enabled listen for discovery packets on UDP port 4001. They participate in the multicast group 239.255.255.250.

Because multicast-UDP is often poorly supported by routers (especially on Wi-Fi), Govee2MQTT provides alternative discovery methods to bypass multicast issues:

1. Direct IP Scanning: You can specify a list of IP addresses to which discovery packets are sent directly (unicast).
2. UDP Broadcast Variations: You can enable options that use standard UDP broadcasts instead of multicast.

For a device to be successfully discovered and usable, UDP ports 4001 and 4003 must be reachable from the Govee2MQTT instance.

Because the Govee API does not return video effects, they are not automatically listed in Home Assistant. To make them available, you must create a workaround using the Govee Home App:

1. In the Govee Home App, create either a "Tap-to-Run" shortcut or a saved "Snapshot" that activates the desired video effect.
2. In Home Assistant, navigate to the "Govee to MQTT" device within the MQTT integration.
3. Click the "Purge Caches" button.

Results:

• Tap-to-Run shortcuts will be mapped as Scene entities in Home Assistant.
• Snapshots will appear in the list of Effects on the device itself.

Depending on your Home Assistant setup, use one of the following methods to install the bridge:

• Home Assistant Add-On: For HAOS and Supervised HASS users. See docs/ADDON.md.
• Docker: For users running Home Assistant in containers. See docs/DOCKER.md.
• Configuration: To set up your credentials and device settings. See docs/CONFIG.md.

To use the Govee LAN API via Govee2MQTT, the following network and device requirements must be met:

Device Requirements

• Enable LAN API: Each Govee device must have its LAN API access enabled manually within the settings of the Govee Home App.
• Open Ports: UDP ports 4001 and 4003 must be reachable on each Govee device.

Govee2MQTT Requirements

• UDP Port Binding: Govee2MQTT must be able to bind to UDP port 4002 on the host machine.
• Network Routing: Your network must allow UDP replies to route back to Govee2MQTT. Note that while Govee devices respond to the source IP of the packets, they will use UDP port 4002 instead of the originating port for the reply.

By default, govee2mqtt uses a Docker volume to persist data. If you prefer to mount the data directory directly to a specific path on your host machine, add a volumes section to your docker-compose.yml service definition.

# Example volume mounting
services:
  govee2mqtt:
    # ... other config ...
    volumes:
      - '/path/to/data:/data'

To deploy govee2mqtt in Docker, follow these steps:

1. Configure MQTT: Ensure the MQTT integration is already configured in Home Assistant.
2. Create a .env file: Populate a .env file with your environment-specific values (see the environment variables section for details).
3. Configure docker-compose.yml: Create a compose file using the ghcr.io/wez/govee2mqtt:latest image. Note: network_mode: host is required.
4. Launch: Run docker compose up -d to start the container in detached mode.
5. Monitor: Use docker logs govee2mqtt --follow to view real-time logs.

name: govee2mqtt
services:
  govee2mqtt:
    image: ghcr.io/wez/govee2mqtt:latest
    container_name: govee2mqtt
    restart: unless-stopped
    env_file:
      - .env
    # Host networking is required
    network_mode: host

To make Govee devices appear in Home Assistant, govee2mqtt must be configured to connect to the same MQTT broker used by your Home Assistant instance.

Use the following options to specify your broker connection details: