Documentation
¶
Overview ¶
Package govee provides a Go client for the Govee Developer REST API v1. It supports listing devices, querying device state, and sending control commands (on/off, brightness, RGB color, color temperature).
Usage:
client := govee.New("your-api-key")
devices, err := client.GetDevices(ctx)
err = client.TurnOn(ctx, devices[0].DeviceID, devices[0].Model)
Index ¶
- type APIError
- type Client
- func (c *Client) GetDeviceState(ctx context.Context, deviceID, model string) (*DeviceState, error)
- func (c *Client) GetDevices(ctx context.Context) ([]Device, error)
- func (c *Client) SetBrightness(ctx context.Context, deviceID, model string, brightness int) error
- func (c *Client) SetColor(ctx context.Context, deviceID, model string, r, g, b int) error
- func (c *Client) SetColorTemp(ctx context.Context, deviceID, model string, kelvin int) error
- func (c *Client) TurnOff(ctx context.Context, deviceID, model string) error
- func (c *Client) TurnOn(ctx context.Context, deviceID, model string) error
- type Color
- type ColorTempRange
- type Device
- type DeviceProperties
- type DeviceState
- type Option
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
APIError is returned when the Govee API responds with a non-200 status code.
Example ¶
package main
import (
"context"
"errors"
"fmt"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("invalid-key")
_, err := client.GetDevices(context.Background())
if err != nil {
var apiErr *govee.APIError
if errors.As(err, &apiErr) {
fmt.Printf("API error %d: %s\n", apiErr.Code, apiErr.Message)
} else {
log.Fatal(err)
}
}
}
Output:
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a Govee API client. Create one with New().
func New ¶
New creates a new Govee API client authenticated with the given API key.
Example ¶
package main
import (
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
_ = client
}
Output:
Example (WithOptions) ¶
package main
import (
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New(
"your-api-key",
govee.WithBaseURL("https://developer-api.govee.com"),
)
_ = client
}
Output:
func (*Client) GetDeviceState ¶
GetDeviceState queries the current state of a device. Only devices with Retrievable=true return useful state. Note: the "online" field is cached on Govee's side and may be stale.
Example ¶
package main
import (
"context"
"fmt"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
devices, err := client.GetDevices(context.Background())
if err != nil {
log.Fatal(err)
}
for _, d := range devices {
if !d.Retrievable {
continue
}
state, err := client.GetDeviceState(context.Background(), d.DeviceID, d.Model)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s: online=%v power=%s brightness=%d\n",
d.DeviceName, state.Online, state.PowerState, state.Brightness)
}
}
Output:
func (*Client) GetDevices ¶
GetDevices returns all Govee devices associated with the API key.
Example ¶
package main
import (
"context"
"fmt"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
devices, err := client.GetDevices(context.Background())
if err != nil {
log.Fatal(err)
}
for _, d := range devices {
fmt.Printf("%s (%s) — %s\n", d.DeviceName, d.Model, d.DeviceID)
}
}
Output:
func (*Client) SetBrightness ¶
SetBrightness sets the brightness of the device (0–100). A value of 0 turns the device off.
Example ¶
package main
import (
"context"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
devices, err := client.GetDevices(context.Background())
if err != nil {
log.Fatal(err)
}
if len(devices) == 0 {
return
}
d := devices[0]
if err := client.SetBrightness(context.Background(), d.DeviceID, d.Model, 75); err != nil {
log.Fatal(err)
}
}
Output:
func (*Client) SetColor ¶
SetColor sets the RGB color of the device. Each channel is 0–255.
Example ¶
package main
import (
"context"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
devices, err := client.GetDevices(context.Background())
if err != nil {
log.Fatal(err)
}
if len(devices) == 0 {
return
}
d := devices[0]
// Set color to orange (R=255, G=165, B=0).
if err := client.SetColor(context.Background(), d.DeviceID, d.Model, 255, 165, 0); err != nil {
log.Fatal(err)
}
}
Output:
func (*Client) SetColorTemp ¶
SetColorTemp sets the color temperature of the device in Kelvin. The valid range is device-specific (reported in DeviceProperties.ColorTemp).
Example ¶
package main
import (
"context"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
devices, err := client.GetDevices(context.Background())
if err != nil {
log.Fatal(err)
}
if len(devices) == 0 {
return
}
d := devices[0]
// Check that the device supports color temperature before setting it.
if !d.SupportsCmd("colorTem") {
return
}
// Set to daylight (6500K). The valid range is in d.Properties.ColorTemp.
if err := client.SetColorTemp(context.Background(), d.DeviceID, d.Model, 6500); err != nil {
log.Fatal(err)
}
}
Output:
func (*Client) TurnOff ¶
TurnOff turns the device off.
Example ¶
package main
import (
"context"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
devices, err := client.GetDevices(context.Background())
if err != nil {
log.Fatal(err)
}
if len(devices) == 0 {
return
}
d := devices[0]
if err := client.TurnOff(context.Background(), d.DeviceID, d.Model); err != nil {
log.Fatal(err)
}
}
Output:
func (*Client) TurnOn ¶
TurnOn turns the device on.
Example ¶
package main
import (
"context"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
devices, err := client.GetDevices(context.Background())
if err != nil {
log.Fatal(err)
}
if len(devices) == 0 {
return
}
d := devices[0]
if err := client.TurnOn(context.Background(), d.DeviceID, d.Model); err != nil {
log.Fatal(err)
}
}
Output:
type ColorTempRange ¶
ColorTempRange is the supported color temperature range for a device, in Kelvin.
type Device ¶
type Device struct {
// DeviceID is the MAC address of the device, used to identify it in control and state requests.
DeviceID string `json:"device"`
// Model is the product model string (e.g. "H6159").
Model string `json:"model"`
// DeviceName is the user-assigned name from the Govee app.
DeviceName string `json:"deviceName"`
// Controllable is true when the device accepts control commands.
Controllable bool `json:"controllable"`
// Retrievable is true when the device state can be queried.
Retrievable bool `json:"retrievable"`
// SupportCmds lists the commands the device accepts: "turn", "brightness", "color", "colorTem".
SupportCmds []string `json:"supportCmds"`
// Properties holds optional per-device property constraints.
Properties DeviceProperties `json:"properties"`
}
Device represents a Govee smart device returned by the API.
func (Device) SupportsCmd ¶
SupportsCmd reports whether the device supports the given command name.
Example ¶
package main
import (
"context"
"fmt"
"log"
govee "github.com/DTCurrie/govee-go"
)
func main() {
client := govee.New("your-api-key")
devices, err := client.GetDevices(context.Background())
if err != nil {
log.Fatal(err)
}
for _, d := range devices {
if d.SupportsCmd("color") {
fmt.Printf("%s supports RGB color\n", d.DeviceName)
}
}
}
Output:
type DeviceProperties ¶
type DeviceProperties struct {
// ColorTemp is non-nil when the device supports the "colorTem" command.
ColorTemp *ColorTempRange `json:"colorTemp,omitempty"`
}
DeviceProperties holds optional per-device constraints returned by DeviceList.
type DeviceState ¶
type DeviceState struct {
// Online indicates whether the device is reachable. Note: this is cached by
// the Govee API and may be stale; control commands should still be attempted
// even when Online is false.
Online bool
// PowerState is "on" or "off".
PowerState string
// Brightness is the current brightness level (0–100). 0 means off or unknown.
Brightness int
// Color is the current RGB color, or nil if not reported.
Color *Color
// ColorTemp is the current color temperature in Kelvin, or 0 if not reported.
ColorTemp int
}
DeviceState is the current reported state of a device.
type Option ¶
type Option func(*Client)
Option is a functional option for configuring a Client.
func WithBaseURL ¶
WithBaseURL overrides the default API base URL. Useful for testing.
func WithHTTPClient ¶
WithHTTPClient replaces the default *http.Client. Useful for custom transports or timeouts.