Elixir client for the Govee Developer API.

This module is the main entry point for interacting with Govee devices. It provides functions to:

• list devices associated with your account
• retrieve the current state of a device
• send control commands (power, brightness, color, temperature)

All data returned by this module is converted into domain structs (GoveeLights.Device and GoveeLights.Device.State) instead of raw API maps.

Authentication

You must provide a Govee API key, either as an environment variable:

export GOVEE_API_KEY="your_api_key"

or via application configuration:

config :govee_lights, api_key: "your_api_key"

You can request an API key from Govee at: https://developer.govee.com/reference/apply-you-govee-api-key

Devices

Retrieve all devices linked to your account:

iex> {:ok, devices} = GoveeLights.Api.devices()
iex> Enum.all?(devices, &match?(%GoveeLights.Device{}, &1))
true

Each device contains basic metadata and a normalized state field.

Device state

Fetch the current state of a device by its identifier and model:

iex> {:ok, state} =
...>   GoveeLights.Api.device_state("AA:BB:CC:DD:EE:FF:11:22", "H6008")
iex> state.on
true
iex> state.brightness
10
iex> state.color
%{r: 36, g: 242, b: 156}

The returned value is a %GoveeLights.Device.State{} struct with normalized fields. Missing information is represented as :unknown.

Device control

Send commands to a device using its identifier and model.

Turn a device on or off:

iex> GoveeLights.Api.turn_on("AA:BB:CC:DD:EE:FF:11:22", "H6008")
{:ok, :updated}

iex> GoveeLights.Api.turn_off("AA:BB:CC:DD:EE:FF:11:22", "H6008")
{:ok, :updated}

Set brightness (0–100):

iex> GoveeLights.Api.set_brightness("AA:BB:CC:DD:EE:FF:11:22", "H6008", 25)
{:ok, :updated}

Set color temperature (Kelvin):

iex> GoveeLights.Api.set_temperature("AA:BB:CC:DD:EE:FF:11:22", "H6008", 2700)
{:ok, :updated}

Set RGB color:

iex> GoveeLights.Api.set_color(
...>   "AA:BB:CC:DD:EE:FF:11:22",
...>   "H6008",
...>   %{r: 255, g: 0, b: 0}
...> )
{:ok, :updated}

Bang functions

For convenience, most functions also have a bang (!) variant that returns the successful value directly or raises GoveeLights.Api.Error on failure.

Example:

iex> state =
...>   GoveeLights.Api.device_state!(
...>     "AA:BB:CC:DD:EE:FF:11:22",
...>     "H6008"
...>   )
iex> state.on
true

Errors

Non-bang functions return structured error tuples:

• {:http_error, reason} – network or HTTP client failure
• {:decode_error, data} – unexpected API response shape
• {:device_error, raw, reason} – invalid device payload
• {:state_error, raw, reason} – invalid state payload
• {:command_failed, command, value, code, message} – API rejected a command
• {:invalid_command, command, value} – invalid command arguments

Bang functions raise GoveeLights.Api.Error, which contains the original error tuple in exception.reason.

HTTP client configuration

By default, this module uses GoveeLights.HTTPClient (based on Req). You can provide a custom HTTP client by configuring:

config :govee_lights, http_client: MyHTTPClient

The client module must implement the GoveeLights.HTTPClient behaviour.

This library is unofficial and not affiliated with Govee.