Project

lifx_api

0.0
No commit activity in last 3 years
No release in over 3 years
A client for the LIFX HTTP API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 5.0
~> 0.10
>= 0
 Project Readme

LifxApi Build Status

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 Mandatory 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 Mandatory 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 Mandatory 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 Mandatory 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 Mandatory 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 Mandatory 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.