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

1. -m / --mac command line flag
2. GOVEE_DEVICE environment variable
3. 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

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