Using Theo Arends’ Sonoff/MQTT Package [“TASMOTA”]

PREFACE – Theo has put a lot of hard work into TASMOTA and continues to update and improve the package at a quite incredible rate.  For instance, Theo changed the major revision number from “4” to “5” on the 25th of April, 2017.  Between then and the time of adding this note (19th of July, 2017), he has made 92 updates that warranted an entry in the release notes and 42 of those changes were additions.

This article first appeared in April of 2016, so it is fairly ancient.  The basic information here (such as the three main methods for interacting with your Sonoff) is still correct, but you need to realize that any references to menu items or MQTT commands have very probably changed since it was first written.  I just can’t keep up with Theo.  🙂

Please do have a quick look at the “_releasenotes.ino” file in the sonoff subdirectory of the Sonoff-Tasmota package to get an idea of what recent changes there are, as well as checking the package README.md for the major news (ie:- Theo has recently added Alexa support to Sonoff).

Having said that, I hope these articles will help you to become more familiar with TASMOTA and with the Sonoff devices themselves.  Please read on…

---

 

This is a continuation to the previous post on updating your Sonoff to use Theo Arends’ Sonoff-MQTT-OTA-Arduino package.  Theo’s package has so many features that it takes a little time to get familiar with it.  I’ve always found that a couple of examples are worth more than a scad of explanation (would that the Unix manual pages had made an “EXAMPLES” section mandatory), so rather than leave everyone floundering around on their own, I thought I’d note down some of the examples which I’ve found to work so far.

Before we start, you should realize that there are three main ways to interact with the device:-  the button/LED pair,  the serial interface (which we used to upload the firmware in the previous post) and MQTT.  All of these interfaces interact with each  other to some extent.  So, for instance, pressing the button to toggle the state of the relay will flash the LED to indicate a successful update and automatically generate output to the serial port as well as an MQTT message.  Sending the unit an MQTT command to toggle the relay will also generate a state-change message to the serial port and flash the LED.  Using the serial port to toggle the state of the relay will automatically generate an MQTT state-change message and flash the LED.  So we effectively have three input/output channels with the input from any one of them producing status output to all three.

The simplest of the input methods is the button.  A change in the number of sequential button presses, or in the duration of the press, will produce a limited number of state changes.

• Pressing the button one will toggle the relay state.
• Pressing the button twice in a row will toggle the relay state twice.  🙂
• Pressing the button thrice in a row will initiate Smart-Config mode for 100-seconds (to allow for more complex configuration changes to be made from an Android device).
• Pressing the button four times in a row will initiate  an over-the-air (OTA) update from a previously configured source.
• Finally, pressing the button and holding it down for more than 4-seconds will reset the Sonoff configuration to the compiled-in defaults and initiate a restart of the device.

The most versatile input method is actually the serial console, but to activate the console you need to disconnect the device from the mains and take off the covers to gain access to the serial header (programming) pins.  Obviously this is most useful with a new device when doing the initial configuration;  it’s not really practicable once the device has been reassembled and is in use.  Having said that, this is the method I’d recommend  for doing your own initial exploration of the Sonoff-MQTT-OTA-Arduino firmware.  Once you’ve completed the initial installation of the firmware, take a few minutes while the USB<->TTL converter is still connected and use the Arduino-IDE “Serial Monitor” (under the “Tools” pull-down menu) to interact with your Sonoff.  Make sure that the serial monitor window has focus and that the cursor is flashing in the input sub-window at the top.

I’m going to emphasize here once again that there shouldn’t be anything at all, other than the serial connector leads from the USB<->TTL converter, plugged into your Sonoff at this point.

When your Sonoff first boots into Theo Arends’ Sonoff-MQTT-OTA-Arduino firmware (hereafter referred to as “TASMOTA”) you’ll see a very brief status message something like this:-

NAME = Sonoff switch
VERSION = 1.0.6
FALLBACKTOPIC = DVES_0CB0CB

Where the version number is the version of TASMOTA and the fallback-topic is the “if-everything-else-fails” way of addressing this specific module from MQTT.  We’ll touch on that latter function again briefly, later on.

You should now be able to type in commands in the serial monitor window and see the results displayed there directly.  A simple carriage return will produce a “usage” message with all of the possible commands listed (in l single line which, unfortunately, will scroll off the side of the serial monitor window):-

SYNTAX = Status, Upgrade, Otaurl, Restart, Reset, Smartconfig, SSId, Password, Host, GroupTopic, Topic, Timezone, Light, Power

Theo has a couple of nice tables in the README of his GitHub repository which explain each of these, so I’m going to limit myself to a couple of the more useful ones here.

Status

This command does what you would expect, giving you some information about the current state of your Sonoff module.  This command takes options though, so you get different results depending upon whether you run the command without any options at all, or with the different options “1” or “2”.

status
STATUS = 1.0.6, sonoff, POWER, 0, 9


status 1
STATUS = sonoffs, DVES_0CB0CB, http://Your-OTA-Server.And.Domain:80/api/arduino/sonoff.ino.bin, Your-SSID, Your-Passwd, Your-MQTT-Server.And.Domain, 1, 11

status 2
STATUS = Version 1.0.6, Boot 4, SDK 1.5.1(e67da894)

As you can see, “status” without any options is succinct.  It shows the TASMOTA version, the current addressable topic name (for this module when using MQTT) which defaults to “sonoff”, the sub-topic name (in this case “POWER”), the relay status (0 = off) and the current timezone (9 = JST/Tokyo).

Status with the “1” option gives us verbose output on the current configuration of the unit.  It shows the current addressable group-topic (“sonoffs”).  The group-topic is used to address all Sonoffs on the local network to send an MQTT command or request which all of the active devices will execute (again, more on this later).  Next comes the fall-back module name for MQTT addressing, next the full URL for the OTA server, the SSID for your access point, the password for your access point, the hostname for the MQTT server.  The last two numbers on the end are the heartbeat count and the configuration save count.

Status with the “2”  option is somewhat less verbose and provides revision information for TASMOTA itself (1.0.6),  the ESP8266 boot version (4) and the ESP8266 SDK version (1.5.1).

Light & Power

The “light” and “power” commands are synonymous and do exactly the same thing – control the relay.  The commands can be used with or without options.  Used without an option they will display the current status of the relay:-

power
POWER = Off

Used with an option of “0” they will switch the relay off:-

light 0
LIGHT = Off

Used with an option of “1” they will switch the relay on:-

power 1
POWER = On

…and with an option of “2”they will toggle the state of the relay :-

light 2
LIGHT = Off

Topic

The use of “topic” as a command name is a slight misnomer, as this command only shows or changes the part of the MQTT topic which is used too address individual Sonoff units.  For instance, when using the “power” command from MQTT, your command line might look something like this:-

cmnd/sonoff/power 2              -- Toggle the state of the relay.

The “cmnd” specifies that the topic is a command.  The “power” specifies that the command is specific to relay control.  The “sonoff” part of the topic string specifies the actual address of the Sonoff unit (and Theo uses “sonoff” as the default, compiled in,  address).  You can also think of this as being the name assigned to each individual unit.

The useful part of this is that the address can be changed, using the “topic” command, so all of your Sonoff units can be addressed individually (it wouldn’t be too useful if they couldn’t be).  So, going back to our serial console and the command line, we can display the current addressable name using:-

topic
TOPIC = sonoff

…and to assign a new addressable name to this specific unit, use the topic command with an argument:-

topic 2F-toilet-gas-sensor
TOPIC = 2F-toilet-gas-sensor

ets Jan 8 2013,rst cause:1, boot mode:(3,7)
chksum 0x42

Project sonoff (Topic 2F-toilet-gas-sensor, Fallback DVES_0CB0CB, GroupTopic sonoffs) Version 1.0.6 (Boot 4, SDK 1.5.1(e67da894))
NAME = Sonoff switch
VERSION = 1.0.6
FALLBACKTOPIC = DVES_0CB0CB

Note that the unit has not only accepted the new addressable name, but it has also automatically rebooted and the reboot header information shows the new name, the fall-back name and also the group name. Now this Sonoff unit will only respond to commands and requests which include the addressable name “2F-toilet-gas-sensor” in the topic string.  It will always respond to the “fallback” name of “DVES_0CB0CB” (derived from the unit’s MAC address) and will also respond to the current group addressable name of “sonoffs” (along with all of the other Sonoffs on the local network which have the same GroupTopic setting).

GroupTopic

As just noted, the “GroupTopic” is a special, common addressible name to which all Sonoffs with the same GroupTopic setting will respond.  The GroupTopic can be displayed and set in exactly the same way as the Topic:-

grouptopic
GROUPTOPIC = sonoffs

grouptopic calling-all-units
GROUPTOPIC = calling-all-units

ets Jan 8 2013,rst cause:1, boot mode:(3,7)
chksum 0x42

Project sonoff (Topic 2F-toilet-gas-sensor, Fallback DVES_0CB0CB, GroupTopic calling-all-units) Version 1.0.6 (Boot 4, SDK 1.5.1(e67da894))
NAME = Sonoff switch
VERSION = 1.0.6
FALLBACKTOPIC = DVES_0CB0CB

Again, calling grouptopic with no argument will display the current setting, while calling it with an argument will set the new group addressable name and automatically reboot the unit.  In the scenario shown above our unit will now respond to the unique address of “2F-toilet-gas-sensor” and also to the common group address of “calling-all-units”.

Next …in the next article we’ll delve into the MQTT command structure for TASMOTA.