diff --git a/bundles/org.openhab.binding.mqtt.generic/README.md b/bundles/org.openhab.binding.mqtt.generic/README.md index 92980fdd9b31e..dd7cecf893e8f 100644 --- a/bundles/org.openhab.binding.mqtt.generic/README.md +++ b/bundles/org.openhab.binding.mqtt.generic/README.md @@ -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. diff --git a/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/color-channel-config.xml b/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/color-channel-config.xml index 8c0d5b4ddc9a4..e657ac32dc0ab 100644 --- a/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/color-channel-config.xml +++ b/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/color-channel-config.xml @@ -92,18 +92,14 @@ - - 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). - 1 - true + + 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. - - 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). - 0 - true + + 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. diff --git a/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/dimmer-channel-config.xml b/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/dimmer-channel-config.xml index 5d799d6cef8f1..5c3d6cb3b8652 100644 --- a/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/dimmer-channel-config.xml +++ b/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/dimmer-channel-config.xml @@ -99,11 +99,13 @@ - A string (like "ON") that is sent to MQTT when an ON command is received, instead of an explicit 100%. + 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. - A string (like "OFF") that is sent to MQTT when an OFF command is received, instead of an explicit 0%. + 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. diff --git a/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/rollershutter-channel-config.xml b/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/rollershutter-channel-config.xml index 6c7d40c1fe792..014ebe2971f2a 100644 --- a/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/rollershutter-channel-config.xml +++ b/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/config/rollershutter-channel-config.xml @@ -88,18 +88,19 @@ 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. + 100, if inverted) will be sent instead. The Outgoing Value Format is not applied to this value. true 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. + (or 0, if inverted) will be sent instead. The Outgoing Value Format is not applied to this value. true - A string (like "STOP") that is sent when commanding the rollershutter to stop. + A string (like "STOP") that is sent when commanding the rollershutter to stop. The Outgoing Value Format + is not applied to this value. true diff --git a/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/i18n/mqtt.properties b/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/i18n/mqtt.properties index d04c947c10e95..870af83e9ac82 100644 --- a/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/i18n/mqtt.properties +++ b/bundles/org.openhab.binding.mqtt.generic/src/main/resources/OH-INF/i18n/mqtt.properties @@ -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