OpenHue Go

A modern Go library for Philips Hue smart lighting systems

Features • Installation • Quick Start • Documentation • Contributing

---

Features

🏠 Home Abstraction — Intuitive entry point to interact with your entire Hue ecosystem
🔍 Bridge Discovery — Automatic bridge detection via mDNS with URL fallback
🔐 Easy Authentication — Simplified link button authentication flow
💡 Full API Coverage — Auto-generated from the OpenHue API specification
⚡ Type-Safe — Strongly typed Go structs for all Hue resources

Installation

Requirements: Go 1.23+

go get -u github.com/openhue/openhue-go

Quick Start

Toggle all rooms in your home with just a few lines of code:

package main

import (
    "fmt"
    "github.com/openhue/openhue-go"
)

func main() {
    home, _ := openhue.NewHome(openhue.LoadConfNoError())
    rooms, _ := home.GetRooms()

    for id, room := range rooms {
        fmt.Printf("> Toggling room %s (%s)\n", *room.Metadata.Name, id)

        for serviceId, serviceType := range room.GetServices() {
            if serviceType == openhue.ResourceIdentifierRtypeGroupedLight {
                groupedLight, _ := home.GetGroupedLightById(serviceId)
                home.UpdateGroupedLight(*groupedLight.Id, openhue.GroupedLightPut{
                    On: groupedLight.Toggle(),
                })
            }
        }
    }
}

Note

The openhue.LoadConf() function loads configuration from the well-known configuration file.
See the configuration guide for details.

Documentation

Bridge Discovery

Automatically discover Hue bridges on your local network:

bridge, err := openhue.NewBridgeDiscovery(openhue.WithTimeout(1 * time.Second)).Discover()
openhue.CheckErr(err)

fmt.Println(bridge)
// Output: Bridge{instance: "Hue Bridge - 1A3E4F", host: "ecb5fa1a3e4f.local.", ip: "192.168.1.xx"}

The discovery process tries mDNS first, then falls back to discovery.meethue.com.

Options:

• openhue.WithTimeout(duration) — Set mDNS discovery timeout (default: 5 seconds)
• openhue.WithDisabledUrlDiscovery — Disable URL fallback discovery

Authentication

Authenticate with your bridge using the link button:

bridge, _ := openhue.NewBridgeDiscovery(openhue.WithTimeout(1 * time.Second)).Discover()
authenticator, _ := openhue.NewAuthenticator(bridge.IpAddress)

fmt.Println("Press the link button")

var key string
for len(key) == 0 {
    apiKey, retry, err := authenticator.Authenticate()

    if err != nil && retry {
        fmt.Printf(".")
        time.Sleep(500 * time.Millisecond)
    } else if err != nil && !retry {
        openhue.CheckErr(err)
    } else {
        key = apiKey
    }
}

fmt.Println("\n", key)

The Authenticate() function returns:

• apiKey — The API key (non-empty on success)
• retry — true if the link button hasn't been pressed yet
• err — Error details if authentication failed

Tip

Authentication has failed when retry == false and err != nil.

Related Projects

• OpenHue API — OpenAPI specification for Philips Hue
• OpenHue CLI — Command-line interface built with this library
• openhue.io — Official documentation and guides

Contributing

Contributions are welcome! Feel free to open issues and pull requests.

This project uses oapi-codegen for code generation. Most code in openhue.gen.go is auto-generated — see the project structure before making changes.

License

OpenHue Go is distributed under the Apache License 2.0, making it open and free for anyone to use and contribute to. See the LICENSE file for details.