💡 GoveeLights

Control your Govee smart lights directly from Elixir.

This library provides a typed, documented wrapper around the Govee Developer API. Instead of working with raw JSON maps, you interact with domain structs such as GoveeLights.Device and GoveeLights.Device.State.

⚠️ This library is unofficial and not affiliated with Govee.

🚀 Installation

Add the dependency to your mix.exs:

def deps do
  [
    {:govee_lights, "~> 0.2.0"}
  ]
end

Fetch dependencies:

mix deps.get

🔑 API Key

You must provide a Govee API key before using the API.

Either via environment variable:

export GOVEE_API_KEY="YOUR_KEY"

Or via application configuration:

config :govee_lights, api_key: "YOUR_KEY"

You can request a key here: https://developer.govee.com/reference/apply-you-govee-api-key

📘 Usage

All interaction happens through GoveeLights.Api.

alias GoveeLights.Api

📦 List devices

Retrieve all devices associated with your account as typed structs:

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

Each %Device{} contains metadata, properties, and a normalized state field.

You can also use the bang variant:

iex> devices = Api.devices!()

🔍 Device state

Fetch the current state of a device:

iex> {:ok, state} =
...>   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 result is a %GoveeLights.Device.State{} struct. Missing values are represented as :unknown.

Bang variant:

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

🔌 Power control

Turn a device on or off:

Api.turn_on("AA:BB:CC:DD:EE:FF:11:22", "H6008")
Api.turn_off("AA:BB:CC:DD:EE:FF:11:22", "H6008")

Both return:

{:ok, :updated}

Bang variants are also available:

Api.turn_on!("AA:BB:CC:DD:EE:FF:11:22", "H6008")

🔆 Brightness (0–100)

Api.set_brightness("AA:BB:CC:DD:EE:FF:11:22", "H6008", 50)

Invalid values return structured errors:

{:error, {:invalid_command, "brightness", 200}}

🌡 Color temperature (Kelvin)

Api.set_temperature("AA:BB:CC:DD:EE:FF:11:22", "H6008", 3000)

Supported ranges depend on the device model and can be inspected via Api.devices/0.

🎨 RGB color

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

Values must be integers in 0..255.

💥 Bang vs non-bang APIs

All major functions come in two forms:

Function	Behavior
`foo/…`	returns `{:ok, value}` or `{:error, reason}`
`foo!/…`	returns `value` or raises `GoveeLights.Api.Error`

Example:

Api.device_state!(device, model)

Raises GoveeLights.Api.Error if the request or decoding fails.

⚠️ Errors

Non-bang functions return structured error tuples such as:

{:http_error, reason}
{:decode_error, data}
{:device_error, raw, reason}
{:state_error, raw, reason}
{:command_failed, command, value, code, message}
{:invalid_command, command, value}

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

🛠 Development

mix test
mix docs

📌 Roadmap

Internal

Device caching layer (TTL / manual invalidation)
Improved contextual errors
Retry & backoff for transient HTTP failures

Features

Full RGB color workflows
Scene / effect control
Presets & automation helpers
Extended state modeling

❤️ Contributing

Issues and pull requests are welcome.

If you find this useful, consider leaving a ⭐ on the repository: it helps a lot !!!