Sonoff - Cheap Remote Controlled Mains Switches

Sonoff Basic We have moved house recently. That is the reason why I couldn’t spend too much time on this website lately. Plus the fact that my new hobby room is still under construction didn’t help either. In the new house I want to automate some of the lighting. And since the days are getting shorter again, I thought it was time to finally deploy my Sonoff switches which I have bought before we left our old house.
This page is not one of my projects as such, all the credit should go to Itead, for creating such a nice small and affordable mains switching device and to Theo Arends, who has written a wonderful alternative firmware for these devices.

This page is merely a collection of the steps required to flash new firmware and deploy the Sonoffs plus a brief description on how to use them. That way I can easily repeat these steps should I need more Sonoff devices at a later date.
I won’t go explaining how to setup your own MQTT broker or how to secure it. You could use a public MQTT broker in case you don’t want to setup one yourself. I'm using Mosquitto as an MQTT broker myself. It's easy to set up and has worked perfectly for me so far. I highly recommend it, but it by no means the only option out there.

Original Software

The Sonoff switches come with eWeLink firmware, which connects your Sonoff to their server. The advantage is that you only have to install the EWeLink App on your phone and you’re good to go. You can control all your Sonoffs from all over the world using this app.
However I would rather like to run it all from my own server. It is a bit more work to set it all up, but it ensures me that it will work for as long as I keep my server running. I won’t have to worry about their server to be decommissioned at some point in the future.
And I’m not interested in controlling my Sonoffs with an App anyway. I’d like my server to control them, at least most of the time.

At first I did manage to find a website explaining how to use your own MQTT broker with the original Sonoff firmware.
Later I’ve learned that Tasmota is a much more sophisticated alternative to the original firmware. It would break the warranty of course, but who cares, for a device with the price tag of about 5 Euros, delivered. Tasmota it is going to be. A big thank you to Theo Arends for making this program publicly available.

Which Way To Go?

I’ve tried different flashing methods before I finally settled on the one which works best for me.

First I tried the Over The Air method because that doesn’t require any additional hardware. Sadly it appears that not all versions of the Sonoff firmware agree to that method any more.

USB to UART Then I tried to use an off the shelf USB UART board from Banggood. That failed because the serial chip on that adapter could only supply 50mA to the Sonoff, whereas the Sonoff needs at least some 80mA. Therefore the supply voltage dropped to about 3V. I didn’t even bother to try to flash Tasmota in the Sonoff with this setup because the Sonoff might switch off half way during the flashing process.

Then I realised that the Raspberry Pi has all the features I need, it has a 3.3V voltage regulator and a serial port built in. That would be ideal. But alas, the Raspberry Pi reboots or simply hangs when I connect its 3.3V to the Sonoff. Thus this method theoretically could work after power cycling the Raspberry Pi. However I don’t find that an ideal solution.

USB to UART with 3V3

Finally I decided on using the off the shelf USB UART anyway, with a slight modification. I’ve added a 3.3V regulator to it (LP2950-33), which can supply some 100mA.

I could have gone for an external power supply for either the Raspberry Pi or the USB UART option, but that was too easy. I mean that’s easier said than done while my hobby room is still under construction. I could dig up a power supply, but where are my test leads and alligator clips…..?

Getting The Software

You can download a ready built binary file from Github. Usually you would need the tasmota.bin for the Sonoff Basic version. It works out of the box with one slight shortcoming, which I’ll explain in a minute.

Installing Tools

I can only show you how to flash the Sonoff with Tasmota firmware using Linux. This works equally well on a desktop computer as on a Raspberry Pi. You should be able to use a Windows machine too, but I have no experience on that.

Before you can start flashing you need a few things, apart from a UART with 3V3 signal levels and 4 Dupont jumper wires.

  • First you’ll need Python3. But that is pretty much installed per default on most Linux machines these days.
  • Second you’ll need to install the python3-pip package.
  • Third you’ll need to install the software.

Here’s how to install all of these on a Debian based machine:

sudo apt install python3 python3-pip
sudo pip install esptool

If you add yourself to the dialout group you can flash your Sonoffs without having to become root. Otherwise you’ll have to place the sudo command in front of the flash command later on.

Connecting The Programmer To The Sonoff

Important note! Make sure the Sonoff is disconnected from the mains while the cover is removed! You don’t need the mains connection during flashing.

Opening the Sonoff is quite easy. Simply pull the bottom plate from the Sonoff away from the top shell, using your nails or a flat screwdriver.

2 revisions side by side

Locate the programming port, which consists of 4 or 5 holes in a row. The number of holes depends on the model of your Sonoff device. The holes may or may not be labelled. Below is a picture which designates the hole numbers, in case yours are not labelled.

Programming pins

In any case 4 holes are needed for flashing, which are 3V3, RX, TX, and GND respectively. The 3V3 hole can be identified by its square solder pad. The fifth hole will probably be labeled GPIO14 and is not required for flashing.

Some people choose to solder a header into these holes, on which it will be easy to connect 4 jumper wires. I personally don’t like this very much, especially with the newer revisions of the Sonoff Basic. The circuit board is a bit crowded around the programming holes and reaching them can be a bit difficult.

Slightly modified header It is way easier to use the bottom side of the PCB for the programming header. But soldering it there is a problem, for the PCB wouldn’t fit into the housing after doing so.

Therefore I have bent each short end of the header pins outward, just a little bit. Every other pin is bent to the opposite direction, sideways. That way the header simply plugs into the holes and makes fairly good contact. The contacts have to last for only a few minutes. After flashing the header can simply be removed again.
No soldering required.

Once the header is inserted into the holes of the Sonoff you can make 3 of the 4 connections using Dupont jumper wires. Connect the pins labelled GND on both ends with one jumper wire. Connect the TX line on the Sonoff side to RX on the serial adapter side. Connect the RX line of the Sonoff side to the TX pin on the serial adapter side.

Now press and hold the button on the Sonoff while connecting the 3V3 line of the Sonoff to a 3V3 powersource, which can supply at least some 100mA. This will put the Sonoff in bootloader mode, where it will wait for the new application software to arrive. The LED does not light up in this mode.

Sonoff connected to programmer

Flashing Tasmota

Now open a terminal on your computer and cd to the directory which holds the tasmota.bin file. Then enter the following command (you might have to place sudo in front of the command): -p /dev/ttyUSB0 write_flash 0x000000 tasmota.bin

On a Raspberry Pi you should replace ttyUSB0 by ttyAMA0. And when you have pressed enter you will see the following appear on the screen: v2.7
Serial port /dev/ttyUSB0
Detecting chip type... ESP8266
Chip is ESP8285
Features: WiFi, Embedded Flash
Crystal is 26MHz
MAC: dc:4f:22:95:0f:6c
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 1MB
Compressed 515872 bytes to 355877...
Wrote 515872 bytes (355877 compressed) at 0x00000000 in 31.6 seconds (effective 130.6 kbit/s)...
Hash of data verified.

Hard resetting via RTS pin...

This whole process will take some 35 seconds. After that you may have to restart your Sonoff by briefly removing the 3V3. Then the LED on the Sonoff should start to blink.

It Works, But....

The default software version doesn’t support a TLS encryption to the broker. The only way to fix this is to compile the software yourself, after changing a configuration file.

The Sonoff basic has a total of 1M bytes of Flash memory. In case you’re interested in Over The Air updates only half of this memory can be used. The other half is used as a buffer during the Over The Air update. Adding TLS encryption to your Sonoff will increase the software size to more than half of the available Flash memory size. This means that you cannot use Over The Air updates anymore. Extra security comes with a price.

After some consideration I’ve decided to leave the Tasmota software as is for now. With Over The Air upgrade capability and without TLS. I can still use it safely on my public MQTT broker by whitelisting only my own home IP address to allow insecure connections.
Another option would have been to run the MQTT broker on a local machine in my home network.

Perhaps I’m going to upgrade to TLS encryption when I have more time to spend on it. Who knows I can squeeze TLS in by removing unused modules. But for now it works, without TLS limited to my own network for security reasons.

Connecting To Your Sonoff

Now it’s time to connect your Tasmota device to your Wifi network. Conveniently a new Sonoff device acts like an Access Point. You’ll need a wifi enabled computer, phone or tablet to connect to this Access Point. This Access Point will look like sonoff-xxxx, where xxxx is a random 4 digit number.
Connect your Wifi enabled device to this access point. There is no security required here.
Once your device is connected open a browser and go to address This will open the setup page for your Tasmota Sonoff.

Wifi configuration

Enter the network SSID and WPA2 pass phrase of your network in the first two fields. You may also enter another SSID, WPA2 pair for a second network if you like.
Now you can restart your Sonoff and it should connect to your Wifi network. Then it’s a matter of finding your Sonoff’s IP address. The easiest way is to use the Fing App on your phone. Otherwise you will probably find the IP address in your router’s configuration pages.

Later you can switch to Access point mode again by shortly pressing the Sonoff button 4 times in quick succession.

BTW: You can now disconnect the header to the Sonoff and put it into its enclosure again. This can go only one way, make sure the button shaft pokes through the hole in the top of the enclosure.

Configuring Your Sonoff

Point your browser to the IP address of your Sonoff. It will present you with a page containing some buttons with which you can control and configure your Sonoff.

Main menu

The Toggle button is the first one you probably want to play with. It toggles the output between on and off. Nice to confirm that all your hard work so far hasn’t been in vain.
But the real fun begins when you press the Config button. It will bring up a menu with the most interesting settings.

Config menu

We have already seen the Wifi Setup menu. For me the most interesting one is the Configure MQTT botton. The other configuration menus don’t apply to my MQTT setup, so I’m going to skip them here and leave them for you to explore.

Config MQTT menu

Not all configurations can be made from the web interface, robably due to memory constraints in the Sonoff devices. You can access the command line interface from the web interface by clicking the Console button in the Main menu where you can see status updates from the device and enter commands.
A list of all the available commands can be found on the Sonoff Wiki page.

It is also possible to configure these same settings through MQTT, so you might consider automating these configuration settings from a central computer.

Here are a few settings you might want to change:

Automate the timezone:

Per the default timezone is set to a fixed offset from UTC. I prefer automatic switching between daylight saving times. For that you’ll have to set the Timezone to 99.

timezone 99

The default daylight saving rules work for me. It is set to the European rules anyway.

Your location:

Per default my Sonoff was placed on top of the Eiffel tower in Paris. This only affects the sunrise/sunset times. So if you want those to be correct you should set the Longitude and Latitude values to your own location.

latitude 51.604112
longitude 5.161626


And now the moment we’ve all been waiting for, controlling your Sonoff using MQTT. For that to work we need an MQTT client on our computer. Again mosquitto is the one I use as a command line interface MQTT client. To make life easier I’ve added two aliases in my .bash_aliases file, like below:

alias iot_sub='mosquitto_sub -h $(cat ~/.mqttpwd) -p 8883 --capath /etc/ssl/certs/'
alias iot_pub='mosquitto_pub -h $(cat ~/.mqttpwd) -p 8883 --capath /etc/ssl/certs/'

That will save me a lot of typing quite mysterious looking magic spells for each command I want to give. If your MQTT doesn't use encryption you can skip the --capath bit. I’ve also created a file named .mqttpwd in my home directory containing only one line with your broker's user name and password:

-u username -P password

And if you chmod that file as 600, no one else can read your password.

With these preparations done giving manual MQTT commands has become a whole lot simpler. Let’s open a terminal and enter the following command:

iot_sub -t stat/sonsoff/#

Or in my example, where I’ve renamed the Sonoff device to bookshelf it would be:

iot_sub -t stat/bookshelf/#

That terminal will now continuously update you on the output of the commands give and the state of the Sonoff switch, no matter how it was switched.


Open a second terminal and give one of the following commands:

iot_pub -t cmnd/sonoff/Power -m 0
iot_pub -t cmnd/sonoff/Power -m 1
iot_pub -t cmnd/sonoff/Power -m 2

The first command will switch you Sonoff off. The second one will switch it on. And the third command toggles the state of your Sonoff switch.

Finally you can also publish messages to the group topic, where all of your Sonoff devices will listen to.

iot_pub -t cmnd/sonoffs/Power -m 2

Now you know the basics on how to control your Sonoff. The commands shown above are by far not the only commands you can give your Sonoff device. More can be found on the Sonoff Wiki pages.
For instance you can configure the time zone and your exact location by using the commands below:

iot_pub -t cmnd/sonoff/Latitude -m "51.604112"
iot_pub -t cmnd/sonoff/Longitude -m "5.161626"
iot_pub -t cmnd/sonoff/Timezone -m "99"

Or you could check their settings by publishing the same command, with an empty message. Don’t forget to have a terminal open where you subscribe to the status of you Sonoff, otherwise you won’t see anything.

iot_pub -t cmnd/sonoff/Latitude -m ""
iot_pub -t cmnd/sonoff/Longitude -m ""
iot_pub -t cmnd/sonoff/Timezone -m ""