Because of the very generic structure of MQTT, this binding allows you to add an arbitrary number
of so called "Generic MQTT Things" to organize yourself.
On each of those things you can add an arbitrary number of channels.
Remember that you need a configured broker Thing first!
You can add the following channels:
#### Supported Channels
* **string**: This channel can show the received text on the given topic and can send text to a given topic.
* **number**: This channel can show the received number on the given topic and can send a number to a given topic. It can have a min, max and step values.
* **dimmer**: This channel handles numeric values as percentages. It can have min, max and step values.
* **contact**: This channel represents an open/close state of a given topic.
* **switch**: This channel represents an on/off state of a given topic and can send an on/off value to a given topic.
* **colorRGB**: This channel handles color values in RGB format. (Deprecated)
* **colorHSB**: This channel handles color values in HSB format. (Deprecated)
* **color**: This channel handles color values in HSB, RGB or xyY (x,y,brightness) formats.
* **location**: This channel handles a location.
* **image**: This channel handles binary images in common java supported formats (bmp,jpg,png).
* **datetime**: This channel handles date/time values.
* **rollershutter**: This channel is for rollershutters.
* __stateTopic__: The MQTT topic that represents the state of the thing. This can be empty, the thing channel will be a state-less trigger then. You can use a wildcard topic like "sensors/+/event" to retrieve state from multiple MQTT topics.
* __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.
* __postCommand__: If `true`, the received MQTT value will not only update the state of linked items, but command it.
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.
* __qos__: QoS of this channel. Overrides the connection QoS (defined in broker connection).
* __trigger__: If `true`, the state topic will not update a state, but trigger a channel instead.
### Channel Type "string"
* __allowedStates__: An optional comma separated list of allowed states. Example: "ONE,TWO,THREE"
You can connect this channel to a String item.
### Channel Type "number"
* __min__: An optional minimum value.
* __max__: An optional maximum value.
* __step__: For decrease, increase commands the step needs to be known
* __unit__: Unit of measurement (optional). For supported units see [OpenHAB: List of Units](https://www.openhab.org/docs/concepts/units-of-measurement.html#list-of-units). Examples: "°C", "°F"
A decimal value (like 0.2) is send to the MQTT topic if the number has a fractional part.
If you always require an integer, please use the formatter.
* __on__: An optional string (like "ON"/"Open") that is recognized as minimum.
* __off__: An optional string (like "OFF"/"Close") that is recognized as maximum.
* __min__: A required minimum value.
* __max__: A required maximum value.
* __step__: For decrease, increase commands the step needs to be known
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`.
You can connect this channel to a Rollershutter or Dimmer item.
### Channel Type "contact", "switch"
* __on__: An optional number (like 1, 10) or a string (like "ON"/"Open") that is recognized as on/open state.
* __off__: An optional number (like 0, -10) or a string (like "OFF"/"Close") that is recognized as off/closed state.
The contact channel by default recognizes `"OPEN"` and `"CLOSED"`. You can connect this channel to a Contact item.
The switch channel by default recognizes `"ON"` and `"OFF"`. You can connect this channel to a Switch item.
If **on** and **off** are not configured it publishes the strings mentioned before respectively.
You can connect this channel to a Contact or Switch item.
### Channel Type "color"
* __color_mode__: A required string that defines the color representation: "hsb", "rgb" or "xyY" (x,y,brightness).
* __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%).
You can connect this channel to a Color, Dimmer and Switch item.
This channel will publish the color as comma separated list to the MQTT broker,
e.g. "112,54,123" for the RGB color mode (0-255 per component), "360,100,100" for the HSB color mode (0-359 for hue and 0-100 for saturation and brightness),
and "0.640074,0.329970,100" for the xyY color mode (0-1 for x and y, and 0-100 for brightness).
The channel expects values on the corresponding MQTT topic to be in this format as well.
### Channel Type "colorRGB", "colorHSB" (Deprecated)
* __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%).
You can connect this channel to a Color, Dimmer and Switch item.
This channel will publish the color as comma separated list to the MQTT broker,
e.g. "112,54,123" for an RGB channel (0-255 per component) and "360,100,100" for a HSB channel (0-359 for hue and 0-100 for saturation and brightness).
The channel expects values on the corresponding MQTT topic to be in this format as well.
### Channel Type "location"
You can connect this channel to a Location item.
The channel will publish the location as comma separated list to the MQTT broker,
* __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.
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.
You can connect this channel to a Rollershutter or Dimmer item.
## Rule Actions
This binding includes a rule action, which allows one to publish MQTT messages from within rules.
There is a separate instance for each MQTT broker (i.e. bridge), which can be retrieved through
```
val mqttActions = getActions("mqtt","mqtt:systemBroker:embedded-mqtt-broker")
```
where the first parameter always has to be `mqtt` and the second (`mqtt:systemBroker:embedded-mqtt-broker`) is the Thing UID of the broker that should be used.
Once this action instance is retrieved, you can invoke the `publishMQTT(String topic, String value, Boolean retained)` method on it:
In the first example a secure connection to a broker is defined. It pins the returned certificate and public key. If someone tries a man in the middle attack later on, this broker connection will recognize it and refuse a connection. Be aware that if your brokers certificate changes, you need to remove the connection entry and add it again.
The second connection is a plain, unsecured one. Use this only for local MQTT Brokers.
A third connection uses a username and password for authentication. The credentials are plain values on the wire, therefore you should only use this on a secure connection.
In a fourth connection, the public key pinning is enabled again. This time, a public key hash is provided to pin the connection to a specific server. It follows the form "hashname:hashvalue". Valid hashnames are SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 and all others listed in Java MessageDigest Algorithms.
### Example
Files can also be used to create topic things and channels and to combine them with a broker connection:
* Date/Time: To reference the item state multiple times, use "%1$". Use the "tX" conversion where "X" can be any of [h,H,m,M,I,k,l,S,p,B,b,A,a,y,Y,d,e].
- For an output of *May 23, 1995* use "%1$**tb** %1$**te**,%1$**tY**".
- For an output of *23.05.1995* use "%1$**td**.%1$**tm**.%1$**tY**".
- For an output of *23:15* use "%1$**tH**:%1$**tM**".
| __colorRGB__ | BigDecimal, BigDecimal, BigDecimal| "%1$d,%2$d,%3$d" | Parameters are **red**, **green** and **blue** components.
| __colorHSB__ | BigDecimal, BigDecimal, BigDecimal| "%1$d,%2$d,%3$d" | Parameters are **hue**, **saturation** and **brightness** components.
| __location__ | BigDecimal, BigDecimal | "%2$f,%3$f,%1$f" | Parameters are **altitude**, **latitude** and **longitude**, altitude is only in default pattern, if value is not '0'.
* If you use the Mosquitto broker: Please be aware that there is a relatively low setting for retained messages. If at some point messages stop being delivered change the setting.
