govee 0.3.0

Async Rust library for controlling Govee smart lighting devices via cloud and local LAN APIs
Documentation

govee

A Rust library for controlling Govee smart lighting devices. Provides idiomatic async access to both the Govee cloud API (v1) and the local LAN API over UDP, a unified backend abstraction, device registry with name/alias resolution, and a scene system for multi-device presets.

Designed as a foundation for govee-cli, govee-server, and govee-mcp — it has no opinion about how it is invoked.

Status

WIP: This project is currently in development and not ready for production use.
Done: M1 in v0.1.0, M2 in v0.2.0, M3 in v0.3.0

Getting started

Prerequisites

  • Rust (1.91+ for edition 2024)
  • Lefthook — git hooks manager

Set up git hooks

Install lefthook and activate the hooks before making any commits:

# macOS
brew install lefthook

# or via npm/cargo/go — see https://github.com/evilmartians/lefthook/blob/master/docs/install.md

lefthook install

This configures:

  • pre-commit — cargo fmt --check and cargo clippy (parallel)
  • pre-push — cargo build then cargo test (sequential)

Build

cargo build

Test

cargo test

Lint

cargo fmt --check
cargo clippy

Development plan

Milestone Scope Status
M1 — Scaffold & CI/CD Cargo project, module stubs, GitHub Actions for CI (fmt + clippy, build, test) and two-step immutable release on tag v0.1.0
M2 — Core types & configuration DeviceId, Device, DeviceState, Color, GoveeError, Config with TOML parsing, input validation v0.2.0
M3 — Cloud backend (v1) GoveeBackend trait, CloudBackend (list, state, control), rate limit handling, User-Agent, timeouts, 84 wiremock+unit tests v0.3.0
M4 — Local LAN backend LocalBackend with UDP multicast discovery, unicast control, state queries, port conflict detection Pending
M5 — Device registry DeviceRegistry: cloud+local merge, name/alias resolution, backend auto-selection, optimistic state cache, groups Pending
M6 — Scenes & workflow stub Built-in + user-defined scene presets, apply_scene, workflow engine stub (NotImplemented) Pending
M7 — SRE & hardening Structured tracing, retry/backoff, graceful degradation, security audit, integration test suite, threat model docs Pending