Lights
Best practices for lights.
Lights are devices that are light sources itself or devices that can directly control light sources. This entails smart light bulbs (e.g. LIFX), sockets (e.g. Fibaro Wall Plug) and (flush) modules (e.g. Fibaro Dimmer 2). Sockets can be seen as a different category, however sockets that have the onoff
and dim
capabilities are most often used for lights and are therefore relevant to consider in this category.
Choosing a device class
In general light devices have the light
device class. In some cases socket
is more applicable. A socket
device has a “What’s plugged in?” setting that allows a user to choose a virtual device class (e.g. light
). Obviously, for socket devices such as Fibaro Wall Plug and Qubino Plug socket
is the required device class.
For (flush) modules, such as the Qubino Flush Dimmer, a tradeoff has to be made. If there are use cases for the device other than controlling a light source the required device class should be socket
. The Qubino Flush Dimmer 0 - 10V has various use cases other than controlling light sources, for example bathroom ventilation control. When in doubt, use socket
since this allows users to configure the device as light
(or something else) after pairing.
Although socket
allows the user to choose “what’s plugged in” it is required to give a device the class light
when possible. This provides a better user experience since it will have the right UI components by default. Otherwise the user needs to find the “what’s plugged in” setting to correct it.
Capabilities and behaviour
Implementing capabilities of lights needs some consideration. We start with the two basic capabilities onoff
and dim
.
Capabilities onoff
and dim
onoff
and dim
A light device can be turned on and off via the toggle UI component (see left image below) as well as the dim level UI component (see right image below). When the device is off, dragging the dim slider from 0 to non-zero must turn the device on (this means the onoff
capability needs to be set to true
). When the device is on, dragging the dim slider from non-zero to 0 must turn the device off (this means the onoff
capability needs to be set to false
).
If the device is using a technology that allows it to report its onoff
and dim
state to Homey when it is changed through external inputs (such as connected switches) this should be reflected in the device UI. If the device is turned off externally, the device should be turned off in Homey, same for dimming. Zigbee and Z-Wave are examples of technologies that almost always support this.
The onoff
and dim
capabilities should be coupled together and debounced. This can be done using the Device#registerMultipleCapabilityListener()
method. This is required because users can create Flows with both an onoff
and dim
action. In order to prevent duplicate (potentially conflicting) commands being sent to a device (e.g. turn on and dim to 50% which would result in a device turning on to the last known dim value and then dimming back to 50%) these capabilities need to be debounced together and combined into one command to the device.
In the unexpected case that a user creates a conflicting Flow, such as turn on and dim to 0%, or turn off and dim to 50%, make sure the onoff
capability is leading. That means, if the dim value is zero, but the new onoff value is true, turn the light on and disregard the dim value and vice versa.
Using the setOnDim
capability option for the onoff
capability will result in Homey sending only a dim
capability set instead of both onoff
and dim
when a user or Flow changes the dim level of a device.
Color and temperature capabilities
Light devices supporting one or multiple of the following capabilities are a little bit more complex:
light_hue
light_saturation
light_temperature
light_mode
A few things are important in this case.
Similar to onoff
and dim
the color and temperature capabilities need to be grouped and debounced to prevent flickering of the device. In general it is best to debounce the color and temperature capabilities together with onoff
and dim
, but this might depend on the technology you are using and how the device responds to different commands. The general rule is to prevent flickering (due to multiple commands being sent from one Flow or user action) as much as possible.
When the device is turned off, changing the light_hue
, light_saturation
, light_temperature
or light_mode
capabilities must not turn the device on. Only onoff
and dim
are allowed to change the on/off state of a device. In the case that the user turns the device on through external inputs (e.g. connected switches) the driver should listen (or actively request if needed) for updates with regard to the light_hue
, light_saturation
, light_temperature
or light_mode
capabilities and reflect the actual state of the device in the UI.
In the unexpected case that a user creates a conflicting Flow, such as turn off and set color to red, make sure the onoff
capability is leading. That means, turn off the light even though the user changed the color to red.
Last updated