mirrors
/
Tasmota
mirror of https://github.com/arendst/Tasmota.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated MQTT (markdown)

Michael Ingraham 2019-10-15 13:11:50 -04:00
parent b38ad103a8
commit e46f4b08e9
1 changed files with 9 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
MQTT.md

@ -97,11 +97,13 @@ Telemetry data will be sent by prefix ```tele``` like ```tele/sonoff/SENSOR {"Ti
## MQTT Topic definition
Until version 5.0.5, the MQTT topic was defined rigidly by using the commands ``Prefix<x>`` and ``Topic`` resulting in a command topic string like ``cmnd/sonoff/Power``.
Starting with version 5.0.5, the MQTT topic is more flexible using command ``FullTopic`` and tokens to be placed within the user definable string up to 100 characters in size. The provided tokens are:
- ``%prefix%`` to be dynamically substituted by one of three prefixes as defined by commands ``Prefix1`` (default: "cmnd"), ``Prefix2`` (default: "stat") and ``Prefix3`` (default: "tele").
- ``%topic%`` to be dynamically substituted by one of five topics as defined by commands ``Topic``, ``GroupTopic``, ``ButtonTopic``, ``SwitchTopic`` and ``MqttClient``.
Starting with version 5.0.5, the MQTT topic is more flexible using command ``FullTopic`` and tokens to be placed within the user definable string (100 character limit). The tokens are substituted dynamically at run-time. The available substitution tokens are:
- ``%prefix%`` = one of three prefixes as defined by commands ``Prefix1`` *(default = `cmnd`)*, ``Prefix2`` *(default = `stat`)* and ``Prefix3`` *(default = `tele`)*.
- ``%topic%`` = one of five topics as defined by commands ``Topic``, ``GroupTopic``, ``ButtonTopic``, ``SwitchTopic`` and ``MqttClient``.
- ``%hostname%`` = the hostname of the device as defined through the web UI *(default = `%s-%04d`)* or via the `Hostname` command.
- ``%id%`` = the MAC address of the device.
If ``FullTopic`` does not contain `%topic%`, the device will not subscribe to ``GroupTopic`` and ``FallbackTopic``.
If ``FullTopic`` does not contain the `%topic%` token, the device will not subscribe to ``GroupTopic`` and ``FallbackTopic``.
Using the tokens the following example topics can be made:
- ``FullTopic %prefix%/%topic%/`` being the legacy situation up to version 5.0.5
@ -116,10 +118,9 @@ Tasmota uses 3 prefixes for forming a FullTopic:
- `stat` - reports back status or configuration message
- `tele` - reports telemetry info at specified intervals
>Theo's note:
>
>To solve possible MQTT topic loops I strongly suggest to use the ``%prefix%`` token in all of your FullTopics. It may work without `%prefix%` as I implemented some validation by forcing the use of a prefix in commands sent to the device but status and telemetry do not need a prefix. Just play with it and report strange problems I might solve in the future.
> **Guidance from Theo**:
> To solve possible MQTT topic loops it is strongly suggested that you use the ``%prefix%`` token in all of your FullTopics. It may work without `%prefix%` as some validation are implemented forcing the use of a prefix in commands sent to the device. Status and telemetry do not need a prefix.
The use of the ``%topic%`` token is also mandatory in case you want to use [`ButtonTopic`](commands#buttontopic) and/or [`SwitchTopic`](commands#switchtopic). It also provides for grouptopic and fallback topic functionality.
Recommendation: **Use both tokens at all time within your FullTopic string**
Recommendation: **Use `%prefix%` and `%topic%` tokens at all time within your FullTopic definition!**