Documentation ¶
Overview ¶
Package golifx provides a simple Go interface to the LIFX LAN protocol.
Based on the protocol documentation available at: http://lan.developer.lifx.com/
Also included in cmd/lifx is a small CLI utility that allows interacting with your LIFX devices on the LAN.
In various parts of this package you may find references to a Device or a Light. The LIFX protocol makes room for future non-light devices by making a light a superset of a device, so a Light is a Device, but a Device is not necessarily a Light. At this stage, LIFX only produces lights though, so they are the only type of device you will interact with.
Index ¶
- Constants
- func SetLogger(logger common.Logger)
- type Client
- func (c *Client) Close() error
- func (c *Client) CloseSubscription(sub *common.Subscription) error
- func (c *Client) GetDeviceByID(id uint64) (common.Device, error)
- func (c *Client) GetDeviceByLabel(label string) (common.Device, error)
- func (c *Client) GetDevices() (devices []common.Device, err error)
- func (c *Client) GetGroupByID(id string) (common.Group, error)
- func (c *Client) GetGroupByLabel(label string) (common.Group, error)
- func (c *Client) GetGroups() (groups []common.Group, err error)
- func (c *Client) GetLightByID(id uint64) (light common.Light, err error)
- func (c *Client) GetLightByLabel(label string) (common.Light, error)
- func (c *Client) GetLights() (lights []common.Light, err error)
- func (c *Client) GetLocationByID(id string) (common.Location, error)
- func (c *Client) GetLocationByLabel(label string) (common.Location, error)
- func (c *Client) GetLocations() (locations []common.Location, err error)
- func (c *Client) GetRetryInterval() *time.Duration
- func (c *Client) GetTimeout() *time.Duration
- func (c *Client) NewSubscription() (*common.Subscription, error)
- func (c *Client) SetColor(color common.Color, duration time.Duration) error
- func (c *Client) SetDiscoveryInterval(interval time.Duration) error
- func (c *Client) SetPower(state bool) error
- func (c *Client) SetPowerDuration(state bool, duration time.Duration) error
- func (c *Client) SetRetryInterval(retryInterval time.Duration)
- func (c *Client) SetTimeout(timeout time.Duration)
Examples ¶
Constants ¶
const (
// VERSION of this library
VERSION = "0.5.0"
)
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Client ¶
Client provides a simple interface for interacting with LIFX devices. Client can not be instantiated manually or it will not function - always use NewClient() to obtain a Client instance.
func NewClient ¶
NewClient returns a pointer to a new Client and any error that occurred initializing the client, using the protocol p. It also kicks off a discovery run.
Example (V2) ¶
Instantiating a new client with protocol V2, with default options
package main import ( "fmt" "github.com/pdf/golifx" "github.com/pdf/golifx/protocol" ) func main() { client, err := golifx.NewClient(&protocol.V2{}) if err != nil { panic(err) } light, err := client.GetLightByLabel(`lightLabel`) if err != nil { panic(err) } fmt.Println(light.ID()) }
Output:
Example (V2port) ¶
When using protocol V2, it's possible to choose an alternative client port. This is not recommended unless you need to use multiple client instances at the same time.
package main import ( "fmt" "github.com/pdf/golifx" "github.com/pdf/golifx/protocol" ) func main() { client, err := golifx.NewClient(&protocol.V2{Port: 56701}) if err != nil { panic(err) } light, err := client.GetLightByLabel(`lightLabel`) if err != nil { panic(err) } fmt.Println(light.ID()) }
Output:
Example (V2reliable) ¶
When using protocol V2, it's possible to enable reliable operations. This is highly recommended, otherwise sends operate in fire-and-forget mode, meaning we don't know if they actually arrived at the target or not. Whilst this is faster and generates less network traffic, in my experience LIFX devices aren't the most reliable at accepting the packets they're sent, so sometimes we need to retry.
package main import ( "fmt" "github.com/pdf/golifx" "github.com/pdf/golifx/protocol" ) func main() { client, err := golifx.NewClient(&protocol.V2{Reliable: true}) if err != nil { panic(err) } light, err := client.GetLightByLabel(`lightLabel`) if err != nil { panic(err) } fmt.Println(light.ID()) }
Output:
func (*Client) CloseSubscription ¶ added in v0.1.0
func (c *Client) CloseSubscription(sub *common.Subscription) error
CloseSubscription is a callback for handling the closing of subscriptions.
func (*Client) GetDeviceByID ¶
GetDeviceByID looks up a device by its `id` and returns a common.Device. May return a common.ErrNotFound error if the lookup times out without finding the device.
func (*Client) GetDeviceByLabel ¶
GetDeviceByLabel looks up a device by its `label` and returns a common.Device. May return a common.ErrNotFound error if the lookup times out without finding the device.
func (*Client) GetDevices ¶
GetDevices returns a slice of all devices known to the client, or common.ErrNotFound if no devices are currently known.
func (*Client) GetGroupByID ¶ added in v0.2.0
GetGroupByID looks up a group by its `id` and returns a common.Group. May return a common.ErrNotFound error if the lookup times out without finding the group.
func (*Client) GetGroupByLabel ¶ added in v0.2.0
GetGroupByLabel looks up a group by its `label` and returns a common.Group. May return a common.ErrNotFound error if the lookup times out without finding the group.
func (*Client) GetGroups ¶ added in v0.2.0
GetGroups returns a slice of all groups known to the client, or common.ErrNotFound if no groups are currently known.
func (*Client) GetLightByID ¶
GetLightByID looks up a light by its `id` and returns a common.Light. May return a common.ErrNotFound error if the lookup times out without finding the light, or common.ErrDeviceInvalidType if the device exists but is not a light.
func (*Client) GetLightByLabel ¶
GetLightByLabel looks up a light by its `label` and returns a common.Light. May return a common.ErrNotFound error if the lookup times out without finding the light, or common.ErrDeviceInvalidType if the device exists but is not a light.
func (*Client) GetLights ¶
GetLights returns a slice of all lights known to the client, or common.ErrNotFound if no lights are currently known.
func (*Client) GetLocationByID ¶ added in v0.2.0
GetLocationByID looks up a location by its `id` and returns a common.Location. May return a common.ErrNotFound error if the lookup times out without finding the location.
func (*Client) GetLocationByLabel ¶ added in v0.2.0
GetLocationByLabel looks up a location by its `label` and returns a common.Location. May return a common.ErrNotFound error if the lookup times out without finding the location.
func (*Client) GetLocations ¶ added in v0.2.0
GetLocations returns a slice of all locations known to the client, or common.ErrNotFound if no locations are currently known.
func (*Client) GetRetryInterval ¶
GetRetryInterval returns the currently configured retry interval for operations on this client
func (*Client) GetTimeout ¶
GetTimeout returns the currently configured timeout period for operations on this client
func (*Client) NewSubscription ¶ added in v0.1.0
func (c *Client) NewSubscription() (*common.Subscription, error)
NewSubscription returns a new *common.Subscription for receiving events from this client.
func (*Client) SetColor ¶
SetColor broadcasts a request to change the color of all devices on the network.
func (*Client) SetDiscoveryInterval ¶
SetDiscoveryInterval causes the client to discover devices and state every interval. You should set this to a non-zero value for any long-running process, otherwise devices will only be discovered once.
func (*Client) SetPower ¶
SetPower broadcasts a request to change the power state of all devices on the network. A state of true requests power on, and a state of false requests power off.
func (*Client) SetPowerDuration ¶ added in v0.0.2
SetPowerDuration broadcasts a request to change the power state of all devices on the network, transitioning over the specified duration. A state of true requests power on, and a state of false requests power off. Not all device types support transitioning, so if you wish to change the state of all device types, you should use SetPower instead.
func (*Client) SetRetryInterval ¶
SetRetryInterval sets the retry interval for operations on this client. If a timeout has been set, and the retry interval exceeds the timeout, the retry interval will be set to half the timeout
func (*Client) SetTimeout ¶
SetTimeout sets the time that client operations wait for results before returning an error. The special value of 0 may be set to disable timeouts, and all operations will wait indefinitely, but this is not recommended.
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
lifx
Command lifx allows performing basic operations on LIFX devices over the LAN
|
Command lifx allows performing basic operations on LIFX devices over the LAN |
Package common contains common elements for the golifx client and protocols
|
Package common contains common elements for the golifx client and protocols |
Package protocol implements the LIFX LAN protocol.
|
Package protocol implements the LIFX LAN protocol. |
v2/device
Package device implements a LIFX LAN protocol version 2 device.
|
Package device implements a LIFX LAN protocol version 2 device. |
v2/packet
Package packet implements a LIFX LAN protocol version 2 packet.
|
Package packet implements a LIFX LAN protocol version 2 packet. |
v2/shared
Package shared contains shared elements of the LIFX LAN protocol version 2.
|
Package shared contains shared elements of the LIFX LAN protocol version 2. |