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

bash

uv pip install -e .

Configuration

Set your device MAC in config.yml:

yaml

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

Or use environment variable:

bash

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

Or pass -m flag to each command.

Commands

Scan for devices

bash

govee scan

Returns list of Govee devices with MAC addresses.

Power control

bash

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

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

Set color

bash

# 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

bash

govee brightness 50   # 0-100%

Device Configuration Priority

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

Python API

python

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

bash

govee on
govee color warm
govee brightness 30

Alert/notification flash

bash

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

Gradual wake-up light

bash

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