Govee

Introduction

This tool provides a CLI and Python API to control Govee LED lights. It communicates directly with the device over Bluetooth, requiring no cloud connection or Govee account.

Prerequisites

Linux system with Bluetooth adapter
BlueZ installed (bluez, bluez-utils)
Python 3.10+ with bleak library
Device MAC address (obtain via govee scan)

Installation

uv pip install -e .

Configuration

Set your device MAC in config.yml:

device: "C5:37:32:32:2C:43"

Or use environment variable:

export GOVEE_DEVICE="C5:37:32:32:2C:43"

Or pass -m flag to each command.

Commands

Scan for devices

govee scan

Returns list of Govee devices with MAC addresses.

Power control

govee on    # Turn light on
govee off   # Turn light off

# Or with explicit MAC:
govee -m <MAC> on
govee -m <MAC> off

Set color

# By name
govee color red
govee color blue
govee color warm

# By hex code
govee color "#FF5500"
govee color 00FF00

# By RGB values
govee rgb 255 128 0

Available color names: red, green, blue, white, yellow, cyan, magenta, purple, orange, pink, warm, cool

Set brightness

govee brightness 50   # 0-100%

Device Configuration Priority

-m / --mac command line flag
GOVEE_DEVICE environment variable
device field in config.yml

Python API

import asyncio
from govee import GoveeDevice

async def control_light():
    async with GoveeDevice("C5:37:32:32:2C:43") as device:
        await device.power_on()
        await device.set_color("red")
        await device.set_brightness(50)
        await device.set_rgb(255, 128, 0)
        await device.power_off()

asyncio.run(control_light())

Example Workflows

Set ambient lighting for movie watching

govee on
govee color warm
govee brightness 30

Alert/notification flash

govee color red
sleep 0.5
govee color blue
sleep 0.5
govee color red

Gradual wake-up light

govee on
govee color warm
for i in 10 20 30 40 50 60 70 80 90 100; do
  govee brightness $i
  sleep 60
done

Known Limitations

Only one Bluetooth connection at a time (disconnect Govee app first)
Device must be powered on and in range (~10m)
Some RGBIC features (segments, scenes) not fully implemented
Connection may take 2-5 seconds

Troubleshooting

| Issue | Solution | |-------|----------| | Device not found | Run govee scan, ensure light is powered on | | Connection timeout | Power cycle the light, close Govee phone app | | Commands fail silently | Light may be off; run govee on first | | Permission denied | Run with sudo or add user to bluetooth group |

Device Compatibility

Verified:

Govee H6046 RGBIC TV Light Bars

Likely compatible (untested):

Govee H6102, H6072 (same MODE_1501 protocol)
Other Govee RGBIC devices

File Locations

CLI source: src/govee/cli.py
Device library: src/govee/device.py
Command builders: src/govee/commands.py
Protocol spec: docs/SPEC.md
Config file: config.yml