[Documentation] Markdown improvements f to m (#13866)
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
committed by
GitHub
GitHub
parent
3c236b3103
commit
0e68936663
@@ -8,13 +8,13 @@ It is designed as a lightweight messaging protocol that uses publish/subscribe o
|
||||
|
||||
MQTT servers are called brokers and the clients are simply the connected devices.
|
||||
|
||||
* When a device (a client) wants to send data to the broker, we call this operation a “publish”.
|
||||
* When a device (a client) wants to receive data from the broker, we call this operation a “subscribe”.
|
||||
- When a device (a client) wants to send data to the broker, we call this operation a “publish”.
|
||||
- When a device (a client) wants to receive data from the broker, we call this operation a “subscribe”.
|
||||
|
||||
|
||||
|
||||
openHAB itself is not an MQTT Broker and needs to connect to one as a regular client.
|
||||
Therefore you must have configured a *Broker Thing* first via the **MQTT Broker Binding**!
|
||||
Therefore you must have configured a _Broker Thing_ first via the **MQTT Broker Binding**!
|
||||
|
||||
## MQTT Topics
|
||||
|
||||
@@ -55,54 +55,54 @@ Remember that you need a configured broker Thing first!
|
||||
|
||||
The following optional parameters can be set for the Thing:
|
||||
|
||||
* __availabilityTopic__: The MQTT topic that represents the availability of the thing. This can be the thing's LWT topic.
|
||||
* __payloadAvailable__: Payload of the `Availability Topic`, when the device is available. Default: `ON`.
|
||||
* __payloadNotAvailable__: Payload of the `Availability Topic`, when the device is *not* available. Default: `OFF`.
|
||||
* __transformationPattern__: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied to the incoming availability payload. Transformations can be chained by separating them with the mathematical intersection character "∩". The result of the transformations is then checked against `payloadAvailable` and `payloadNotAvailable`.
|
||||
- **availabilityTopic**: The MQTT topic that represents the availability of the thing. This can be the thing's LWT topic.
|
||||
- **payloadAvailable**: Payload of the `Availability Topic`, when the device is available. Default: `ON`.
|
||||
- **payloadNotAvailable**: Payload of the `Availability Topic`, when the device is _not_ available. Default: `OFF`.
|
||||
- **transformationPattern**: An optional transformation pattern like [JSONPath](https://goessner.net/articles/JsonPath/index.html#e2) that is applied to the incoming availability payload. Transformations can be chained by separating them with the mathematical intersection character "∩". The result of the transformations is then checked against `payloadAvailable` and `payloadNotAvailable`.
|
||||
|
||||
## Supported Channels
|
||||
|
||||
You can add the following 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.
|
||||
- **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.
|
||||
|
||||
## Channel Configuration
|
||||
|
||||
* __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.
|
||||
- **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.
|
||||
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.
|
||||
* __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.
|
||||
- **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"
|
||||
- **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"
|
||||
- **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.
|
||||
@@ -111,11 +111,11 @@ 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.
|
||||
* __min__: A required minimum value.
|
||||
* __max__: A required maximum value.
|
||||
* __step__: For decrease, increase commands the step needs to be known
|
||||
- **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**.
|
||||
|
||||
@@ -125,8 +125,8 @@ 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.
|
||||
- **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.
|
||||
@@ -137,10 +137,10 @@ 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,
|
||||
- **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%).
|
||||
@@ -155,9 +155,9 @@ The channel expects values on the corresponding MQTT topic to be in this format
|
||||
|
||||
### 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,
|
||||
- **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%).
|
||||
@@ -196,29 +196,28 @@ 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 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
|
||||
|
||||
```
|
||||
```java
|
||||
val mqttActions = getActions("mqtt","mqtt:broker:myBroker")
|
||||
```
|
||||
|
||||
where the first parameter always has to be `mqtt` and the second (`mqtt:broker:myBroker`) 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:
|
||||
|
||||
```
|
||||
```java
|
||||
mqttActions.publishMQTT("mytopic","myvalue", true)
|
||||
```
|
||||
|
||||
@@ -228,9 +227,9 @@ The retained argument is optional and if not supplied defaults to `false`.
|
||||
|
||||
## Configuration via Text Files
|
||||
|
||||
*broker.things* file:
|
||||
_broker.things_ file:
|
||||
|
||||
```
|
||||
```java
|
||||
mqtt:broker:mySecureBroker [ host="192.168.0.41", secure=true, certificatepin=true, publickeypin=true ]
|
||||
mqtt:broker:myInsecureBroker [ host="192.168.0.42", secure=false ]
|
||||
mqtt:broker:myAuthenticatedBroker [ host="192.168.0.43",secure=true, username="user", password="password" ]
|
||||
@@ -246,9 +245,9 @@ In a fourth connection, the public key pinning is enabled again. This time, a pu
|
||||
|
||||
Files can also be used to create topic things and channels and to combine them with a broker connection:
|
||||
|
||||
*mqtt.things* file:
|
||||
_mqtt.things_ file:
|
||||
|
||||
```
|
||||
```java
|
||||
Bridge mqtt:broker:myInsecureBroker [ host="192.168.0.42", secure=false ]
|
||||
|
||||
Thing mqtt:topic:mything "mything" (mqtt:broker:myInsecureBroker) {
|
||||
@@ -263,19 +262,19 @@ Thing mqtt:topic:mything "mything" (mqtt:broker:myInsecureBroker) {
|
||||
|
||||
If the availability status is available, it can be configured to set the Thing status:
|
||||
|
||||
```
|
||||
```java
|
||||
Thing mqtt:topic:bedroom1-switch (mqtt:broker:myInsecureBroker) [ availabilityTopic="tele/bedroom1-switch/LWT", payloadAvailable="Online", payloadNotAvailable="Offline" ] {
|
||||
Channels:
|
||||
Type switch : power [ stateTopic="stat/bedroom1-switch/RESULT", transformationPattern="REGEX:(.*POWER.*)∩JSONPATH:$.POWER", commandTopic="cmnd/bedroom1-switch/POWER" ]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Limitations
|
||||
|
||||
* The HomeAssistant Fan Components only support ON/OFF.
|
||||
* The HomeAssistant Cover Components only support OPEN/CLOSE/STOP.
|
||||
* The HomeAssistant Light Component does not support XY color changes.
|
||||
* The HomeAssistant Climate Components is not yet supported.
|
||||
- The HomeAssistant Fan Components only support ON/OFF.
|
||||
- The HomeAssistant Cover Components only support OPEN/CLOSE/STOP.
|
||||
- The HomeAssistant Light Component does not support XY color changes.
|
||||
- The HomeAssistant Climate Components is not yet supported.
|
||||
|
||||
## Incoming Value Transformation
|
||||
|
||||
@@ -310,34 +309,34 @@ The default is "%s" which means: Output the item state as string.
|
||||
|
||||
Here are a few examples:
|
||||
|
||||
* All uppercase: "%S". Just use the upper case letter for the conversion argument.
|
||||
* Apply a prefix: "myprefix%s"
|
||||
* Apply a suffix: "%s suffix"
|
||||
* Number precision: ".4f" for a 4 digit precision. Use the "+" flag to always add a sign: "+.4f".
|
||||
* Decimal to Hexadecimal/Octal/Scientific: For example "60" with "%x", "%o", "%e" becomes "3C", "74", "60".
|
||||
* 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**".
|
||||
- All uppercase: "%S". Just use the upper case letter for the conversion argument.
|
||||
- Apply a prefix: "myprefix%s"
|
||||
- Apply a suffix: "%s suffix"
|
||||
- Number precision: ".4f" for a 4 digit precision. Use the "+" flag to always add a sign: "+.4f".
|
||||
- Decimal to Hexadecimal/Octal/Scientific: For example "60" with "%x", "%o", "%e" becomes "3C", "74", "60".
|
||||
- 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**".
|
||||
|
||||
Default pattern applied for each type:
|
||||
| Type | Parameter | Pattern | Comment |
|
||||
| ---------------- | --------------------------------- | ------------------- | ------- |
|
||||
| __string__ | String | "%s" |
|
||||
| __number__ | BigDecimal | "%f" | The default will remove trailing zeros after the decimal point.
|
||||
| __dimmer__ | BigDecimal | "%f" | The default will remove trailing zeros after the decimal point.
|
||||
| __contact__ | String | -- | No pattern supported. Always **on** and **off** strings.
|
||||
| __switch__ | String | -- | No pattern supported. Always **on** and **off** strings.
|
||||
| __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'.
|
||||
| __image__ | -- | -- | No publishing supported.
|
||||
| __datetime__ | ZonedDateTime | "%1$tY-%1$tm-%1$tdT%1$tH:%1$tM:%1$tS.%1$tN" | Trailing zeros of the nanoseconds are removed.
|
||||
| __rollershutter__| String | "%s" | No pattern supported. Always **up**, **down**, **stop** string or integer percent value.
|
||||
| **string** | String | "%s" |
|
||||
| **number** | BigDecimal | "%f" | The default will remove trailing zeros after the decimal point.
|
||||
| **dimmer** | BigDecimal | "%f" | The default will remove trailing zeros after the decimal point.
|
||||
| **contact** | String | -- | No pattern supported. Always **on** and **off** strings.
|
||||
| **switch** | String | -- | No pattern supported. Always **on** and **off** strings.
|
||||
| **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'.
|
||||
| **image** | -- | -- | No publishing supported.
|
||||
| **datetime** | ZonedDateTime | "%1$tY-%1$tm-%1$tdT%1$tH:%1$tM:%1$tS.%1$tN" | Trailing zeros of the nanoseconds are removed.
|
||||
| **rollershutter**| String | "%s" | No pattern supported. Always **up**, **down**, **stop** string or integer percent value.
|
||||
|
||||
Any outgoing value transformation will **always** result in a __string__ value.
|
||||
Any outgoing value transformation will **always** result in a **string** value.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
* If you get the error "No MQTT client": Please update your installation.
|
||||
* 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.
|
||||
- If you get the error "No MQTT client": Please update your installation.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user