Skip to content

Latest commit

 

History

History
410 lines (246 loc) · 14.3 KB

lightState.md

File metadata and controls

410 lines (246 loc) · 14.3 KB
Raw

Light States

There are three variations of the LightState object that are used by different parts of the API:

These Light State objects all share common base properties and then have some specialized functionality as required by the underlying Hue Bridge API.

Creating a LightState

To create any one of the variations of LightStates you can import them using:

// LightState fo r interacting with Lights
const LightState = require('node-hue-api').v3.lightStates.LightState;

// LightState for interacting with Scene Lights
const SceneLightState = require('node-hue-api').v3.lightStates.GroupLightState;

// LightState for interacting with Group Lights
const GroupLightState = require('node-hue-api').v3.lightStates.GroupLightState;

Once you have the desired LightState implementation, you can build a light state using parameters specific to that Light State, for example:

const LightState = require('node-hue-api').v3.lightStates.LightState;

const myLightState = new LightState();

// Do stuff with myLightState
myLightState
  .on()
  .white(153, 100);

The LightState object is a convenience object to aid in building up a valid LightState that can be applied to a Light.

Common LightState Properties

All implementations of Light State objects have these properties/functions.

All of the Light State functions that set values on the state object will return the Light State object itself, allowing for chaining of function calls to build up the light state in a more fluent manner.

For example to create and then populate a LightState with the desired state:

myLightState = new LightState()
  .on(true)
  .brightness(50)
  .saturation(65)
  .alertShort();

reset()

The function reset() will clear all the existing settings on a LightState.

getPayload()

The function getPayload() will transform the LightState settings into a payload JSON object that the Hue Bridge can set.

This function can be useful to capture a snapshot of the current settings in a LightState.

You should not need to call this yourself as the API will perform the necessary conversions using the targeted light device before passing the payload to the Hue Bridge.

Note, this function is not chainable as it returns a JSON payload for the state.

populate()

The function populate(data) will populate the state values of the LightState object using the data object it is called with.

For each property key in the data object that is matched to a valid state property in the LightState, the corresponding value from the data object will be set.

For example calling this function with a data object of the form:

{
  "on": true,
  "ct": 153,
  "some_other_value": 100
}

Will result in the matched state values of on and ct being set to true and 153 respectively. The value some_other_value in the data object will be ignored.

This function can be used along with getPayload() to copy an existing LightState object using the following code:

const myLightState = new LightState().on.ct(200);

// Create a copy of myLightState
const copiedLightState = new LightState();
copiedLightState.populate(myLightState.getPayload());

on()

The on(value) function will set the state to the boolean value of value, or if value is not specified, will implicitly set a value of true.

  • value: The on state of the light, true or not specified for on and false for off.

off()

The function off() is a convenience function that will set the Light state to the equivalent of on(false).

bri()

The function bri(value) will set the bri attribute to value.

  • value: the brightness value to set the light to. Brightness is a scale from 1 (the minimum the light is capable of) to 254 (the maximum).

Note: a brightness of 1 is not off.

brightness()

The brightness(value) function will set a brightness percentage value for the light.

  • value: A percentage value for the brightness between 0 and 100. Note that 0% will correspond to a bri value of 1, which is not off.

hue()

The hue(value) function will set a hue value for the light.

  • value: The hue value is a wrapping value between 0 and 65535. Both 0 and 65535 are red, 25500 is green and 46920 is blue

sat()

The sat(value) function will set a saturation value for the light.

  • value: the saturation of the light. 0 is the least saturated (white) and 254 is the most saturated (colored)

saturation()

The saturation(value) function will set a saturation as a percentage value.

  • value: The percentage for the saturation between 0 and 100.

xy()

The xy(x, y) function will set an x,y cooridinate in the CIE color space.

  • x: x cooordinate between 0 and 1
  • y: y coorordinate between 0 and 1

Note: You can pass the xy value in as a Array as well, e.g. xy([x, y]).

If you pass in values outside the CIE color space for the target light, the closest color to the coordinates will be chosen by the Hue Bridge.

ct()

The ct(value) function will set the Mired color temperature for the light.

  • value: The Mired color temperature, between 153 (6500K) and 500 (2000K)

bri_inc()

The bri_inc(value), increments or decrements the value of the brightness. The bri_inc is ignored if the bri attribute is provided.

  • value: An increment or decrement value between -254 and 254. A value of 0 stops any ongoing transition.

sat_inc()

The sat_inc(value), increments or decrements the value of the saturation. The sat_inc is ignored if the sat attribute is provided.

  • value: An increment or decrement value between -254 and 254. A value of 0 stops any ongoing transition.

hue_inc()

The hue_inc(value), increments or decrements the value of the brightness. The hue_inc is ignored if the hue attribute is provided.

  • value: An increment or decrement value between -65534 and 65534.

Note: the hue value is a wrapped attribute in the bridge. This means once the increment/decrement value is applied, if it is out of the hue range of 0 to 65535 the result will wrap, e.g. an existing hue value of 65535 incremented by 1 will wrap to 0.

ct_inc()

The ct_inc(value) function increments or decrements the value of the ct. ct_inc is ignored if the ct attribute is provided.

  • value: An increment or decrement value between -65534 and 65534. A value of 0 stops any ongoing transition.

xy_inc()

The xy_inc(x_inc, y_inc) function will increment or decrement an existing x,y cooridinate in the CIE color space. The xy_inc attribute is ignored if an xy value is set.

  • x: x increment or decrement between -0.5 and 0.5 setting a value of 0 will stop any ongoing transition
  • y: y increment or decrement -0.5 and 0.5 setting a value of 0 will stop any ongoing transition

Note: You can pass the xy value in as a Array as well, e.g. xy_inc([x_inc, y_inc]).

If you pass in values outside the CIE color space for the target light, the closest color to the coordinates will be chosen by the Hue Bridge.

effect ()

The effect(value) will set the effect on the light.

  • value: The effect to set which can be colorloop or none. Setting colorloop will cycle through all the hues that the light supports using the existing brightness and saturation settings.

Note: setting this to none will clear any looping.

effectColorLoop()

The effectColorLoop() function will set an effect of colorloop for the light.

effectNone()

The effectNone() function will set an effect of none for the light.

transitiontime()

The transitiontime(value) will set the duration of any transition from the lights current state to the new state.

  • value: An integer value as a multiple of 100ms, e.g. 4 corresponds to 400ms and 10 to 1 second.

transition()

The transition(value) function will set the duration of any transition from the lights current stat to a new state in milliseconds.

  • value: The value in milliseconds for the transition, e.g. 4000 for 4000ms

transtionInMiilis()

The transition(value) function will set the duration of any transition from the lights current stat to a new state in milliseconds.

  • value: The value in milliseconds for the transition, e.g. 4000 for 4000ms

transitionSlow()

The transitionSlow() function will set a slow transition for the light state change of 800ms.

transtionFast()

The transitionFast() function will set a fast transition for the list state change of 200ms

transtionInstant()

The transitionInstant() function will set an instance transition time of 0ms.

transitionDefault()

The transitionDefault() function will set the Bridge default transition time of 400ms.

alert()

The alert(value) function will allow you to set a temporary alert state on the light.

  • value: One of none, select (one breathe cycle), lselect (breathe cycles for 15 seconds or until cleared using none alert state).

Note: you are not required to reset this state to none unless you want to stop the current state. Also the light will report the previously set value for this when retrieved, which is not necessarily the current state.

alertNone()

The alertNone() function will clear the current alert state, setting it to none.

alertShort()

The alertShort() function will set the current alert state to select.

alertLong()

The alertLong() function will set the current alert state to lselect.

LightState

LightState is used for defining a Light State that can be used directly on a Light instance via the lights api.

In addition to the common properties for a Light State it also has:

white()

The white(temp, bri) function will set the state to white, using the provided temp and brightness values.

  • temp is the ct value also known as the Mired color temperature and can be set to a value between 153 and 500 (corresponding to 6500K and 2000K respectively). This is the same as ct()
  • bri is the brightness expressed as a percentage from 0 to 100. Note, 0% does not mean off in this case, it will correspond to the lowest bri value for the light. This is the same as breightness()

hsb()

The hsb(hue, saturation, brightness) function will set an hsb value on the light.

  • hue: is the hue value expressed as a degree value between 0 and 360.
  • saturation: is the saturation expressed as a percentage from 0 to 100. This is the same as saturation()
  • brightness is the brightness expressed as a percentage from 0 to 100. Note, 0% does not mean off in this case, it will correspond to the lowest bri value for the light. This is the same as breightness()

hsl()

The hsl(hue, saturation, luminosity) function will set an hsl value on the light.

  • hue: is the hue value expressed as a degree value between 0 and 360.
  • saturation: is the saturation expressed as a percentage from 0 to 100. This is the same as saturation()
  • luminosity: is the luminsoty value between 0 and 100.

Note: that there is conversion in play with this value, so it is an approximation to what the light can display.

rgb()

The rgb(red, green, blue) will set an RGB value on the light.

  • red: the red value between 0 and 255
  • green: the green value between 0 and 255
  • blue: the blue value between 0 and 255

Note: You can pass the rgb value in as a Array as well, e.g. rbg([255, 0, 0]).

Note: That these values are converted in to a value that the light can display, as such, you might not get a perfect match to your expected RGB color. This is limited by what colors that the light can actually support and there is a lot of mathematics going on in the background to map this to the light color space.

SceneLightState

The SceneLightState is to be used for setting LightStates of Lights contained within a Scene. This state object only has the common properties

GroupLightState

The GroupLightState is to be used with the triggering of LightStates of Lights in a Group.

In addition to the common properties for a Light State it also has:

scene()

The scene(value) function allows for the scene name to be set on the Group that you wish to trigger.

  • name: A string for the identifier of the scene to trigger for the Group.

When using this property of a GroupLightState to set a state on a Group, you will get the intersection of the lights associated with the Group and the target Scene's lights attribute.