hue

package module
v0.0.0-...-612793f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 3, 2021 License: GPL-3.0 Imports: 8 Imported by: 0

README

hue

A driver for controlling Phillips Hue lights.

Requirements

  1. Follow the guide at https://www.developers.meethue.com/documentation/getting-started up until you can successfully send commands via the web interface
  2. Add your bridge's IP address and your user ID to your environment. The easiest way for testing is to create a *.env file like the following: 
    export HUE_BRIDGE_IP=192.168.1.XX
export HUE_USER_ID=YOUR_ID_HERE
    and then run source your_file.env.
  3. Run go install ./cmd/client from the project root
  4. Run client to run the demo program

Documentation

Overview

Package hue provides an interface to the Phillips Hue RESTful API for controlling lightbulbs over HTTP. It attempts to create a simple to use wrapper that can be used in a larger project for doing custom home automation on pre-defined schedules.

Since we have very specific needs, this is not an attempt to be an all-inclusive SDK, but rather to provide the most useful functionality in the with the simplest API.

Index

Constants

View Source 
const (
	// CancelAlert represents an alert status of "none".
	CancelAlert = iota
	// ShortAlert represents an alert status of "select", which is a single flash.
	ShortAlert
	// LongAlert represents an alert status of "lselect", which pulses for 15s or
	// until "none" is set.
	LongAlert
)
View Source 
const (
	// CancelEffect represents an effect status of "none".
	CancelEffect = iota
	// ColorLoop represents an effect status of "colorloop".
	ColorLoop
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Alert 

type Alert int

Alert represents one of the recognized alert states.

type Capabilities 

type Capabilities struct {
	Certified bool      `json:"certified"`
	Control   Control   `json:"control"`
	Streaming Streaming `json:"streaming"`
}

type Client 

type Client interface {
	Do(*http.Request) (*http.Response, error)
}

Client describes an interface that consumes an HTTP request to produce a response.

type ColorTemperature 

type ColorTemperature struct {
	Min int `json:"min"`
	Max int `json:"max"`
}

type Config 

type Config struct {
	Archetype string  `json:"archetype"`
	Function  string  `json:"function"`
	Direction string  `json:"direction"`
	Startup   Startup `json:"startup"`
}

type Control 

type Control struct {
	MinDimLevel      int              `json:"mindimlevel"`
	MaxLumen         int              `json:"maxlumen"`
	ColorGamutType   string           `json:"colorgamuttype"`
	ColorGamut       [][]float64      `json:"colorgamut"`
	ColorTemperature ColorTemperature `json:"ct"`
}

type Effect 

type Effect int

Effect represents one of the recognized effect states.

type Group 

type Group struct {
	// ID is the string ID of the group.
	ID string `json:"-"`
	// Name is the user- or system-defined name of the group.
	Name string `json:"name"`
	// Lights is a list of light IDs that belong to the group.
	Lights []string `json:"lights"`
	// GroupType is the type of group.
	GroupType string `json:"type"`
	// Action is the last state command issued to the group.
	Action State `json:"action"`
}

Group represents a group of Phillips Hue lights. The group may either be user- or system-defined. The group with ID 0 is the master group and can be used to control all lights regardless of their other group or room associations.

func (*Group) String 

func (g *Group) String() string

String implements fmt.Stringer.

type Hue 

type Hue struct {
	// contains filtered or unexported fields
}

Hue is a client to a Phillips Hue bridge. It allows control of Hue lights using the RESTful API.

func New 

func New(ip, user string, client Client) *Hue

New returns a Hue client. It connects to the bridge at the provided IP, using the given user ID, using the provided Client.

func (*Hue) Groups 

func (h *Hue) Groups() ([]*Group, error)

Groups returns a list of user-defined light groups.

func (*Hue) Light 

func (h *Hue) Light(id string) (*Light, error)

Light returns the information and state for the Phillips Hue bulb with the given ID.

func (*Hue) Lights 

func (h *Hue) Lights() (LightList, error)

Lights returns a list of all reachable Phillips Hue light bulbs and their states.

func (*Hue) SetAll 

func (h *Hue) SetAll(state StateMod) error

SetAll applies the provided StateMod to the master group that contains all the lights in the system.

func (*Hue) SetState 

func (h *Hue) SetState(l *Light, s StateMod) error
	for {
		select {
		case err := <-errs:
			return errors.Wrap(err, "could not set state")
		default:
			time.Sleep(100 * time.Millisecond)
		}
	}
}

type Light 

type Light struct {
	// ID is the simple string ID the bulbs are keyed by.
	ID string `json:"-"`

	// State is the total state of the bulb at the time of query.
	State State `json:"state"`

	Update Update `json:"swupdate"`

	Type string `json:"type"`

	// Name is the user-set nickname for a bulb.
	Name string `json:"name"`

	ModelID string `json:"modelid"`

	ManufacturerName string `json:"manufacturername"`

	ProductName string `json:"productname"`

	Capabilities Capabilities `json:"capabilities"`

	Config Config `json:"config"`

	// UniqueID is the MAC address-like ID that uniquely identifies a single
	// bulb regardless of configuration.
	UniqueID string `json:"uniqueid"`

	SoftwareVersion string `json:"swversion"`

	SoftwareConfigID string `json:"swconfigid"`

	ProductID string `json:"productid"`
}

Light describes the properties of a single Phillips Hue lightbulb.

func (*Light) String 

func (l *Light) String() string

String implements fmt.Stringer.

type LightList 

type LightList []*Light

func (LightList) Get 

func (ll LightList) Get(n string) (*Light, bool)

type Startup 

type Startup struct {
	Mode       string `json:"mode"`
	Configured bool   `json:"configured"`
}

type State 

type State struct {
	// On specifies whether the bulb is on or off.
	On bool `json:"on"`
	// Brightness is a value between 1 and 254. 1 is the lowest the bulb can
	// produce, but is not off.
	Brightness int `json:"bri"`
	// Hue is a value between 0 and 65535. Both 0 and 65535 are red, 25500 is
	// green, and 46920 is blue.
	Hue int `json:"hue"`
	// Saturation is the color saturation of the light. 254 is the most
	// saturated and 0 is the least (white).
	Saturation int `json:"sat"`
	// Alert is the last alert sent to the light. It is either "none", "select",
	// or "lselect".
	Alert string `json:"alert"`
	// Effect is currently either "none" or "colorloop".
	Effect string `json:"effect"`
	// Reachable indicates the bulb is reachable from the bridge (and can thus
	// be controlled).
	Reachable bool `json:"reachable"`
}

State describes the accumulated state of a single Phillips Hue bulb. We only work with hue and saturation at the moment, since they are the easiest without doing a lot of conversion.

func (*State) String 

func (s *State) String() string

String implements fmt.Stringer.

type StateMod 

type StateMod map[string]interface{}

StateMod is a structure suitable for converting to JSON that can be passed to the state update endpoint for a single light. This can be created manually, but it's ideal to use the StateOption functions since they do some sanity checks beforehand.

func NewState 

func NewState(opts ...StateOption) StateMod

NewState returns a StateMod that is the combination of the provided options. Options are processed in order, so passing two of the same option ends up in a last write wins scenario.

func Off 

func Off() StateMod

Off returns a StateMod setting the "on" state to false.

func On 

func On() StateMod

On returns a StateMod setting the "on" state to true.

type StateOption 

type StateOption func(StateMod)

StateOption is a function that modifies the given StateMod. Most settings are specified as "generator" function that return a StateOption function when passed a value for whatever parameter is being modified.

func WithAlert 

func WithAlert(alert Alert) StateOption

WithAlert returns a StateOption that sets the "alert" parameter to the value corresponding to the provided Alert. Unrecognized Alerts are assumed to be "none".

func WithBrightness 

func WithBrightness(bri int) StateOption

WithBrightness returns a StateOption function that sets the "bri" parameter to the given value. The value is clamped to be between 1 and 254, with 1 being the lowest a bulb can operate, and 254 being maximum brightness.

func WithEffect 

func WithEffect(effect Effect) StateOption

WithEffect returns a StateOption that sets the "effect" parameter to the value corresponding to the provided Effect. Unrecognized Effects are assumed to be "none".

func WithHue 

func WithHue(hue int) StateOption

WithHue returns a StateOption function that sets the "hue" parameter to the given vavlue. The value is clamped to be between 0 and 65535, with both being red, and additional hues occupying the space between.

func WithOff 

func WithOff() StateOption

WithOff returns a StateOption function that sets the "on" parameter to false.

func WithOn 

func WithOn() StateOption

WithOn returns a StateOption function that sets the "on" parameter to true.

func WithSaturation 

func WithSaturation(sat int) StateOption

WithSaturation returns a StateOption function that sets the "sat" parameter to the given value. The value is clamped to be between 0 and 254, with 254 being maximum color saturation, and 0 being white.

func WithTransitionTime 

func WithTransitionTime(t int) StateOption

WithTransitionTime returns a StateOption function that sets the "transitiontime" parameter to the given value. The value is clamped to be greater than 0, since negative transition times are non-sensical.

func WithXY 

func WithXY(xy XY) StateOption

type Streaming 

type Streaming struct {
	Renderer bool `json:"renderer"`
	Proxy    bool `json:"proxy"`
}

type Update 

type Update struct {
	State       string `json:"state"`
	LastInstall string `json:"lastinstall"`
}

type XY 

type XY struct {
	X, Y float64
}

func (XY) MarshalJSON 

func (xy XY) MarshalJSON() ([]byte, error)

Source Files

View all Source files

Directories

Path Synopsis
cmd
demo
This package is a demo of the API in the hue package.
 This package is a demo of the API in the hue package.
pride
stpats
xmas
This program is a test of the API that also happens to be as festive as I get.
 This program is a test of the API that also happens to be as festive as I get.
Package debug just contains some junk to help me debug the API while in development.
 Package debug just contains some junk to help me debug the API while in development.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.