You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: developers/addons/faq.md
+63-28Lines changed: 63 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -51,34 +51,69 @@ If you do not find an answer to your question, do not hesitate to ask it on the
51
51
52
52
### Modelling Channels
53
53
54
-
1._How do I model a dimmable light?_
55
-
56
-
A dimmable light should only have a single channel of type `system.brightness` for its control.
57
-
Note that although this channel type is declared for item type 'Dimmer', it is perfectly possible to link a `Switch`
58
-
item to it, additionally to a `Dimmer` item.
59
-
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.
60
-
In the openHAB abstraction layer, 0% brightness is identical to OFF.
61
-
Sending an ON command to such a channel does not have to switch to 100% brightness, though.
62
-
Depending on whether the device supports it, it can also dim to the last brightness value (other than 0%) it was in before.
63
-
64
-
1._How do I model a color light?_
65
-
66
-
This is very similar to dimmable lights, just that this time the channel should be of type `system.color`.
67
-
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.
68
-
When the brightness is changed (through a linked `Dimmer` item), the hue and saturation values are simply kept.
69
-
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.
70
-
71
-
1._How do I deal with a color temperature feature of a bulb?
72
-
73
-
In theory, color temperature is nothing else than a color palette with a limited (linear) choice of colors.
74
-
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.
75
-
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.
76
-
77
-
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.
78
-
`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.
79
-
80
-
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.
81
-
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.
54
+
1._How do I model a light with color, brightness, on/off, and/or color temperature channels?_
55
+
56
+
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.
57
+
So when you model a light in your binding, you must follow the _**"Highest Capability Channel Rule"**_.
58
+
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:
59
+
60
+
- _Single Color Channel for Top Capability Light:_
61
+
If the light supports full color, it must expose one single `Color` channel only.
62
+
This should have the channel-type `system.color` therefore inheriting default tags `[Control, Color]`.
63
+
Although the channel is of type `Color`, items of type `Dimmer` or `Switch` can be linked to it.
64
+
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.
65
+
Therefore the channel must be able to process all of the following types of command:
66
+
- HSBType commands control the color hue, brightness, and on/off state, _plus_
67
+
- PercentType commands control the brightness, and on/off state, _plus_
68
+
- OnOffType commands control the on/off state
69
+
70
+
When the brightness is changed through a linked `Dimmer` item, the hue and saturation values must be preserved.
71
+
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.
72
+
In the openHAB abstraction layer, 0% brightness is identical to `OFF`.
73
+
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.
74
+
75
+
- _Single Dimmer Channel for Mid Capability Light:_
76
+
If the light supports dimming, (but not full color), it must expose one single `Dimmer` channel only.
77
+
This should have the channel-type `system.brightness` thus inheriting default tags `[Control, Brightness]`.
78
+
Although the channel is of type `Dimmer`, items of type `Switch` can be linked to it.
79
+
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.
80
+
Therefore the channel must be able to process all of the following types of command:
81
+
- PercentType commands which controls the brightness, and the on/off state, _plus_
82
+
- OnOffType commands which controls the on/off state
83
+
84
+
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.
85
+
86
+
- _Single Switch Channel for Low Capability Light:_
87
+
If the light supports on/off only, it must expose one single `Switch` channel only.
88
+
The channel-type should have default tags `[Switch, Light]` rather than `[Switch, Power]`.
89
+
This channel must be able to process the following type of command:
90
+
- OnOffType commands which controls the on/off state
91
+
92
+
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).
93
+
94
+
- _Color Temperature Channel:_
95
+
If the light also supports variable color temperature (in percent) the following applies.
96
+
Color temperature is nothing else than a color palette with a limited (linear) choice of colors.
97
+
However there is no dedicated item type for color temperature and it is tricky (though not impossible) to map color temperatures to HSB values.
98
+
So you cannot "overload" the `Color` channel in the same way as is done for brightness above.
99
+
Instead you must expose a separate `Dimmer` channel.
100
+
This should have the channel-type `system.color-temperature` thus inheriting default tags `[Control, ColorTemperature]`.
101
+
This channel is orthogonal to the brightness and on/off state, but not orthogonal to the HS part of the HSB.
102
+
So changing the color temperature may (or may not) have a consequent impact on the color channel.
103
+
104
+
- _Absolute Color Temperature Channel:_
105
+
If the light also supports absolute color temperature (in Kelvin or Mired/Mirek).
106
+
The case is similar to color temperature in percent above.
107
+
You can implement this by exposing another separate `Dimmer` channel.
108
+
This channel should have the channel-type `system.color-temperature-abs` thus inheriting the `Advanced` attribute.
109
+
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.
110
+
Additionally the web UI has a dedicated picker widget for selecting color temperature in Kelvin.
111
+
112
+
- _Extra (Advanced) Channels:_
113
+
HSBType commands combine a mixture of color (HS), brightness (B) and on/off state (B>0) values in a single state variable.
114
+
There may be use cases that require pure access to these state variables independently.
115
+
So it is also allowed (optionally) to have advanced pure channels e.g. `colorOnly`, `brightnessOnly` and/or `onOffOnly`.
116
+
However such channels **must** have the `Advanced` attribute and **must** have no default semantic tags applied to them.
82
117
83
118
1._I have an image in my binding and want to pass it to the framework. What is the best way to achieve this?_
0 commit comments