Govee (Cloud)

Govee-branded smart lights, light strips, light bars, and smart plugs via the public developer cloud API at developer-api.govee.com. One GEM device per Govee account (API key); each paired Govee device maps to a GEM zone.

Prerequisites

• A Govee Home account with each target device paired in the mobile app.
• Cloud control enabled on each device (default — verify under the device's settings page in the Govee Home app if get_devices returns less than expected).
• A free developer API key. Open the Govee Home app, side menu → About Us → Apply for API Key. The key is emailed within a few minutes.
• Outbound HTTPS to developer-api.govee.com (port 443) from the GEM server.

Setup

1. On the Devices page choose System → Devices → Add Device and pick the driver govee_cloud.
2. Paste the API key into the api_key attribute (marked secure, stored encrypted) and save. On connect the driver fetches the account's device list; once the key is valid the parent device comes up Connected.
3. Run the get_devices command. It returns { devices: [ … ] } with one entry per paired Govee device — {address, name, model, controllable, retrievable, supportCmds}. Note the address value of each device you want to control.
4. For each Govee device, create a zone bound to this device under Zones:
   • Subsystem — a default GEM install ships a Lights subsystem (lights), and this driver hints lights, so the zone editor pre-selects Lights for you. (Re-create it under Subsystems only if it was removed.)
   • Address — paste the address value from get_devices verbatim (e.g. AA:BB:CC:DD:EE:FF:12:34:H6160). The model number is always the final colon-separated segment; don't hand-assemble the string.
   • Optional supports_color / supports_color_tem if you want the UI to expose color / tunable-white controls; the driver dispatches RGB / color-temperature commands regardless of these flags — they are UI hints you set yourself, not auto-detected.
5. (Optional) Adjust status_interval if the account has many zones — see the rate-limit note below.

The driver does not auto-create zones or a subsystem — add one zone per Govee device as above. Each zone is matched to its Govee device by its exact address, so a typo there means the zone never updates or controls.

Attribute Reference

Device attributes

Attribute	Required	Type	Default	Notes
api_key	yes	string (secure)	—	Developer API key issued by Govee. Sent as the Govee-API-Key header on every request.
status_interval	no	int (ms)	30000	How often each zone is polled for state. Keep this ≥ 30000 ms once you have more than ~30 zones on the same key.

Zone attributes

Attribute	Required	Type	Notes
address	yes	string	The device's hardware identifier followed by :<model>, exactly as returned in the address field of get_devices — copy it verbatim. The model number (e.g. H6160, H6072) is always the final colon-separated segment.
supports_color	no	bool	UI hint — does this model accept RGB. Does not gate dispatch; set_color is sent regardless.
supports_color_tem	no	bool	UI hint — does this model accept color temperature. Does not gate dispatch; set_color_tem is sent regardless.

Polled state attributes

Each status poll (and any get_state call) writes the device's current state back onto its zone. Build attribute triggers, UI tiles, and history on these names:

Attribute	Type	Meaning
state	string	on / off.
level	int	Brightness 1–100 (Govee's native scale, written straight through).
red / green / blue	int	Last RGB color, 0–255 each (color-capable models only).
color_tem	int	Color temperature in Kelvin (tunable-white models only).

The driver writes an attribute only when the polled value differs from what the zone already holds, so triggers fire on real changes. Smart-plug models report power only, so just state updates for them.

Commands

Name	Args	Notes
on	address	Power on.
off	address	Power off.
toggle	address	Reads cached state (or fetches if unknown) and inverts.
set_level	address, level (0-100)	Brightness. level <= 0 sends off. Govee's wire scale is 1-100 — the driver rounds and clamps.
set_color	address, red, green, blue (0-255 each)	Requires a model with RGB capability.
set_color_tem	address, color_tem (kelvin)	Range varies by model — typically 2000-9000 K. Out-of-range values come back as HTTP 400.
get_state	address	One-shot state read (power / brightness / color / color_tem).
get_devices	—	Lists every Govee device visible to this API key plus its supportCmds. Use this to populate zone addresses.

Rate limits

Govee enforces 100 requests per minute per API key. The status loop paces itself with an 800 ms gap between zone reads, so a single key comfortably polls up to ~30 zones at the default 30 s interval. If you exceed the limit you'll get HTTP 429 and get_* / set_* calls will surface {error: 'rate limited (429) — raise status_interval'}. Mitigations: raise status_interval, or split zones across two Govee accounts (each with its own key on a separate GEM device).

Known Limitations

• Devices paired LAN-only in the Govee Home app do not appear in the cloud API. The mobile app's "Devices" tab must show them with cloud control enabled.
• State reads can lag the actual device by a few seconds — Govee's cloud cache is the source of truth, not the bulb.
• Effects, scenes, music-react modes, and segment-level control on light strips are not yet exposed through this driver (the developer API only covers turn, brightness, color, colorTem).
• Smart-plug models report powerState only; brightness and color writes are rejected by the API.
• The cloud API does not surface per-device offline state — a missing or errored read is treated as "no change", so a Govee device that drops off Wi-Fi keeps showing its last-known state until it returns. The status poll does not flip the GEM device offline on a failed zone read.
• The parent GEM device's online/offline state is set at connect and re-evaluated only when get_devices runs (at connect, or when you run that command). A full cloud/network outage therefore shows as down the next time get_devices is attempted; individual control commands report their own {error: …} result without changing the device's connection state.

Troubleshooting

Symptom	Likely cause / fix
get_devices returns empty	API key is wrong, OR the paired Govee devices are LAN-only (open the mobile app, turn on cloud control).
HTTP 429	Rate limit hit. Raise status_interval, reduce zone count, or split across additional Govee accounts.
HTTP 401	API key revoked or stale. Re-issue from the Govee Home app and update the attribute.
set_color returns 400 "unsupported command"	This model has no RGB capability. Check supportCmds from get_devices.
set_color_tem returns 400 "invalid value of colorTem"	Value outside the model's supported kelvin range. The supported range is in properties.colorTem.range of the /v1/devices response.
State changes don't show up	Govee's cloud cache lags. The status loop will pick them up on its next pass; raise polling frequency only if you have headroom under the 100 req/min limit.
A Govee device went offline but its zone still shows the old state	Expected — the cloud API does not report per-device offline, and the poll treats a failed read as "no change". Confirm reachability in the Govee Home app; the zone updates on the next successful poll.
A zone never updates or controls	The zone's address does not match a Govee device. Re-run get_devices and paste the address value verbatim — the model is the final colon-separated segment.

Related Documentation

• Zones — creating and binding the per-device zones.
• Subsystems — the Lights subsystem these zones live under.
• Devices — the device editor, secure attributes, and Reload.
• Commands — the command tester used to run get_devices.