LifxApi

A Ruby client for the LIFX API.

This provides access to the LIFX HTTP API, so it can control your lights from anywhere in the world. It does not implement the LAN API.

Installation

Add this line to your application's Gemfile:

gem 'lifx_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install lifx_api

Usage

You'll need to have some LIFX bulbs already setup and configured. Then you will need to obtain an access_token from the LIFX website.

require 'lifx_api'

access_token = "a1b7349df2a...e213"
client = LifxApi.new access_token
lights = client.list_lights
exit() if lights.count == 0
light_id = lights.first[:id]

client.toggle_power selector: 'all'

client.toggle_power selector: "id:#{light_id}"

Endpoints and parameters

See LIFX HTTP API for the official documentation.

list_lights

Parameters

Key	Type	Mandatory	Default	Description
`:selector`	selector		all	See selector documentation on the LIFX website.

set_state

Parameters

Key	Type	Default	Description
`:selector`	selector	all	See selector documentation on the LIFX website.
`:power`	string		The power state you want to set on the selector. Must be `on` or `off`.
`:color`	color		The color to set the light to. See color documentation on the LIFX website.
`:brightness`	numeric		The brightness level from 0.0 to 1.0. Overrides any brightness set in color (if any).
`:duration`	numeric	1.0	How long in seconds you want the power action to take. Range: `0.0` - `3155760000.0` (100 years)
`:infrared`	numeric		The maximum brightness of the infrared channel from `0.0` to `1.0`.
`:fast`	boolean	false	Execute the query fast, without initial state checks and wait for no results.

set_states

Parameters

Key	Type	Mandatory	Default	Description
`:states`	array of hashes	✔		Array of state hashes as per `#set_state`. No more than 50 entries.
`:defaults`	hash			Default values to use when not specified in each `states[]` hash.
`:fast`	boolean		false	Execute the query fast, without initial state checks and wait for no results.

state_delta

Parameters

Key	Type	Default	Description
`:selector`	selector	all	See selector documentation on the LIFX website.
`:power`	string		The power state you want to set on the selector. Must be `on` or `off`.
`:duration`	numeric	1.0	How long in seconds you want the power action to take. Range: `0.0` - `3155760000.0` (100 years)
`:infrared`	numeric		The maximum brightness of the infrared channel.
`:hue`	numeric		Rotate the hue by this angle in degrees. Range: `-360.0` - `360.0` degrees.
`:saturation`	numeric		Change the saturation by this additive amount; the resulting saturation is clipped to `[0, 1]`.
`:brightness`	numeric		Change the brightness by this additive amount; the resulting brightness is clipped to `[0, 1]`.
`:kelvin`	numeric		Change the kelvin by this additive amount; the resulting kelvin is clipped to `[2500, 9000]`.

stage_delta

[DEPRECATED] #stage_delta is deprecated, please use #state_delta instead

Parameters

Key	Type	Default	Description
`:selector`	selector	all	See selector documentation on the LIFX website.
`:power`	string		The power state you want to set on the selector. Must be `on` or `off`.
`:duration`	numeric	1.0	How long in seconds you want the power action to take. Range: `0.0` - `3155760000.0` (100 years)
`:infrared`	numeric		The maximum brightness of the infrared channel.
`:hue`	numeric		Rotate the hue by this angle in degrees. Range: `-360.0` - `360.0` degrees.
`:saturation`	numeric		Change the saturation by this additive amount; the resulting saturation is clipped to `[0, 1]`.
`:brightness`	numeric		Change the brightness by this additive amount; the resulting brightness is clipped to `[0, 1]`.
`:kelvin`	numeric		Change the kelvin by this additive amount; the resulting kelvin is clipped to `[2500, 9000]`.

toggle_power

Parameters

Key	Type	Mandatory	Default	Description
`:selector`	selector		all	See selector documentation on the LIFX website.
`:duration`	numeric		1.0	The time is seconds to spend perfoming the power toggle.

breathe_effect

Parameters

Key	Type	Mandatory	Default	Description
`:selector`	selector		all	See selector documentation on the LIFX website.
`:color`	color	✔		The color to use for the breathe effect. See color documentation on the LIFX website.
`:from_color`	string		current bulb color	The color to start the effect from. If this parameter is omitted then the color the bulb is currently set to is used instead.
`:period`	numeric		1.0	The time in seconds for one cyles of the effect.
`:cycles`	numeric		1.0	The number of times to repeat the effect.
`:persist`	boolean		false	If `false` set the light back to its previous value when effect ends, if true leave the last effect color.
`:power_on`	boolean		true	If `true`, turn the bulb on if it is not already on.
`:peak`	numeric		0.5	Defines where in a period the target color is at its maximum. Minimum `0.0`, maximum `1.0`.

move_effect

Parameters

Key	Type	Default	Description
`:selector`	selector	all	See selector documentation on the LIFX website.
`:direction`	string	forward	Move direction, can be `forward` or `backward`.
`:period`	numeric	1.0	The time in seconds for one cyles of the effect.
`:cycles`	numeric	infinite	The number of times to move the pattern across the device. Special cases are `0` to switch the effect off, and unspecified to continue indefinitely.
`:power_on`	boolean	true	Switch any selected device that is off to on before performing the effect.

morph_effect

Parameters

Key	Type	Default	Description
`:selector`	selector	all	See selector documentation on the LIFX website.
`:period`	numeric	5.0	This controls how quickly the morph runs. It is measured in seconds. A lower number means the animation is faster.
`:duration`	numeric	infinite	How long the animation lasts for in seconds. Not specifying a duration makes the animation never stop. Specifying `0` makes the animation stop. Note that there is a known bug where the tile remains in the animation once it has completed if duration is nonzero.
`:palette`	array of colors	7 colours across the spectrum	You can control the colors in the animation by specifying a list of color specifiers. For example `["red", "hue:100 saturation:1"]`.
`:power_on`	boolean	true	Switch any selected device that is off to on before performing the effect.

flame_effect

Parameters

Key	Type	Default	Description
`:selector`	selector	all	See selector documentation on the LIFX website.
`:period`	numeric	5.0	This controls how quickly the flame runs. It is measured in seconds. A lower number means the animation is faster.
`:duration`	numeric	infinite	How long the animation lasts for in seconds. Not specifying a duration makes the animation never stop. Specifying `0` makes the animation stop. Note that there is a known bug where the tile remains in the animation once it has completed if duration is nonzero.
`:power_on`	boolean	true	Switch any selected device that is off to on before performing the effect.

pulse_effect

Parameters

Key	Type	Mandatory	Default	Description
`:selector`	selector		all	See selector documentation on the LIFX website.
`:color`	string	✔		The color to use for the pulse effect. See color documentation on the LIFX website.
`:from_color`	string		current bulb color	The color to start the effect from. If this parameter is omitted then the color the bulb is currently set to is used instead.
`:period`	numeric		1.0	The time in seconds for one cyles of the effect.
`:cycles`	numeric		1.0	The number of times to repeat the effect.
`:persist`	boolean		false	If `false` set the light back to its previous value when effect ends, if true leave the last effect color.
`:power_on`	boolean		true	If `true`, turn the bulb on if it is not already on.

effects_off

Parameters

Key	Type	Mandatory	Default	Description
`:selector`	selector		all	See selector documentation on the LIFX website.
`:power_off`	boolean		false	If `true`, the devices will also be turned off.

cycle

Parameters

Key	Type	Mandatory	Default	Description
`:selector`	selector		all	See selector documentation on the LIFX website.
`:states`	array of hashes	✔		Array of state hashes as per `#set_state`. Must have 2 to 5 entries.
`:defaults`	hash			Default values to use when not specified in each `states[]` object.
`:direction`	direction		forward	Direction in which to cycle through the list. Can be `forward` or `backward`.

list_scenes

No parameters

activate_scene

Parameters

Key	Type	Mandatory	Default	Description
`:scene_uuid`	uuid	✔		The UUID for the scene you wish to activate
`:duration`	numeric		1.0	The time in seconds to spend performing the scene transition.
`:ignore`	array of strings			Any of `power`, `infrared`, `duration`, `intensity`, `hue`, `saturation`, `brightness` or `kelvin`, specifying that these properties should not be changed on devices when applying the scene.
`:overrides`	hash			A state hash as per `#set_state` specifying properties to apply to all devices in the scene, overriding those configured in the scene.

validate_color

Parameters

Key	Type	Mandatory	Default	Description
`:color`	color	✔		Color string you'd like to validate. See color documentation on the LIFX website.

Deviation from the API spec

Some API endpoints require a mandatory selector parameter, which defines which bulbs to apply your action to. This client will default the selector parameter to 'all', if no selector is provided.

# which means that you can call
client.list_bulbs
# ...and receive a hash of all your bulbs back

# instead of having to explicitly specify you want all bulbs:
client.list_bulbs selector: 'all'

Exceptions

If there is an error, LifxApi will raise an exception. The exception message will usually give a good indication of what went wrong, but you can also rescue the exception and access the request, response and decoded JSON objects, via the request, response and data methods.

Development

Run rake test to run the tests and rake console to start an interactive pry console.

TODO

Validation of :state and :array_of_states is poor
Validation of :color and :array_of_colors is poor
Validation of endpoints is non-existent

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/cyclotron3k/lifx_api.

License

The gem is available as open source under the terms of the MIT License.