Skip to content

James-Tarran/govee-homeassistant

BranchesTags
 
 

Repository files navigation

Govee Logo

Govee Integration for Home Assistant

Your Govee lights + Home Assistant = RGB bliss with real-time control

HACS Custom GitHub Release License

Open in HACS

What's This?

Ever wanted your Govee lights to actually talk to Home Assistant? This integration gives you:

  • Full light control — brightness, RGB colors, color temp, the works
  • Scene magic — your Govee scenes become HA scenes
  • RGBIC segment control — paint each segment a different color OR control all segments together as one
  • Real-time sync — optional MQTT for instant updates (bye-bye polling lag)

Get Started

1. Grab Your API Key

In the Govee Home app: Profile → Settings → Apply for API Key

Check your email in ~5 minutes.

2. Install via HACS

Click the button above, search "Govee", hit Download, restart Home Assistant.

3. Add the Integration

Settings → Devices & Services → Add Integration → Govee

Enter your API key. Want instant updates? Add your Govee email/password for MQTT.

What Works

Device Features
LED Lights & Strips On/off, brightness, RGB, color temp
RGBIC Strips All the above + per-segment colors
Fans On/off, speed (Low/Medium/High), oscillation, preset modes
Heaters On/off, target temperature (16-35°C), fan speed control
Air Purifiers On/off, mode selection (Sleep/Low/High/Custom)
HDMI Sync Boxes On/off, HDMI input selection (1-4)

Note: Cloud-enabled devices only. Bluetooth-only devices need a different integration.

RGBIC Segment Control

For devices with RGB segments (like LED strips), you can choose how to control them globally or per-device:

Segment Control Modes

Mode Use Case
Individual Segments Control each segment separately with different colors (default)
Grouped Segments Control all segments together as a single light — perfect for synchronized effects
Disabled Hide all segment entities if you don't need them

Global vs Per-Device Configuration

You can configure segment control in two ways:

  1. Global Setting — Apply one mode to all RGBIC devices

    • In Configure, set "Global Segment Control Mode"
    • All devices without per-device settings use this mode

  2. Per-Device Settings (NEW) — Different modes for different devices

    • In Configure, select which devices to customize
    • Set individual modes for each device (e.g., strips as individual, spotlights as grouped)
    • Devices not configured per-device fall back to the global setting

How to Configure

To set up segment control:

  1. Go to Settings → Devices & Services → Govee → Configure
  2. Set your Global Segment Control Mode (fallback for all devices)
  3. If you have RGBIC devices, you'll see additional steps:
    • Select which devices to customize with per-device settings
    • Set individual modes for each selected device
  4. Save — entities are automatically created/removed based on your selections

Example scenario:

  • Global mode: Individual segments (default)
  • Customize per-device:
    • LED Strip A (living room): Individual segments
    • LED Strip B (kitchen): Grouped segments (for synced effects)
    • Spotlight (bedroom): Disabled (don't need segment control)

Real-time Updates

Polling is so 2020. Add your Govee account credentials during setup for instant state sync via AWS IoT MQTT.

No credentials? Polling works fine (every 60 seconds by default).

Troubleshooting

Problem Fix
Devices not showing Make sure they're WiFi devices, not Bluetooth-only
Slow updates Enable MQTT or reduce poll interval in options
Rate limit errors Increase poll interval (Govee allows 100 req/min)

Debug Logging

When troubleshooting issues, enable debug logging to capture detailed information about what the integration is doing.

Enable Debug Logging

Option 1: From the Integration (Recommended)

  1. Go to Settings → Devices & Services
  2. Find the Govee integration card
  3. Click the three dots menu (⋮) on the integration card
  4. Select Enable debug logging
  5. Reproduce the issue (turn on a light, trigger the error, etc.)
  6. Return to the integration card, click the three dots menu again
  7. Select Disable debug logging
  8. Your browser will download a log file automatically

Option 2: Via configuration.yaml

For issues during startup or if you need persistent debug logging, add to your configuration.yaml and restart:

logger:
  default: info
  logs:
    custom_components.govee: debug

Viewing Logs

  • Go to Settings → System → Logs
  • Click Load Full Logs to see everything
  • Use the search box to filter for "govee"

See Home Assistant Logger docs for more details.

Gathering Logs for Issues

When opening an issue, include relevant log entries. Here's what to capture:

  1. Enable debug logging (see above)
  2. Reproduce the issue (turn on/off a device, change a scene, etc.)
  3. Copy the relevant log entries

What to include:

  • Logs from when Home Assistant starts (shows device discovery)
  • Logs from when the issue occurs
  • Any error messages or tracebacks

Example log snippet to include:

2024-01-15 10:30:45 DEBUG (MainThread) [custom_components.govee.coordinator] Device: Living Room Light (AA:BB:CC:DD:EE:FF:00:11) type=devices.types.light
2024-01-15 10:30:45 DEBUG (MainThread) [custom_components.govee.coordinator]   Capability: type=devices.capabilities.on_off instance=powerSwitch

Before posting, redact sensitive information:

  • Replace device IDs with XX:XX:XX:XX:XX:XX:XX:XX
  • Remove any email addresses or account IDs

Reporting Issues

When reporting issues with unsupported devices or unexpected behavior, please include your device's API response. This helps us understand your device's capabilities and fix the problem.

Getting Your Device Data

You'll need your Govee API key (the same one you used to set up this integration).

macOS / Linux

Step 1: Open Terminal

  • macOS: Press Cmd + Space, type "Terminal", press Enter
  • Linux: Press Ctrl + Alt + T or search for "Terminal" in your applications

Step 2: Get your device list

Copy this command, replace YOUR_API_KEY with your actual API key, then paste into Terminal and press Enter:

curl -s -H "Govee-API-Key: YOUR_API_KEY" "https://openapi.api.govee.com/router/api/v1/user/devices"

Step 3: Get device state (optional, for more details)

From the output above, find your device's sku (e.g., "H7101") and device ID (e.g., "AA:BB:CC:DD:EE:FF:00:11"), then run:

curl -s -X POST -H "Govee-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"requestId":"test","payload":{"sku":"YOUR_SKU","device":"YOUR_DEVICE_ID"}}' "https://openapi.api.govee.com/router/api/v1/device/state"

Windows

Step 1: Open PowerShell

  • Press Win + X, then click "Windows PowerShell" or "Terminal"
  • Or press Win + R, type powershell, press Enter

Step 2: Get your device list

Copy this command, replace YOUR_API_KEY with your actual API key, then paste into PowerShell and press Enter:

Invoke-RestMethod -Uri "https://openapi.api.govee.com/router/api/v1/user/devices" -Headers @{"Govee-API-Key"="YOUR_API_KEY"} | ConvertTo-Json -Depth 10

Step 3: Get device state (optional, for more details)

From the output above, find your device's sku and device ID, then run (replace the values):

Invoke-RestMethod -Uri "https://openapi.api.govee.com/router/api/v1/device/state" -Method POST -Headers @{"Govee-API-Key"="YOUR_API_KEY"; "Content-Type"="application/json"} -Body '{"requestId":"test","payload":{"sku":"YOUR_SKU","device":"YOUR_DEVICE_ID"}}' | ConvertTo-Json -Depth 10

Posting Your Results

Before posting, redact sensitive information:

  • Replace your API key with REDACTED
  • Replace your email/account ID if visible

Then paste the output in your GitHub issue.

Contributing

PRs welcome! See CONTRIBUTING.md.

License

MIT — see LICENSE.txt

About

Govee Integration for Home Assistant - A HACS custom component for Govee lights and smart devices

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Python 100.0%