Device Write API

Device write API controls devices. The API is designed in a explicit and restrictive way.

Applications can only control (write) devices through API.

On/off Device

Libre_DeviceOnOffSet(id, state)

Controls an “on/off” device. Note, the function also works on “Level Control” device, see notes below.

Parameters:

  • id - Integer, internal device ID.
  • state - Boolean, ture for on and false for off.

Note, for “Level Control” devices, “on” seta the level to “On Level” or maximum (255), “off” sets the level to 0.

Level Control Device

Libre_DeviceLevelSet(id, level, transitionTime)

Set the device level with a smooth transition time.

Parameters:

  • id - Integer, internal device ID.
  • level - Integer, target level of the device.
  • transitionTime - Integer, the time it takes to smoothly transit from current level to target level, in 1/100 second unit.

Hint: A transition time of 0 will change the device level immediately.


Libre_DeviceLevelMove(id, mode, rate)

Move the device level up or down at specified rate.

Parameters:

  • id - Integer, internal device ID.
  • mode - Integer, 0 is up, 1 is down.
  • rate - Integer, the move rate, in units per second.

Note: A “Stop” command shall be issued to stop the level move.


Libre_DeviceLevelStop(id)

Stop the previous level move command.

Parameters:

  • id - Integer, internal device ID.

Libre_DeviceLevelStep(id, mode, size, transitionTime)

Step the current level up or down with a size and transition time.

Parameters:

  • id - Integer, internal device ID.
  • mode - Integer, 0 is up, 1 is down.
  • size - Integer, step units.
  • transitionTime - Integer, transition time in 1/100 seconds.

Multistate Device

Libre_MultistateSet(id, value)

Set the present value of the multistate device.

Parameters:

  • id - Integer, internal device ID.
  • value - Integer, device’s new present value.

Color Control Device

“Color Control” device control API is listed below.

Note color control devices may operate in 3 different modes:

  1. Hue and Saturation in HSV mode
  2. x and y in xyY mode
  3. Color temperature mode

Application shall first query the “ColorMode” of the device, then use appropriate API to control the device.

Libre_DeviceColorMoveToHue(id, hue, direction, transitionTime)

Libre_DeviceColorMoveHue(id, moveMode, rate)

Libre_DeviceColorStepHue(id, stepMode, stepSize, transitionTime)

Libre_DeviceColorMoveSaturation(id, moveMode, rate)

Libre_DeviceColorMoveToSaturation(id, saturation, transitionTime)

Libre_DeviceColorStepSaturation(id, stepMode, stepSize, transitionTime)

Libre_DeviceColorMoveToHueSaturation(id, hue, saturation, transitionTime)

Libre_DeviceColorMoveToColor(id, colorX, colorY, transitionTime)

Libre_DeviceColorMoveColor(id, rateX, rateY)

Libre_DeviceColorStepColor(id, stepX, stepY, transitionTime)

Libre_DeviceColorMoveToColorTemperature(id, colorTemp, transitionTime)

Parameters:

  • id - Integer, internal device ID.
  • hue - Hue in HSV color space
  • saturation - Saturation in HSV color space
  • colorX - X in xyY color space.
  • colorY - y in xyY color space.
  • colorTemp - Color temperature.
  • direction - Integer
    • 0x00 - Shortest distance
    • 0x01 - Longest distance
    • 0x02 - Up
    • 0x03 - Down
  • moveMode - Integer
    • 0x00 - Stop
    • 0x01 - Up
    • 0x03 - Down
  • stepMode - Integer
    • 0x01 - Up
    • 0x03 - Down
  • rate, rateX, rateY - Integer, in steps per second.
  • stepSize, stepX, stepY - Integer, step units.
  • transitionTime - Integer, transition time in 1/100 seconds.

Thermostats

Libre_DeviceThermostatSet(id, attributes)

Controls the thermostat. The input attributes are checked for correct combination and value ranges.

Parameters:

  • id - Integer, internal device ID.
  • attributes - Set of key/value pairs representing the attributes. Key represents attribute ID (integer). Value represents attribute value of predefined types.

Note: A list of valid attribute ID can be found here.

Work in Progress

More device control API will be open over time through Hub update.