openhab · lsiepel · Oct 17, 2025 · Oct 16, 2025
@@ -84,7 +84,7 @@ You can add the following channels:
 - **transformationPattern**: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied to all incoming MQTT values.
 - **transformationPatternOut**: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied before publishing a value to MQTT.
 - **commandTopic**: The MQTT topic that commands are send to. This can be empty, the thing channel will be read-only then. Transformations are not applied for sending data.
-- **formatBeforePublish**: Format a value before it is published to the MQTT broker. The default is to just pass the channel/item state. If you want to apply a prefix, say "MYCOLOR,", you would use "MYCOLOR,%s". Currently only "%s" is supported.
+- **formatBeforePublish**: Format a value before it is published to the MQTT broker. The default is to just pass the channel/item state. If you want to apply a prefix, say "MYCOLOR,", you would use "MYCOLOR,%s". Currently only "%s" is supported. Note that this format does not apply to the special on/off command values for dimmer channels, or up/down/stop command values for rollershutter channels.
 - **postCommand**: If `true`, the received MQTT value will not only update the state of linked items, but command it.
   The default is `false`.
   You usually need this to be `true` if your item is also linked to another channel, say a KNX actor, and you want a received MQTT payload to command that KNX actor.
@@ -112,12 +112,15 @@ You can connect this channel to a Number item.
 
 ### Channel Type "dimmer"
 
-- **on**: An optional string (like "ON"/"Open") that is recognized as minimum.
-- **off**: An optional string (like "OFF"/"Close") that is recognized as maximum.
+- **on**: An optional string (like "ON"/"Open") that is sent for the `ON` command to tell the device to turn on to whatever value it thinks is useful (i.e. restore last state).
+- **off**: An optional string (like "OFF"/"Close") that is sent for the `OFF` command.
 - **min**: A required minimum value.
 - **max**: A required maximum value.
 - **step**: For decrease, increase commands the step needs to be known
 
+If **on** or **off** are not defined, an explicit 0 or 100 will be sent (after being scaled by **min** and **max** as appropriate).
+Note that **formatBeforePublish** will be ignored for these values, in case your device uses a vastly different format for these special commands than it does for number values.
+
 The value is internally stored as a percentage for a value between **min** and **max**.
 
 The channel will publish a value between `min` and `max`.
@@ -139,12 +142,9 @@ You can connect this channel to a Contact or Switch item.
 ### Channel Type "color"
 
 - **colorMode**: An optional string that defines the color representation: `HSB`, `RGB` or `XYY` (x,y,brightness). Defaults to `HSB` when not specified.
-- **on**: An optional string (like "BRIGHT") that is recognized as on state. (ON will always be recognized.)
-- **off**: An optional string (like "DARK") that is recognized as off state. (OFF will always be recognized.)
-- **onBrightness**: If you connect this channel to a Switch item and turn it on,
-
-color and saturation are preserved from the last state, but
-the brightness will be set to this configured initial brightness (default: 10%).
+- **on**: An optional string (like "ON"/"Open") that is sent for the `ON` command to tell the device to turn on to whatever value it thinks is useful (i.e. restore last state).
+- **off**: An optional string (like "OFF"/"Close") that is sent for the `OFF` command.
+- **onBrightness**: If you connect this channel to a Switch item and turn it on, color and saturation are preserved from the last state, but the brightness will be set to this configured initial brightness (default: 10%).
 
 You can connect this channel to a Color, Dimmer and Switch item.
 
@@ -154,6 +154,9 @@ and "0.640074,0.329970,100" for the xyY color mode (0-1 for x and y, and 0-100 f
 
 The channel expects values on the corresponding MQTT topic to be in this format as well.
 
+If **on** or **off** are not defined, a color command with the brightness set to 0 or 100 will be sent.
+Note that **formatBeforePublish** will be ignored for these values, in case your device uses a vastly different format for these special commands than it does for regular values.
+
 ### Channel Type "colorRGB", "colorHSB" (Deprecated)
 
 - **on**: An optional string (like "BRIGHT") that is recognized as on state. (ON will always be recognized.)
@@ -197,13 +200,13 @@ The channel expects values on the corresponding MQTT topic to be in this format
 
 ### Channel Type "rollershutter"
 
-- **on**: An optional string (like "Open") that is recognized as `UP` state.
-- **off**: An optional string (like "Close") that is recognized as `DOWN` state.
-- **stop**: An optional string (like "Stop") that is recognized as `STOP` state.
+- **on**: An optional string (like "Open") that is sent for the `UP` command.
+- **off**: An optional string (like "Close") that is sent for the `DOWN` command.
+- **stop**: An optional string (like "Stop") that is sent for the `STOP` command.
 - **stopCommandTopic**: An optional topic to send `STOP` commands to. If not set, `STOP` commands are sent to the main **commandTopic**.
 
-Internally `UP` is converted to 0%, `DOWN` to 100%.
-If strings are defined for these values, they are used for sending commands to the broker, too.
+If **on**, **off**, or **stop** are not defined, an explicit 0 or 100 will be sent for `UP` and `DOWN` respectively. `STOP` commands will be ignored entirely.
+Note that **formatBeforePublish** will be ignored for these values, in case your device uses a vastly different format for these special commands than it does for number values.
 
 You can connect this channel to a Rollershutter or Dimmer item.
 

@@ -92,18 +92,14 @@
 		</parameter>
 
 		<parameter name="on" type="text">
-			<label>On/Open Value</label>
-			<description>A number (like 1, 10) or a string (like "enabled") that is recognised as on/open state. You can use this
-				parameter for a second keyword, next to ON (OPEN respectively on a Contact).</description>
-			<default>1</default>
-			<advanced>true</advanced>
+			<label>Custom ON Command</label>
+			<description>A string (like "ON") that is sent to MQTT when an ON command is received, instead of a color command
+				with a brightness of 100%. The Outgoing Value Format is not applied to this value.</description>
 		</parameter>
 		<parameter name="off" type="text">
-			<label>Off/Closed Value</label>
-			<description>A number (like 0, -10) or a string (like "disabled") that is recognised as off/closed state. You can use
-				this parameter for a second keyword, next to OFF (CLOSED respectively on a Contact).</description>
-			<default>0</default>
-			<advanced>true</advanced>
+			<label>Custom OFF Command</label>
+			<description>A string (like "OFF") that is sent to MQTT when an OFF command is received, instead of a color command
+				with a brightness of 0%. The Outgoing Value Format is not applied to this value.</description>
 		</parameter>
 		<parameter name="onBrightness" type="integer" min="1" max="100">
 			<label>Initial Brightness</label>

@@ -99,11 +99,13 @@
 		</parameter>
 		<parameter name="on" type="text">
 			<label>Custom ON Command</label>
-			<description>A string (like "ON") that is sent to MQTT when an ON command is received, instead of an explicit 100%.</description>
+			<description>A string (like "ON") that is sent to MQTT when an ON command is received, instead of an explicit 100%.
+				The Outgoing Value Format is not applied to this value.</description>
 		</parameter>
 		<parameter name="off" type="text">
 			<label>Custom OFF Command</label>
-			<description>A string (like "OFF") that is sent to MQTT when an OFF command is received, instead of an explicit 0%.</description>
+			<description>A string (like "OFF") that is sent to MQTT when an OFF command is received, instead of an explicit 0%.
+				The Outgoing Value Format is not applied to this value.</description>
 		</parameter>
 	</config-description>
 </config-description:config-descriptions>
@@ -88,18 +88,19 @@
 		<parameter name="on" type="text">
 			<label>Up Command Value</label>
 			<description>A string (like "OPEN") that is sent when commanding the rollershutter to open. If not provided, 0 (or
-				100, if inverted) will be sent instead.</description>
+				100, if inverted) will be sent instead. The Outgoing Value Format is not applied to this value.</description>
 			<advanced>true</advanced>
 		</parameter>
 		<parameter name="off" type="text">
 			<label>Down Command Value</label>
 			<description>A string (like "CLOSE") that is sent when commanding the rollershutter to close. If not provided, 100
-				(or 0, if inverted) will be sent instead.</description>
+				(or 0, if inverted) will be sent instead. The Outgoing Value Format is not applied to this value.</description>
 			<advanced>true</advanced>
 		</parameter>
 		<parameter name="stop" type="text">
 			<label>Stop Command</label>
-			<description>A string (like "STOP") that is sent when commanding the rollershutter to stop.</description>
+			<description>A string (like "STOP") that is sent when commanding the rollershutter to stop. The Outgoing Value Format
+				is not applied to this value.</description>
 			<advanced>true</advanced>
 		</parameter>
 		<parameter name="onState" type="text">

@@ -46,10 +46,10 @@ thing-type.config.mqtt.color_channel.formatBeforePublish.label = Outgoing Value
 thing-type.config.mqtt.color_channel.formatBeforePublish.description = Format a value before it is published to the MQTT broker. The default is to just pass the channel/item state. If you want to apply a prefix, say "MYCOLOR,", you would use "MYCOLOR,%s". If you want to adjust the precision of a number to for example 4 digits, you would use "%.4f".
 thing-type.config.mqtt.color_channel.group.transformations.label = Transform Values
 thing-type.config.mqtt.color_channel.group.transformations.description = These configuration parameters allow you to alter a value before it is published to MQTT or before a received value is assigned to an item.
-thing-type.config.mqtt.color_channel.off.label = Off/Closed Value
-thing-type.config.mqtt.color_channel.off.description = A number (like 0, -10) or a string (like "disabled") that is recognised as off/closed state. You can use this parameter for a second keyword, next to OFF (CLOSED respectively on a Contact).
-thing-type.config.mqtt.color_channel.on.label = On/Open Value
-thing-type.config.mqtt.color_channel.on.description = A number (like 1, 10) or a string (like "enabled") that is recognised as on/open state. You can use this parameter for a second keyword, next to ON (OPEN respectively on a Contact).
+thing-type.config.mqtt.color_channel.off.label = Custom OFF Command
+thing-type.config.mqtt.color_channel.off.description = A string (like "OFF") that is sent to MQTT when an OFF command is received, instead of a color command with a brightness of 0%. The Outgoing Value Format is not applied to this value.
+thing-type.config.mqtt.color_channel.on.label = Custom ON Command
+thing-type.config.mqtt.color_channel.on.description = A string (like "ON") that is sent to MQTT when an ON command is received, instead of a color command with a brightness of 100%. The Outgoing Value Format is not applied to this value.
 thing-type.config.mqtt.color_channel.onBrightness.label = Initial Brightness
 thing-type.config.mqtt.color_channel.onBrightness.description = If you connect this channel to a Switch item and turn it on, color and saturation are preserved from the last state, but the brightness will be set to this configured initial brightness percentage.
 thing-type.config.mqtt.color_channel.postCommand.label = Is Command
@@ -78,9 +78,9 @@ thing-type.config.mqtt.dimmer_channel.max.description = This configuration repre
 thing-type.config.mqtt.dimmer_channel.min.label = Absolute Minimum
 thing-type.config.mqtt.dimmer_channel.min.description = This configuration represents the minimum of the allowed range. For a percentage channel that equals zero percent.
 thing-type.config.mqtt.dimmer_channel.off.label = Custom OFF Command
-thing-type.config.mqtt.dimmer_channel.off.description = A string (like "OFF") that is sent to MQTT when an OFF command is received, instead of an explicit 0%.
+thing-type.config.mqtt.dimmer_channel.off.description = A string (like "OFF") that is sent to MQTT when an OFF command is received, instead of an explicit 0%. The Outgoing Value Format is not applied to this value.
 thing-type.config.mqtt.dimmer_channel.on.label = Custom ON Command
-thing-type.config.mqtt.dimmer_channel.on.description = A string (like "ON") that is sent to MQTT when an ON command is received, instead of an explicit 100%.
+thing-type.config.mqtt.dimmer_channel.on.description = A string (like "ON") that is sent to MQTT when an ON command is received, instead of an explicit 100%. The Outgoing Value Format is not applied to this value.
 thing-type.config.mqtt.dimmer_channel.postCommand.label = Is Command
 thing-type.config.mqtt.dimmer_channel.postCommand.description = If the received MQTT value should not only update the state of linked items, but command them, enable this option.
 thing-type.config.mqtt.dimmer_channel.qos.label = QoS
@@ -136,11 +136,11 @@ thing-type.config.mqtt.rollershutter_channel.group.transformations.description =
 thing-type.config.mqtt.rollershutter_channel.invert.label = Invert
 thing-type.config.mqtt.rollershutter_channel.invert.description = Enable if your device uses 100 as UP and 0 as DOWN, instead of the normal openHAB convention of 0 as UP and 100 as DOWN.
 thing-type.config.mqtt.rollershutter_channel.off.label = Down Command Value
-thing-type.config.mqtt.rollershutter_channel.off.description = A string (like "CLOSE") that is sent when commanding the rollershutter to close. If not provided, 100 (or 0, if inverted) will be sent instead.
+thing-type.config.mqtt.rollershutter_channel.off.description = A string (like "CLOSE") that is sent when commanding the rollershutter to close. If not provided, 100 (or 0, if inverted) will be sent instead. The Outgoing Value Format is not applied to this value.
 thing-type.config.mqtt.rollershutter_channel.offState.label = Down State Value
 thing-type.config.mqtt.rollershutter_channel.offState.description = A string (like "CLOSED") that is recognised as DOWN state. You can use this parameter for a second keyword, next to DOWN. Defaults to the Down Command Value.
 thing-type.config.mqtt.rollershutter_channel.on.label = Up Command Value
-thing-type.config.mqtt.rollershutter_channel.on.description = A string (like "OPEN") that is sent when commanding the rollershutter to open. If not provided, 0 (or 100, if inverted) will be sent instead.
+thing-type.config.mqtt.rollershutter_channel.on.description = A string (like "OPEN") that is sent when commanding the rollershutter to open. If not provided, 0 (or 100, if inverted) will be sent instead. The Outgoing Value Format is not applied to this value.
 thing-type.config.mqtt.rollershutter_channel.onState.label = Up State Value
 thing-type.config.mqtt.rollershutter_channel.onState.description = A string (like "OPENED") that is recognised as UP state. You can use this parameter for a second keyword, next to UP. Defaults to the Up Command Value.
 thing-type.config.mqtt.rollershutter_channel.postCommand.label = Is Command
@@ -155,7 +155,7 @@ thing-type.config.mqtt.rollershutter_channel.retained.description = The value wi
 thing-type.config.mqtt.rollershutter_channel.stateTopic.label = MQTT State Topic
 thing-type.config.mqtt.rollershutter_channel.stateTopic.description = An MQTT topic that this thing will subscribe to, to receive the state. This can be left empty, the channel will be state-less command-only channel.
 thing-type.config.mqtt.rollershutter_channel.stop.label = Stop Command
-thing-type.config.mqtt.rollershutter_channel.stop.description = A string (like "STOP") that is sent when commanding the rollershutter to stop.
+thing-type.config.mqtt.rollershutter_channel.stop.description = A string (like "STOP") that is sent when commanding the rollershutter to stop. The Outgoing Value Format is not applied to this value.
 thing-type.config.mqtt.rollershutter_channel.stopCommandTopic.label = MQTT Stop Command Topic
 thing-type.config.mqtt.rollershutter_channel.stopCommandTopic.description = An MQTT topic that this thing will send a STOP command to. If not set, it will send STOP commands to the main commandTopic.
 thing-type.config.mqtt.rollershutter_channel.transformExtentsToString.label = Transform Commands at Extents to String