Improve modelling rules for light channels

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?_