diff --git a/developers/addons/faq.md b/developers/addons/faq.md index b344d0d1c6..45694edbbe 100644 --- a/developers/addons/faq.md +++ b/developers/addons/faq.md @@ -51,34 +51,69 @@ If you do not find an answer to your question, do not hesitate to ask it on the ### Modelling Channels -1. _How do I model a dimmable light?_ - - A dimmable light should only have a single channel of type `system.brightness` for its control. - Note that although this channel type is declared for item type 'Dimmer', it is perfectly possible to link a `Switch` - item to it, additionally to a `Dimmer` item. - The possibility to switch the light ON/OFF is therefore implicitly available and there is no need for an additional channel with item type `Switch`, even if the hardware might have separated switching and dimming in different commands. - In the openHAB abstraction layer, 0% brightness is identical to OFF. - Sending an ON command to such a channel does not have to switch to 100% brightness, though. - Depending on whether the device supports it, it can also dim to the last brightness value (other than 0%) it was in before. - -1. _How do I model a color light?_ - - This is very similar to dimmable lights, just that this time the channel should be of type `system.color`. - Note again that this channel is very versatile: The user can link `Switch`, `Dimmer` and `Color` items to it, possibly also all at the same time. - When the brightness is changed (through a linked `Dimmer` item), the hue and saturation values are simply kept. - Likewise, an OFF command will simply adjust the brightness to 0%, so that with the next ON (or brightness change), the hue and saturation values are untouched. - -1. _How do I deal with a color temperature feature of a bulb? - - In theory, color temperature is nothing else than a color palette with a limited (linear) choice of colors. - We do not have a dedicated item type for it in openHAB and it would be very tricky to map color temperatures to HSB values of an `Color` channel. - So unlike the solution for color bulbs above, we cannot simply "upgrade" our channel to another item type and openHAB therefore defines the `system.color-temperature` channel type, which should be used for a dedicated channel additionally to the brightness/color channel. - - As color temperature is a linear control, its typical controls are Dimmer items, where the value defines the amount of "heat", i.e. 0% is cold light, while 100% is warm light. - `Dimmer` items are a great match for physical controls, such as rotary controls or rockers (with repeating INCREASE/DECREASE commands) and therefore allow an easy integration with input interfaces, be it physical devices or UI widgets. - - If the light bulb also offers setting absolute color temperatures, the Thing can additionally also offer a channel of the advanced `system.color-temperature-abs` channel type. - This is especially useful when being used from within automation rules where different light bulbs from different vendors should be set to the very same color temperature. +1. _How do I model a light with color, brightness, on/off, and/or color temperature channels?_ + + Lights have different capabilities -- some are just on/off, some are dimmable, some have cold/warm color temperature control, and some have full color control. +So when you model a light in your binding, you must follow the _**"Highest Capability Channel Rule"**_. +This rule means supporting **only one** of the following _Single Color Channel for Top Capability Light, Single Dimmer Channel for Mid Capability Light_, or _Single Switch Channel for Low Capability Light_ scenarios: + + - _Single Color Channel for Top Capability Light:_ + If the light supports full color, it must expose one single `Color` channel only. + This should have the channel-type `system.color` therefore inheriting default tags `[Control, Color]`. + Although the channel is of type `Color`, items of type `Dimmer` or `Switch` can be linked to it. + The ability to dim or switch the light is therefore implicitly available so there is no need for an additional channel with item type `Dimmer` or `Switch`, even if the hardware might have separated switching and dimming in different commands. + Therefore the channel must be able to process all of the following types of command: + - HSBType commands control the color hue, brightness, and on/off state, _plus_ + - PercentType commands control the brightness, and on/off state, _plus_ + - OnOffType commands control the on/off state + + When the brightness is changed through a linked `Dimmer` item, the hue and saturation values must be preserved. + Likewise, when an `OFF` command is sent through a linked `Switch` item, it must adjust the brightness to 0% and/or set the on/off state to OFF, so that with the next ON (or brightness change), the hue and saturation values are restored untouched. + In the openHAB abstraction layer, 0% brightness is identical to `OFF`. + Sending an `ON` command to such a channel does _not_ have to switch to 100% brightness; depending on the device, it can also dim to the last brightness value (other than 0%) it had before. + + - _Single Dimmer Channel for Mid Capability Light:_ + If the light supports dimming, (but not full color), it must expose one single `Dimmer` channel only. + This should have the channel-type `system.brightness` thus inheriting default tags `[Control, Brightness]`. + Although the channel is of type `Dimmer`, items of type `Switch` can be linked to it. + The possibility to switch the light is therefore implicitly available so there is no need for an additional channel with item type `Switch`, even if the hardware might have separated switching and dimming in different commands. + Therefore the channel must be able to process all of the following types of command: + - PercentType commands which controls the brightness, and the on/off state, _plus_ + - OnOffType commands which controls the on/off state + + When an `ON` or `OFF` command is sent through a linked `Switch` item, the behaviour must be similar to the _Highest Capability Light_ scenario above. + + - _Single Switch Channel for Low Capability Light:_ +If the light supports on/off only, it must expose one single `Switch` channel only. +The channel-type should have default tags `[Switch, Light]` rather than `[Switch, Power]`. +This channel must be able to process the following type of command: + - OnOffType commands which controls the on/off state + + Please refer to the Hue API v2 Thing Handler for an [example implementation](https://github.com/openhab/openhab-addons/blob/main/bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/handler/Clip2ThingHandler.java#L384). + + - _Color Temperature Channel:_ +If the light also supports variable color temperature (in percent) the following applies. +Color temperature is nothing else than a color palette with a limited (linear) choice of colors. +However there is no dedicated item type for color temperature and it is tricky (though not impossible) to map color temperatures to HSB values. +So you cannot "overload" the `Color` channel in the same way as is done for brightness above. +Instead you must expose a separate `Dimmer` channel. +This should have the channel-type `system.color-temperature` thus inheriting default tags `[Control, ColorTemperature]`. +This channel is orthogonal to the brightness and on/off state, but not orthogonal to the HS part of the HSB. +So changing the color temperature may (or may not) have a consequent impact on the color channel. + + - _Absolute Color Temperature Channel:_ +If the light also supports absolute color temperature (in Kelvin or Mired/Mirek). +The case is similar to color temperature in percent above. +You can implement this by exposing another separate `Dimmer` channel. +This channel should have the channel-type `system.color-temperature-abs` thus inheriting the `Advanced` attribute. +This is especially useful when being used from within automation rules where different light bulbs from different vendors should be set to the very same color temperature. +Additionally the web UI has a dedicated picker widget for selecting color temperature in Kelvin. + + - _Extra (Advanced) Channels:_ +HSBType commands combine a mixture of color (HS), brightness (B) and on/off state (B>0) values in a single state variable. +There may be use cases that require pure access to these state variables independently. +So it is also allowed (optionally) to have advanced pure channels e.g. `colorOnly`, `brightnessOnly` and/or `onOffOnly`. +However such channels **must** have the `Advanced` attribute and **must** have no default semantic tags applied to them. 1. _I have an image in my binding and want to pass it to the framework. What is the best way to achieve this?_