mqtt - FengtianGu/Sonoff-Tasmota GitHub Wiki

MQTT is the recommended protocol for controlling your devices. If you have no previous knowledge of it you can learn more from MQTT Overview or get a complete course in the MQTT Essentials article series. After you have a working MQTT broker you need to configure Tasmota to communicate with it.

If you flashed a precompiled .bin or didn't enter MQTT info in user_config_override.h before compiling you have to configure it on your device first.

Go to Configuration -> Configure Other and make sure "MQTT Enable" box is checked.
Once MQTT is enabled you need to set it up using Configuration -> Configure MQTT.

While here, you might as well change the Friendly Name into something more descriptive than generic "Sonoff". This is a must for Home Assistant autodiscovery feature.

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, do not change if not sure what it is for

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!

To send commands and view responses you'll need an MQTT client.

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.

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 table we can learn about the Power command and options associated with it.

• Ask the device for status:

  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:

  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.

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.

• 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}}

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%/

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 and/or SwitchTopic. It also provides for grouptopic and fallback topic functionality.

Recommendation: Use both tokens at all time within your FullTopic string