diff --git a/MQTT.md b/MQTT.md index 866c029b..730a956b 100644 --- a/MQTT.md +++ b/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`` 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** \ No newline at end of file +Recommendation: **Use `%prefix%` and `%topic%` tokens at all time within your FullTopic definition!** \ No newline at end of file