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

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.


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 = 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:-


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

light 0

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

power 1

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

light 2


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 = 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

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).


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 = 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

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.



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

  1. Thank you for such a thoroughly precise explanation of what looks to be an excellent project. Unfortunately I have been using the IMROY version of pubsubclient and so the code supplied in this project wouldn’t compile with that library. I so wish the two principle versions of pubsubclient, IMROY and O’ Lleary had been given different names so they could co-exist. I guess I’ll have to change to the seemingly more widely used O’Lleary version. I look forward to your next installment on this excellent sonoff firmware.


    • Thanks for your feedback, Bob. I wasn’t even aware that there were two different versions of PubSub. I’ve actually been using Ingo Randolph’s Arduino port of Tuan PM’s esp-mqtt for most of my projects (in fact, I’ve ported a couple of PubSub projects over to esp-mqtt simply because I was more familiar with Tuan PM’s version). Anyway, Nick O’Leary’s code is quite mature and should really be rock solid. Ian Tester’s (imroy) stuff looks interesting though …OTA via MQTT — going to have to have a play with that. 🙂


      • Hi, Likewise I wasn’t aware of Ingo Randolph’s port of Tuan’s MQTT for the esp/Arduino set up. I’ll give that a try. Ideally I’d like to standardize on one PSC so I’ll probably go back to the O’Leary version.


      • Hi, I wonder if you can help me with a problem. I have loaded the TASMOTA code onto an ESP-12E and with the serial monitor connected it does show the initial output as per your article but it does not respond to any serial commands from the top window of the Arduino serial monitor. I thought that the DEBUG messages within the TASMOTA code would help but I don’t know how to enable the debug output. Could you tell me how to do that please.




      • Bob,

        The easiest way at the moment is to update your Arduino-IDE board-manager, as the latest version includes a nifty DEBUG feature where you can easily enable or disable debug and set the different levels. So…

        Got to “tools” and select “Board” -> “Boards Manager”.
        (Give it a few seconds to update it’s cache from the ‘net).
        Scroll down to the “ESP8266 by ESP8266 Community” section and select update.
        (This will take a couple of minutes, depending upon your connection speed).
        Once the update is completed, shut down the IDE using the File -> Quit method.

        Restart the IDE
        Goto Tools -> Boards
        Select “Core Development Module”
        (You might have to select the scroll-down-arrow at the bottom of the menu to have this option show up)
        Go back to the Tools menu and you will now find you have a couple of extras in the middle of the menu, “Debug Port” and “Debug Level”.
        Tools -> Debug Port -> Serial
        Leave the level at “None” for the time being.
        Recompile and flash with those new settings and you’ll get DEBUG output squirted to the Serial Monitor window.

        This is one of those things that looks extremely complicated when written down, but is very simple and quick (once the update has completed) when you use the IDE.

        Just as an aside, I loaded the code to a WROOM-02 this morning (don’t have a 12E) and it worked fine (serial monitor and MQTT) both with and without the DEBUG option.


      • Hi PuceBaboon, Thank you so much for your prompt response. I had all the latest stuff loaded and so it was only a case of looking under tools. As you say simple and quick when you know how.
        I have now got the TASMOTA code working properly both under serial and MQTT. I have learnt a lot about coding techniques from that code and will certainly use them in my own projects. Just waiting for my SONOS to arrive now. BTW I said my ESP’s were version 12E but they could also be 12F or 12Q according to the guy where I buy my BO boards from.
        Thanks again and have a great day.


      • I have been using Imroy’s as well as O’Leary’s pubsub. Imroy has some advantages as it is easier to send string variables,but sadly the are not compatible. I have not tried the OTA via MQTT yet. wasnt even aware of that possibility


  2. Hi John,

    You did a great job documenting my code and assisting others in solving their little problems.

    Thanx, Theo


    • Thanks Theo …but I can’t keep up with the pace of your development! 🙂
      It’s a great package; thanks for all of the work you’ve put into it.

      By the way, I’ve been meaning to ask …what’s the significance of the number “4” (wifi.ino). It’s unusual to see a bare number used so many times (4-times) without being assigned to a symbolic name.
      Here in Japan, the number four is considered to be unlucky (much more so than the western “unlucky 13”) because it sounds like the verb to die (seriously bad luck, or exception(28) finally explained). 🙂


  3. Sorry John, If I had known I would have done it like I did since version 1.0.9. 😉

    I’m currently implementing some of your suggested changes (user_config.h and pubsubclient parameters in sonoff.ino) soon to be released as version 1.0.14. That also solves another unlucky 13.


  4. Hi
    I’m have lots of fun with your upgrade to the sonoffs, thanks for you hard work. I have a POW and TH working.

    I would like to change the topic, i have made several attempts with the user_config.h
    #define MQTT_CLIENT_ID “test”
    #define MQTT_TOPIC “sonoff_%06X”
    #define MQTT_TOPIC “sonoff/%06X”

    and a number of others but I can’t seem to get the changes flowing through. It simply uses tele/sonoff or stat/sonoff. I was able to change it through the web-server however.

    I would like the topic to reflect my other device MQTT topics. I’m installing about 50 of these devices in my new house and my schema is: location/function/device.

    for example: house/entry/ceiling/temperature/device

    I would appreciate any assistance.

    Kind regards Daniel


    • Daniel,

      To answer your config question first …there’s a #define right at the top of the user_config.h file named CFG_HOLDER, which is the start location for the configuration data. If you change this value it will trigger an update and your new values will be used (just try adding two to the current value and recompile).

      You definitely need to change the MQTT_CLIENT_ID value to something like “XYYZ_%06X” before adding any other devices. MQTT uses the client ID to track individual connections, so a connection from a second (or third, or fiftieth) “test” will cause the broker to immediately disconnect any other client using that name.

      I get the feeling that you were replying to Theo’s post, by the way and I would agree that we all owe him a big thank you (and several beers) for the work he’s done with these devices. In fact, Theo’s changes are so prolific and wide-ranging that I can’t keep up, so I’d recommend you check out his Wiki on the GitHub page for up to date info:-

      The latest release is 3.1.4 …but that will probably have changed by the time you read this. 🙂

      Good luck with the new house!



      • Cheers John,

        yes i have his git page just about opened all the time. Thanks for the prompt advice, I will have a look at that shortly.

        Kind regards


  5. Hi John,

    As advised that did work, thanks.

    Is there a way that I could send the MAC using mqtt and receive back the topic for that device. I don’t want 50 x programs to maintain. I can do the script on the server side, but i didn’t want to tinker to much with Theo’s code.

    Kind regards daniel


    • Daniel,

      Theo’s original code uses “DVES_%06X” as the MQTT_CLIENT_ID, with the %06X part being replaced with the unique chip ID for each individual ESP8266 (which Theo uses as the “fallback” topic for the unit), so unless I’m misunderstanding your question, everything you want is already there.

      You don’t have to change the program for your fifty units, but you do have to change back to Theo’s original definition, or something like it, for the MQTT_CLIENT_ID and you also have to do some work on whatever you are using on the broker side (Node-Red, or whatever) to ensure that it can identify the individual client IDs and associate them in some way with the controls and topics associated with them (that is, you need to know on your control side that the ESP with client-ID “DVES_1ABCD2” is a temperature sensor in the 2nd bedroom and that “DVES_3FEDC4” is the servo controlling the heat for that same room).

      You can change the topics via MQTT itself (the sonoff unit will reboot automatically after this command is issued), so you should be able to do pretty much whatever you want with Theo’s original, unchanged code.



      • Thanks Mate,

        Yes I can work with that, I’ll setup a table of MAC address, and if I have to change one of the devices then I should only have to the MAC address in the table.

        thanks for your help, good to just talk through something.

        A happy seasons greeting to you.

        Kind regards Daniel


      • Hi John,

        Sorry there is always something else….

        I have:
        #define MQTT_CLIENT_ID “sonoff_%06X” this is the default

        but the MAC address does not seem to resolve till later so I get topics like
        tele/sonoff_%06X/POWER = OFF

        Instead of:
        tele/sonoff_0708B6/POWER = OFF

        The web-Server says:

        Program version 3.1.0
        Core/SDK version 2_3_0/1.5.3(aec24ac9)
        Uptime 1 Hours
        Flash write count 7
        Boot count 2
        Reset reason Power on

        AP1 SSId (RSSI) Kingfisher (100%)
        Hostname sonoff_%06X-2230
        IP address
        MAC address 60:01:94:07:08:B6

        MQTT Host automation
        MQTT Port 1883
        MQTT Client and
        Fallback Topic sonoff_0708B6
        MQTT User
        MQTT Topic sonoff_%06X

        Sorry to be a pain in this feastive season.

        any thoughts.

        Kind regards Daniel


  6. Daniel,

    Yup, that won’t work. You’re defining your topic to be the uninitialized client ID. The topic define is evaluated at compile time and never changed. The client ID, on the other hand, is initialized with the data from ESP.getChipId() at run time.

    When your ESP first contacts the MQTT server, you need to use the fallback address to set the topic (from the MQTT server side — pushed out to the ESP) to whatever it is that you want. You need to do that for all of your units.

    Don’t forget that Theo has also provided a “broadcast” address to allow you to send to all units. That might come in handy for doing a regular sanity check on how units are configured.

    The bottom line is that you’re going to have to either initialize the topic at run-time (copying the method used for initializing the client-ID), or you need to do a bit of work from the infrastructure on the other side of your MQTT server to push out the modified topics via MQTT back to the Sonoffs.



    • Thanks again John.

      I will do a bit more pondering before wasting any more of your time.

      Have a great New Year.

      Kind regards Daniel


      • Hi Daniel, I had a similar requirement to you whereby I wanted to have ‘plug n play’ modules without having to use MAC address look up. I opted to use unique addresses by reading the state of IO pins of an I2C port expander. Alternatively you could program a unique address into EEPROM or SPIFFS and read that on power up. I then include the unique address in the MQTT messages.
        I used a PCF 8574 I2C I/O expander to provide up to 256 addresses by DIP switches or jumpers. I used a second 8574 to drive an opto coupled 8 relay board which I refer as a ‘bank’ of relays. So my addressing is BankNo/RelayNo/State.
        I appreciate this adds parts and if you only wanted to address a few devices you could do this using, say 3,pins on an ESP8266 to give 8 addresses.
        I highly recommend studying the code Theo produced for the Sonoff. I learnt a great deal from it.


      • Thanks Bob,
        I shall give this some thought as well. I’m sure that this type of problem will only become more prevalent as more want to control there homes.

        Kind regards Daniel


  7. How can I make the sonoff relay start ‘on’ when power is connected (normal state is off when power is connected). I’m trying to send mqtt commands and nothing seems to save once power cycled?


    • Adam,

      Make sure that SAVE_DATA is set to “1” and that APP_POWERON_STATE is set to “3” and change the value of CFG_HOLDER (by, say, adding 3 to the current value) before you reflash.

      It’s also worth downloading the latest version. As you’ve probably noticed, Teo churns out updates at an amazing rate.



  8. is there a way to have TASMOTA sending subscribe /cmnd/sonoff/POWER when starting up or reconnecting. This would be helpful when using the firmware together with iobrokers mqtt-server adapter. this mqtt-server adapter writes all topics into a objects tree (acting as interface to iobroker scripting and gui). If the cmnd topic is not sent by TASMOTA, it is not entered to that tree and thus no switching commands can be initiated.


    • Hi N.Horn,

      To be honest, I’m not 100% sure I understand your question, but if you need a specific power-on message to enable support for a particular product, I’d suggest adding an issue on Theo’s GitHub repository. He’s very quick to respond is usually happy to add features which help to integrate TASMOTA with other products.



      • hi John, thanks for the hint, I already did so, but I have seen that Theo also reads here.
        TASMOTA already publishes all the other topics like stat, tele, info – thats perfect with iobroker but the other direction, subscribe cmnd doesn´t happen at powerup time. ok lets wait for Theo´s answer.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s