Using oddball ESP boards with TASMOTA

Theo Arends continues to fix, improve and expand TASMOTA at a rate that, as a mere mortal, I find incredible.  One of the areas which has seen a lot of activity is the list of supported modules and devices.  When you connect to the web server on your device and select the configuration menu, the top item on the list is “Configure Module”.  This allows you to select your specific hardware (currently, with release 5.11.1, ranging from the original ITead Sonoff Basic, all the way through to the Arilux LC06 RGB LED controller) to enable device-specific features in TASMOTA.

While there are 40-odd entries in the module list, the question is, are you out of luck if your hardware isn’t yet included?  The answer, I’m glad to report, is a resounding “Heck, no!”.  Theo has included a couple of devices in the list which make it relatively easy to drop TASMOTA onto pretty much anything which has an ESP8266 device on-board and have it work,not only with the basic relay switching function, but also with a whole load of other, custom goodies connected.  Here’s an example.

I usually have a couple of the “Yellow Dev Boards” to hand, mainly because they’re so easy to press into service without having to jump through too many hoops.  They have plenty of nice LEDs, an on-board, low quiescent current voltage regulator and an attached battery holder (making for an easy, remote sensor platform), an LDR already wired to the ADC input, all driven by an ESP12 variant (the version has varied over time).

TASMOTA doesn’t have a configuration entry for the Yellow Dev Board specifically, but because the board has an ESP12, most of the entries on the list will work to some degree or other.  Okay, so why don’t we just go with the default “Sonoff Basic” then?  Because the Basic only has a limited number of GPIOs available (and some of them are inverted via MOSFET drivers), it doesn’t lend itself too well to customization.  You can load your own board with the Basic and successfully connect to the TASMOTA web server, but then you really need to look through the hardware available in the “Configure Modules” list and find something which is closer to your specific hardware.

If you’re using a Witty Cloud board (rather than the Yellow), for instance, you’re in luck; entry #32 in the modules list is for that specific board.  If you have a Wemos D1 Mini, that’s also included at number #18.  It’s worth scanning the list to see whether your specific board might have been added recently.

As you can see from the screenshots, the entries in the list aren’t sorted, so searching for an entry can be a little difficult.

As it turns out, the WeMos D1 entry is a good choice when you’re using an ESP12 series ESP8266 and this is the one I’ve chosen in the screenshot examples (the grey entry at the very top).  After selecting (and saving!) this module type, you’ll find that the GPIO options are greatly expanded, compared to the Sonoff Basic.

 

 

 

Note that the WeMos D1 parameter list includes the WeMos pin nomenclature to the left of the GPIO names and the Sonoff default assignations to the right.  This looks a little confusing at first glance, but is actually quite useful when deciding where to connect peripheral devices on your own ESP module (for instance, assigning your relay/SSR to GPIO12 and LED to GPIO13 will still leave your device working if the module type is changed back to Sonoff Basic at any time in the future).

The drop-down selection box to the right of each GPIO (currently showing “00 None”) allows you to select what function or peripheral you’d like to have assigned to that pin.  Again, choosing the WeMos D1 module type enables a wide range of options for each individual GPIO (as of version 5.11.1 of TASMOTA, there are 64 different switches, buttons, LEDs, sensors, busses, relays and functions available, including some which I assume are device specific — what’s a “PZEM Tx”?? — and others which look like a future project in the making — do “IRrecv” or “BkLight” sound interesting to anyone other than me?).

So, going back to our Yellow Dev board, we have an RGB LED, as well as a bunch of boring old red LEDs across the top of the board (see the picture, above).  In this particular application, we’re going to add a DS18B20 temperature sensor to GPIO5 and a small, solid-state relay (SSR) to GPIO12 (the default Sonoff relay pin).  This is going to allow us to switch an incandescent light bulb on (as a low power heater) when the DS18B20 indicates that the temperature has dropped below freezing.  As it’s no fun at all to do this sort of thing without blinkenlights, we’re also going to use the RGB LED to indicate freezing temperatures (blue flashes), above freezing (red flashes) and, for bonus points with those people who aren’t as colour-blind as I am, hovering around freezing point (purple flashes).  We’re also going to add a button to GPIO0 which will provide the standard Sonoff/TASMOTA functions of toggle (for the relay/SSR), as well as the ESP8266 default of forcing the module into programming mode when pressed at power-on.

We’re going to use two methods to drive the LEDs; simple on/off for the green LED (because it’s the Sonoff default power LED, as the handy cross-reference in the Module Type menu, above right, shows us) and PWM drive for the red LED (GPIO14) and blue LED (GPIO15).

One point to note about the green LED is that the xref text shows it as “Led1i”.  That trailing “i” indicates that, on the Sonoff, the ESP output is inverted, because the LED is actually driven via a dedicated MOSFET.  On our Yellow board there’s no driver MOSFET, so we choose the non-inverting “Led1” when assigning a device to GPIO13.

GPIO14 and GPIO15 are LEDs, but because we want to vary the intensity and mix the colours (it’s that chunky, though-hole RGB LED at the top right of the Yellow board, remember), we’re going to assign types PWM1 and PWM2 to them.

The SSR is assigned type “Relay1” on the Sonoff default GPIO12 and we assign type “DS18B20” to GPIO5.  The sensor assign does neat stuff, using Theo’s modified version the One Wire code to communicate on the designated pin (you must add a 4k7 resistor between the 3v3 pin and the data pin to have this work correctly and, if you’re using a sensor on long, unshielded leads, I’d recommend that you place the resistor at the outer, DS18B20 end, rather than on the GPIO end and add a 0.1µf between the DS18B20 ground and 3v3 pins).

Here’s what the module configuration panel looks like with all of those changes made:-

When you hit “Save”, the module will be restarted with your new configuration implemented.  At this point it would be a good idea to go back into the main configuration menu and select “Backup Configuration” to save all of those changes to a file on your local machine.

In the second part of this post, we’ll look at some minor hacking of the Yellow board hardware to make a functional device, as well as going over the web and MQTT commands to get the peripherals working.

 

 

 

 

Using “TASMOTA” [Part – 2, MQTT]

Update @ 20th February 2018  –  There’s now a newer post available on using TASMOTA, which I’d recommend as a follow-up to this one.

[Apologies for those of you have been checking back in regularly for this second article on using Theo Arends’ Sonoff-MQTT-OTA-Arduino package.  Not only has Real Life™ been getting in the way, but I’ve purposely been delaying hitting the big, red “publish” button until I could sort out a nagging little problem I’ve been having (more on that later).  Anyway, here we go with part two…]

In the previous article, we looked at how to access some of the features of TASMOTA (Theo Arends’ Sonoff-MQTT-OTA-Arduino package) using the button/LED and serial-console interfaces.  In this article we’ll take a look at controlling the unit using MQTT.

[…and if you don’t really know what MQTT is, or what it does, Elliot Williams has recently published a clear, easy to read and easy to understand article on Hackaday which is worth looking at…]

The main selling point (other than the extraordinarily low price) of the Sonoff is the fact that it is controllable across the ‘net.  Unfortunately, ITEAD Studios have tied control of the device to their own cloud service which, while it may be great for most people, doesn’t work for those of us who are still using “dumb” phones and who don’t have the option of using a service such as Oogleg’s “voice” to get around that limitation.  Theo’s firmware implements MQTT on the Sonoff which, while it doesn’t help my “dumb” phone, does mean that I can use existing devices on my own network to control it.  I already have a couple of MQTT servers on the local network providing time services to various battery-powered, ESP8266 enabled sensors and collecting data (temperature, humidity, barometric pressure, battery voltage) from them.  It would be a trivial matter to have the internal MQTT servers push that data to one of the free data aggregation services out on the ‘net and only a little more work to make the MQTT interface available through the firewall for external access when we’re away from home (Okay, a lot more work to do it properly 🙂 ).  In my case, the need for MQTT is purely pragmatic; it’s a neat device, but I need MQTT to get it to work without a smart-phone.  For others, there may be a reluctance to entrust data access and control to a cloud service which might disappear at some time in the future.  Whichever it happens to be, Theo’s package “hits the spot” and broadens the possible usage window for the Sonoff (which, long term, is good for ITEAD’s sales, too).

In the previous article we already saw how to set up the “topic” keyword to give your Sonoff devices individual addresses, as well as using “grouptopic” to set a group address to which all devices will listen.  Before you can use MQTT though, you need to configure the MQTT broker (server) details for your network, too.  The recommended way of doing this (unless you have a gazillion MQTT servers on multiple networks) is to simply compile-in the hostname/IP and port number when you initially build the package.  If you’re using Theo’s original package, edit the user configurable details at the top of the sonoff.ino file and change these lines:-

// MQTT
#define MQTT_HOST "sidnas2"
#define MQTT_PORT 1883

…to point to your own MQTT server address and port (if you’re using the version which I put up on GitHub with the function defines added, these settings broken out into user_config.h instead).

You can still change this setting (along with most others) from the serial console, or from MQTT, later on.  Using the serial console (as per the previous examples), you can see that the Sonoff unit automatically reboots after the change:-

host
HOST = blind.nthld.org

host hazeltonrig.nthld.org
HOST = hazeltonrig.nthld.org

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

First we used the “host” command without arguments to interrogate the unit for the current setting. Secondly, we used the “host hazeltonrig…” command to change the compiled-in default. TASMOTA then automatically saves the new value to non-volatile memory and restarts the ESP8266 using the newly updated parameters.

Mosquitto notes

Before we start using MQTT let’s just take a brief look at Mosquitto and the utilities which come bundled with it, mosquitto_sub and mosquitto_pub.  If you’re not using Mosquitto as your MQTT server, feel free to skip this section.

As you’d expect from the names, mosquitto_sub is a command-line utility which allows you to subscribe to a topic, while mosquitto_pub allows you to publish.  They are invaluable tools when setting-up and debugging MQTT installations, allowing you to send arbitrary data and commands and to monitor the output.

You can also install the Mosquitto package on a desktop or laptop machine to make these applications available when you just want to connect to a remote MQTT server on some other machine (both utilities accept a “-h” option with an argument specifying the hostname to connect to and a “-p” option with a numeric argument to specify the port number).  However, typing in the full command names, plus options and arguments can get tedious very quickly, so I’d suggest adding aliases for both commands.  These can be added to your .bashrc (assuming you’re using the common, Bourne Again SHell) to make your life a little easier. Here’s an example (you need to customize it for your specific installation):-


##
## Aliases for Mosquitto utilities.
##
## Simple alias for server on this machine.
alias mp=/usr/bin/mosquitto_pub;
alias ms=/usr/bin/mosquitto_sub;
##
## Aliases for server on remote machine.
## (You can comment-out this whole section if you
## only use the server running on this machine).
MQTT_SRV="hazeltonrig.nthld.org";
MQTT_PRT=1883;
alias rmp="mp -h ${MQTT_SRV} -p ${MQTT_PRT}";
alias rms="ms -h ${MQTT_SRV} -p ${MQTT_PRT}";
unset MQTT_SRV MQTT_PRT; ## Prevent pollution.
##
## End of Mosquitto aliases.
##


In the .bashrc excerpt above, we are first setting “mp” to be an alias for the full pathname of the mosquitto_pub command and then doing the same for “ms” and mosquitto_sub command.

You only need the second part (from the line “## Aliases for server on remote machine.”) if you are running the MQTT server on a different machine to the one where you’ll be running the mosquitto_pub and  mosquitto_sub commands.  If you do want to use it, you’ll need to change “hazeltonrig.nthld.org” (and possibly the 1883 port number) to point to the MQTT server on your network.  The aliases here build on the “mp” and “ms” aliases which we’ve already defined to provide “rmp” (“r”emote “mp”) and “rms” to access our remote server with minimal typing.

The “unset” command simply deletes the MQTT_SRV and MQTT_PRT variables to prevent any unwanted clashes if those names are used by you later.

At the end of that, you can now simplify and shorten your commands.

From:- /usr/bin/mosquitto_sub -h hazeltonrig.nthld.org -p 1883 -t stat/#

    To:-    rms -t stat/#

 

Using the Mosquitto utilities

Now that we have our server defined and some aliases set up, let’s go ahead and dive into using MQTT with the Sonoff and TASMOTA.  I’m going to assume at this point that, if you already have an MQTT broker (server) set up, you basically know how the publish/subscribe model works.  Let’s also assume that our MQTT server (the machine running Mosquitto) is called “hazeltonrig” (as we saw above) and that we’re actually using a laptop to type in these examples and display the output.

Because our laptop is not the MQTT server, we need to use the remote aliases which we set up above to channel all of our publish and subscribe requests through “hazeltonrig”, because for the most part, we are actually interested in interacting with a third machine, the Sonoff module.  So, just the same as with the serial console, let’s start off by getting the status from the device.  The easiest way to do this is to use an MQTT wildcard and listen in on all status broadcasts from all devices on the network:-

rms -t "stat/#"

Going back to our aliases, we can see that this actually expands to the command:-

/usr/bin/mosquitto_sub -h hazeltonrig.northld.org -p 1883 -t "stat/#"

The word “stat” is the top-level topic used by TASMOTA clients to publish their status data.  The “#” is a wildcard, meaning match-anything-from-here onwards.

What happens when you type in this command?  Well, unless your Sonoff happens to be transmitting some status information at the time you hit <CR>, absolutely nothing.  You won’t get a prompt and you won’t see any text on the screen after the command itself.  Not very exciting, but you have just started a subscriber process which will sit there quite happily and spit out any data that comes along with the “stat/” topic header.

If you power-cycle your Sonoff at this point, you  will see a couple of power-up status messages displayed on your screen; something like:-

Sonoff switch
1.0.6
DVES_0CB0CB


You’ll also notice that, if you still have the serial monitor connected via the USB<->TTL converter, you will start seeing status messages appearing on your screen when you type in virtually any command.  So, if you type “power 1” into the serial monitor, you’ll get output on the serial monitor itself and you’ll also see the word “on” appear in the window where your subscribe command is running (actually, even if you don’t type in commands, the subscribe window will still show messages at power-up, restart or power-down events; for instance, pulling the plug on the Sonoff will produce an “offline” message approximately 10 seconds after the unit is switched off).

You could type a <CTRL>z to put the command into background and carry on typing MQTT commands into the same window where you’ve just started your subscriber process, but that would begin to get a little confusing once that process started to return data, so at this point I’d recommend opening a new window to be able to enter further commands.

Now we need to command the Sonoff to send out some status, so that we can read it with our patiently listening subscriber process.  For this we use our remote publish alias, “rmp”:-

rmp  -t  "cmnd/2f-toilet-gas-sensor/status"  -m  ""

This expands to:-

/usr/bin/mosquitto_pub  -h  hazeltonrig.nthld.org  -p  1883  -t  "cmnd/2f-toilet-gas-sensor/status"  -m  ""

…which means, publish the command “status” (request status) to the device currently known as “2f-toilet-gas-sensor”.  The -m “” part of the command is simply a null argument to keep mosquitto_pub happy, otherwise it will print a usage summary to try and persuade you that you need to use a message (-m) as an argument to any topic (-t).

The output you’ll see in your subscriber window from the status command with a null (-m “”) option will be something like:-

1.0.6, 2f-toilet-gas-sensor, POWER, 0, 9

This is telling you that the Sonoff is running firmware version 1.0.6, has a topic (addressable name) of “2f-toilet-gas-sensor”, that the last sub-command was “POWER” and the status of the relay is off (“0”). The last “9” indicates the timezone which is currently configured (in this case GMT+9 for Tokyo).

Up Next…

This article has been languishing in the deeper recesses of the WordPress draft cloud for far too long, and has a lot of information for the reader to digest, so I’m going to save some of the other MQTT commands for yet another article and push the big, red “publish” button to get this one out into the wild.

In the next part, we’ll use some of the more useful commands which Theo has provided and look at the difference between normal and group commands.