[mqtt] Update documentation for postCommand / Is Command

bundles/org.openhab.binding.mqtt/README.md

@@ -163,7 +163,8 @@ You can add the following channels:
 - **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. 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.
+- **postCommand**: If `true`, the received MQTT value is processed as a command instead of a state update.
+  Profiles that react only to state updates, such as `timestamp-update` and `timestamp-change`, do not process incoming values when this option is enabled.
   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.
 - **retained**: The value will be published to the command topic as retained message. A retained value stays on the broker and can even be seen by MQTT clients that are subscribing at a later point in time.

bundles/org.openhab.binding.mqtt/src/main/resources/OH-INF/config/color-channel-config.xml

@@ -85,8 +85,9 @@
 		</parameter>
 		<parameter name="postCommand" type="boolean">
 			<label>Is Command</label>
-			<description>If the received MQTT value should not only update the state of linked items, but command them, enable
-				this option.</description>
+			<description>Process the received MQTT value as a command instead of a state update. Profiles that react only to
+				state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is
+				enabled.</description>
 			<default>false</default>
 			<advanced>true</advanced>
 		</parameter>

bundles/org.openhab.binding.mqtt/src/main/resources/OH-INF/config/dimmer-channel-config.xml

@@ -74,8 +74,9 @@
 		</parameter>
 		<parameter name="postCommand" type="boolean">
 			<label>Is Command</label>
-			<description>If the received MQTT value should not only update the state of linked items, but command them, enable
-				this option.</description>
+			<description>Process the received MQTT value as a command instead of a state update. Profiles that react only to
+				state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is
+				enabled.</description>
 			<default>false</default>
 			<advanced>true</advanced>
 		</parameter>

bundles/org.openhab.binding.mqtt/src/main/resources/OH-INF/config/number-channel-config.xml

@@ -74,8 +74,10 @@
 		</parameter>
 		<parameter name="postCommand" type="boolean">
 			<label>Is Command</label>
-			<description>If the received MQTT value should not only update the state of linked items, but command them, enable
-				this option. Note that if the value is NaN (interpreted as UNDEF), it can only update; commands are not possible.</description>
+			<description>Process the received MQTT value as a command instead of a state update. Profiles that react only to
+				state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is
+				enabled. NaN is interpreted as UNDEF and is always processed as a state update because UNDEF cannot be sent as a
+				command.</description>
 			<default>false</default>
 			<advanced>true</advanced>
 		</parameter>

bundles/org.openhab.binding.mqtt/src/main/resources/OH-INF/config/rollershutter-channel-config.xml

@@ -80,8 +80,9 @@
 		</parameter>
 		<parameter name="postCommand" type="boolean">
 			<label>Is Command</label>
-			<description>If the received MQTT value should not only update the state of linked items, but command them, enable
-				this option.</description>
+			<description>Process the received MQTT value as a command instead of a state update. Profiles that react only to
+				state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is
+				enabled.</description>
 			<default>false</default>
 			<advanced>true</advanced>
 		</parameter>

bundles/org.openhab.binding.mqtt/src/main/resources/OH-INF/config/string-channel-config.xml

@@ -74,8 +74,9 @@
 		</parameter>
 		<parameter name="postCommand" type="boolean">
 			<label>Is Command</label>
-			<description>If the received MQTT value should not only update the state of linked items, but command them, enable
-				this option.</description>
+			<description>Process the received MQTT value as a command instead of a state update. Profiles that react only to
+				state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is
+				enabled.</description>
 			<default>false</default>
 			<advanced>true</advanced>
 		</parameter>

bundles/org.openhab.binding.mqtt/src/main/resources/OH-INF/config/switch-channel-config.xml

@@ -74,8 +74,9 @@
 		</parameter>
 		<parameter name="postCommand" type="boolean">
 			<label>Is Command</label>
-			<description>If the received MQTT value should not only update the state of linked items, but command them, enable
-				this option.</description>
+			<description>Process the received MQTT value as a command instead of a state update. Profiles that react only to
+				state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is
+				enabled.</description>
 			<default>false</default>
 			<advanced>true</advanced>
 		</parameter>

bundles/org.openhab.binding.mqtt/src/main/resources/OH-INF/i18n/mqtt.properties

@@ -135,7 +135,7 @@ thing-type.config.mqtt.color_channel.on.description = A string (like "ON") that
 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
-thing-type.config.mqtt.color_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.color_channel.postCommand.description = Process the received MQTT value as a command instead of a state update. Profiles that react only to state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is enabled.
 thing-type.config.mqtt.color_channel.qos.label = QoS
 thing-type.config.mqtt.color_channel.qos.description = MQTT QoS of this channel (0, 1, 2). Default is QoS of the broker connection.
 thing-type.config.mqtt.color_channel.qos.option.0 = At most once (best effort delivery "fire and forget")
@@ -168,7 +168,7 @@ thing-type.config.mqtt.dimmer_channel.off.description = A string (like "OFF") th
 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%. 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.postCommand.description = Process the received MQTT value as a command instead of a state update. Profiles that react only to state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is enabled.
 thing-type.config.mqtt.dimmer_channel.qos.label = QoS
 thing-type.config.mqtt.dimmer_channel.qos.description = MQTT QoS of this channel (0, 1, 2). Default is QoS of the broker connection.
 thing-type.config.mqtt.dimmer_channel.qos.option.0 = At most once (best effort delivery "fire and forget")
@@ -199,7 +199,7 @@ thing-type.config.mqtt.number_channel.min.description = This configuration repre
 thing-type.config.mqtt.number_channel.nullValue.label = NULL Value
 thing-type.config.mqtt.number_channel.nullValue.description = If the received MQTT value matches this, treat it as NULL.
 thing-type.config.mqtt.number_channel.postCommand.label = Is Command
-thing-type.config.mqtt.number_channel.postCommand.description = If the received MQTT value should not only update the state of linked items, but command them, enable this option. Note that if the value is NaN (interpreted as UNDEF), it can only update; commands are not possible.
+thing-type.config.mqtt.number_channel.postCommand.description = Process the received MQTT value as a command instead of a state update. Profiles that react only to state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is enabled. NaN is interpreted as UNDEF and is always processed as a state update because UNDEF cannot be sent as a command.
 thing-type.config.mqtt.number_channel.qos.label = QoS
 thing-type.config.mqtt.number_channel.qos.description = MQTT QoS of this channel (0, 1, 2). Default is QoS of the broker connection.
 thing-type.config.mqtt.number_channel.qos.option.0 = At most once (best effort delivery "fire and forget")
@@ -238,7 +238,7 @@ thing-type.config.mqtt.rollershutter_channel.on.description = A string (like "OP
 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
-thing-type.config.mqtt.rollershutter_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.rollershutter_channel.postCommand.description = Process the received MQTT value as a command instead of a state update. Profiles that react only to state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is enabled.
 thing-type.config.mqtt.rollershutter_channel.qos.label = QoS
 thing-type.config.mqtt.rollershutter_channel.qos.description = MQTT QoS of this channel (0, 1, 2). Default is QoS of the broker connection.
 thing-type.config.mqtt.rollershutter_channel.qos.option.0 = At most once (best effort delivery "fire and forget")
@@ -271,7 +271,7 @@ thing-type.config.mqtt.string_channel.ignoreValue.description = If the received
 thing-type.config.mqtt.string_channel.nullValue.label = NULL Value
 thing-type.config.mqtt.string_channel.nullValue.description = If the received MQTT value matches this, treat it as NULL.
 thing-type.config.mqtt.string_channel.postCommand.label = Is Command
-thing-type.config.mqtt.string_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.string_channel.postCommand.description = Process the received MQTT value as a command instead of a state update. Profiles that react only to state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is enabled.
 thing-type.config.mqtt.string_channel.qos.label = QoS
 thing-type.config.mqtt.string_channel.qos.description = MQTT QoS of this channel (0, 1, 2). Default is QoS of the broker connection.
 thing-type.config.mqtt.string_channel.qos.option.0 = At most once (best effort delivery "fire and forget")
@@ -300,7 +300,7 @@ thing-type.config.mqtt.switch_channel.off.description = A number (like 0, -10) o
 thing-type.config.mqtt.switch_channel.on.label = Custom On/Open Value
 thing-type.config.mqtt.switch_channel.on.description = A number (like 1, 10) or a string (like "enabled") that is additionally 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.switch_channel.postCommand.label = Is Command
-thing-type.config.mqtt.switch_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.switch_channel.postCommand.description = Process the received MQTT value as a command instead of a state update. Profiles that react only to state updates, such as timestamp-update and timestamp-change, do not process incoming values when this option is enabled.
 thing-type.config.mqtt.switch_channel.qos.label = QoS
 thing-type.config.mqtt.switch_channel.qos.description = MQTT QoS of this channel (0, 1, 2). Default is QoS of the broker connection.
 thing-type.config.mqtt.switch_channel.qos.option.0 = At most once (best effort delivery "fire and forget")