mirror of https://github.com/arendst/Tasmota.git
Added MQTT by mushing parts of all MQTT articles together
blakadder
parent
416814bb42
commit
a8be060dbb
|
|
@ -0,0 +1,120 @@
|
|||
MQTT is the recommended protocol for controlling your devices. If you have no previous knowledge of MQTT you can learn more from [MQTT Overview](MQTT-Overview) or get a complete course in the [MQTT Essentials](http://www.hivemq.com/mqtt-essentials/) article series. After you have a working [MQTT broker](https://www.google.com/search?q=setting+up+an+mqtt+broker) you need to configure Tasmota to communicate with it.
|
||||
|
||||
## Configure MQTT
|
||||
If you flashed a precompiled .bin or didn't enter MQTT info in `user_config_override.h` before compiling you need to configure MQTT on your device first.
|
||||
|
||||
### Configure MQTT using WebUI
|
||||
Go to **Configuration -> Configure Other** and make sure **"MQTT Enable"** box is checked.<BR>
|
||||
Once MQTT is enabled you need to set it up using **Configuration -> Configure MQTT**.
|
||||
|
||||
|
||||
|
||||
For a basic setup you only need to set **Host**, **User** and **Password** but it is recommended to change **Topic** to avoid issues. Each device should have a unique **Topic**.
|
||||
|
||||
- **Host** = your MQTT broker address or IP
|
||||
- **Port** = your MQTT broker port (default port is set to 1883)
|
||||
- **Client** = device's unique identifier, do not change if not sure what it is for
|
||||
- **User** = username for authenticating on your MQTT broker
|
||||
- **Password** = password for authenticating on your MQTT broker
|
||||
- **Topic** = unique identifying topic for your device (e.g. `hallswitch`, `kitchen-light`). `%topic%` in wiki references to this.
|
||||
- **FullTopic** = [full topic definition](#mqtt-topic-definition), do not change if not sure what it is for
|
||||
|
||||
### Configure MQTT using Backlog
|
||||
|
||||
Using a serial connection or the WebUI Console you can issue (or even better, paste a premade) Backlog command for quick and easy MQTT setup.
|
||||
|
||||
```
|
||||
Backlog mqtthost <mqtt_broker_address>; mqttport <mqtt_broker_port>; mqttuser <username>; mqttpassword <password>; topic <device_topic>
|
||||
```
|
||||
|
||||
After a reboot all necessary MQTT settings are configured. Don't forget, you can use Backlog for all [commands](#commands)!
|
||||
|
||||
## Commands over MQTT
|
||||
To send commands and view responses you'll need an [MQTT client](http://www.hivemq.com/blog/seven-best-mqtt-client-tools).
|
||||
|
||||
Commands over MQTT are issued to Tasmota by using `cmnd/%topic%/<command> <parameter>`. If there is no `<parameter>` (an empty MQTT message/payload), a query is sent for current status of the `<command>`.
|
||||
|
||||
> If you are using *mosquitto_pub*, you can issue an empty payload using the `-n` command line option.
|
||||
> If your MQTT client cannot issue an empty payload, you can use the single character `?` instead.
|
||||
|
||||
|
||||
### Command flow
|
||||
|
||||
The following example will go in depth on what happens when you send an MQTT command.
|
||||
|
||||
A device was flashed and configured with the **FullTopic** as default `%prefix%/%topic%/` and the **Topic** set to `sonoff-switch`. We want to see current status of the switch and change it.
|
||||
|
||||
By looking at the [commands](commands) table we can learn about the [Power](commands#power) command and options associated with it.
|
||||
* Ask the device for status:
|
||||
```java
|
||||
cmnd/sonoff-switch/Power ← // an empty message/payload sends a status query
|
||||
↳ cmnd/sonoff-switch/RESULT → {"POWER":"OFF"}
|
||||
↳ stat/sonoff-switch/POWER → OFF
|
||||
```
|
||||
We can see that the module's relay is turned off.
|
||||
|
||||
* Send a command to toggle the switch:
|
||||
```java
|
||||
cmnd/sonoff-switch/Power ← "TOGGLE"
|
||||
↳ // Power for relay 1 is toggled
|
||||
↳ cmnd/sonoff-switch/RESULT → {"POWER":"ON"}
|
||||
↳ stat/sonoff-switch/POWER → ON
|
||||
```
|
||||
We've sent the toggle command and received confirmation that the switch is turned on.
|
||||
|
||||
### Examples
|
||||
In the following examples `%topic%` is `sonoff` for demonstration purposes:
|
||||
|
||||
- The relay can be controlled with `cmnd/sonoff/power on`, ```cmnd/sonoff/power off``` or ```cmnd/sonoff/power toggle```. Sonoff will send a MQTT status message like ```stat/sonoff/POWER ON```.
|
||||
|
||||
- The power state message can be sent with the retain flag set. Enable this with ```cmnd/sonoff/PowerRetain on```.
|
||||
|
||||
- The telemetry messages can also be sent with the retain flag, but this is a compile time option. See [#1071](https://github.com/arendst/Sonoff-Tasmota/issues/1071).
|
||||
|
||||
- For sonoff dual or 4CH the relays need to be addressed with ```cmnd/sonoff/power{n}```, where {n} is the relay number from 1 to 2 (Sonoff Dual) or from 1 to 4 (Sonoff 4CH). `cmnd/sonoff/power4 off` turns off the 4th relay on a Sonoff 4CH.
|
||||
|
||||
- QTT topic can be changed with ```cmnd/sonoff/topic sonoff1``` which reboots sonoff and changes the `%topic%` to `sonoff1`. From that point on MQTT commands should look like ```cmnd/sonoff1/power on```.
|
||||
|
||||
- The OTA firmware location can be made known to sonoff with ```cmnd/sonoff/otaurl http://thehackbox.org/tasmota/release/sonoff.bin```. Reset to default with ```cmnd/sonoff/otaurl 1```.
|
||||
|
||||
- Upgrade OTA firmware from the OtaUrl server with ```cmnd/sonoff/upgrade 1```.
|
||||
|
||||
- Show all status information with ```cmnd/sonoff/status 0```.
|
||||
|
||||
- The button can send a MQTT message to the broker that in turn will switch the relay. To configure this you need to perform ```cmnd/sonoff/ButtonTopic sonoff``` where sonoff equals to Topic. The message can also be provided with the retain flag by ```cmnd/sonoff/ButtonRetain on```.
|
||||
|
||||
- Sonoff Pow status can be retreived with ```cmnd/sonoff/status 8``` or periodically every 5 minutes using ```cmnd/sonoff/TelePeriod 300```.
|
||||
|
||||
- When a Sonoff Pow threshold like PowerLow has been met a message ```tele/sonoff/POWER_LOW ON``` will be sent. When the error is corrected a message ```tele/sonoff/POWER_LOW OFF``` will be sent.
|
||||
|
||||
While most MQTT commands will result in a message in JSON format the power status feedback will always be returned like ```stat/sonoff/POWER ON``` too.
|
||||
|
||||
Telemetry data will be sent by prefix ```tele``` like ```tele/sonoff/SENSOR {"Time":"2017-02-16T10:13:52", "DS18B20":{"Temperature":20.6}}```
|
||||
|
||||
## 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``.
|
||||
|
||||
Using the tokens the following example topics can be made:
|
||||
- ``FullTopic %prefix%/%topic%/`` being the legacy situation up to version 5.0.5
|
||||
- ``FullTopic tasmota/%topic%/%prefix%/``
|
||||
- ``FullTopic tasmota/bedroom/%topic%/%prefix%/``
|
||||
- ``FullTopic penthouse/bedroom1/bathroom2/%topic%/%prefix%/``
|
||||
|
||||
### %prefix%
|
||||
Tasmota uses 3 prefixes for forming a FullTopic:
|
||||
|
||||
- `cmnd` - prefix to issue commands; ask for status
|
||||
- `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.
|
||||
|
||||
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**
|
||||
Loading…
Reference in New Issue