Monday, 6 November 2017

Flashing sonoffs with custom firmware

First things first.

DO NOT work on any sonoff devices that are plugged into the mains, at best you may get a nasty shock, and at worst you may kill yourself.  Do not mess with mains devices if you don't know what you're doing, or local laws prevent it.

Sonoffs are relays.  They turn things on and off.  There are many different versions available, but the good thing for home hackers is that they are based on the 8266 chip, and there are lots of clever people who've done lots of work to make replacing the factory software with your own easy.

I will show you how to flash sonoff and sonoffrf devices as that's what I've got, and I'll be adding firmware that allows the sonoff to respond to MQTT commands.

You will need

  • The Arduino IDE to compile your firmware [Free]
  • A firmware of your choice [Free]
  • A FTDI FT232RL USB to TTL Serial UART Converter Module 5V / 3.3V Arduino, PIC
  • Male pin headers 2.54mm [£1]

First a sonoff

The device will have a paper seal that shows tampering, run a 'spudger' or flat blunt knife blade in the groove at the bottom of the housing and unclip the top cover, it should click off easily.

The insides should look like this

The thing that allows us to do our magic is the unpopulated connectors on the board.  You'll need to buy some pin headers and then solder them in place

When you've finished it should look like this

I populated all 5 pins, but we only need the left 4 for our reflashing.

Next you will need your software set up.   I don't plan to reinvent the wheel, so there's a good video by Bruh Home Automation so have a look at that - it gives lots of good information, though I would do one or two things differently - it's a good overview with lots of details though, so well worth a watch.

To replace the original firmware in my sonoffs I use the Tasmota firmware which can be obtained from

Download the zip file, extract it and put it in the path of your Arduino IDE software.

This should be something like


where project is something like sonoff1

You will have to make some changes to the code in order to customise it to your wifi and needs - this is covered in the Bruh HA video above, but a list of changes is as follows.

In your


folder find and edit PubSubClient.h

Comment out the line that specifies the max packet size by putting // at the beginning of the line
Copy that line and paste it afterwards and change the number to 512
It should look like below

//#define MQTT_MAX_PACKET_SIZE 128

Save PubSubClient.h

The only other file you need to modify is user_config.h
This can be found in


Change the following lines

#define PROJECT                "sonoff1"

sonoff1 will be the name of your switch when you use it, so you could call it something more specific like kitchenswitch1 etc

Next update some wifi settings

#define WIFI_IP_ADDRESS        ""       
#define WIFI_GATEWAY           "" 
#define WIFI_SUBNETMASK        "" 
#define WIFI_DNS               "" 

Change to whatever you use on your lan

Now enter your wifi name and password

#define STA_SSID1              "Wifiname"               // [Ssid1] Wifi SSID
#define STA_PASS1              "secretpassword"     //

You can also add

#define STA_SSID2              "alternativewifiname"      // [Ssid2] Optional alternate AP Wifi SSID
#define STA_PASS2             "alternativepassword"

if you've more than one wifi network avaiable.

I run my own mqtt broker on my RPi

So we need to configure that

#define MQTT_HOST            ""          // [MqttHost]
#define MQTT_PORT            1883              // [MqttPort] MQTT port (10123 on CloudMQTT)
#define MQTT_USER            "brokeruser"       // [MqttUser] Optional user
#define MQTT_PASS            "brokerpassword"       // [MqttPassword] Optional password

Change the details to those that you use.

Next it's possible to send a command to all sonoff devices eg turn everything off

You may set up all your kitchen devices to respond, or as I'm doing set all sonoffs to respond to this group topic (rather than telling each switch specifying to turn on or off)

#define MQTT_GRPTOPIC          "sonoffs"

and finally, give your device a friendly name

#define FRIENDLY_NAME        "Sonoff1"

There are other things you can configure like security etc but I'm not covering that.

Once you've done all that you're now ready to flash.

Check the settings on your IDE are as follows

  • Tools->Board->Generic ESP8266
  • Flash mode ->DIO  [Check firmware version as later ones say DOUT should be used]
  • Flash frequency -> 40MHz
  • CPU Frequency-> 80MHz
  • Flash Size-> 1M (64k SPIFFS)
  • Debug port-> Disabled
  • Debug level-> None
  • Reset Method->ck
  • Upload Speed-> 115200
  • Port->Where you connected your FTDI board (eg Com5 or /ttyUSB0 etc)

Press the compile button on the IDE, if all goes well it will tell you.  If not, look at the error messages - it will most likely be a typo, or you need to install a library that the code uses, but you don't have.

Tools->Add files->Manage libraries

Will allow you to search for and add any libraries you need.

Assuming you've no errors

Connect your sonoff to your FTDI as below, plug the usb lead into your PC at this stage.  Make sure you FTDI is set to 3.3v

I've had a fair bit of frustration at this point, but the most reliable way to get the firmware uploaded is as follows.

Plug in the usb to your computer, wait until the port for the FDTI device is selectable in the Arduino IDE, then select it.

You will see the FDTI connectors from left to right are

VCC, Tx, Rx, Gnd  the Gnd IS NOT connected at this point.

We need to set the sonoff to accept new firmware, in the case of the basic sonoff what is needed is to
PRESS and HOLD DOWN the on/off switch, while AT THE SAME TIME connecting the Gnd to the 4th pin (the one next to the green wire in the picture above, the 5th pin is not used).

Once you've slide the Gnd wire on the 4th pin you can release the switch.

If when you're doing this you break the connection between the ground wire, and the ground pin then you will have to start again, as the sonoff will not be in a mode to accept new firmware.

When you've done this you can now press the upload button in your IDE.  Your FDTI board led will flash and you should see lots of dots in the IDE indicating progress.

Hopefully this reaches 100% in which case you're done.

Your sonoff should now be able to connect to your MQTT broker and respond to commands to /sonoffs/sonoff1

If you receive errors then try again.  I had most problems when using a 5v logic level 8266 based plug, and think the voltage was boarderline, so moved the USB on the computer to a port directly attached to the board, rather than one on the front plate of my PC, and that allowed successful flashing.

The process for flashing other sonoff devices is similar, though sometimes a bit more awkward.

I've also got sonoffrf devices

Outwardly they look similar, but inside they've a daughter board with the Rf receiver, but the same empty pin holes on the main board.

Solder pin headers as before so you can attach your FTDI board

The process for flashing a sonoff Rf is exactly the same as the basic sonoff, with one difference.

In order to put the sonoff Rf into a mode that allows firmware update we DO NOT press the button down when connecting the ground wire.  Instead it's a bit more fiddly.

We need to look at the underside of the board

And then instead of holding down the switch we need to short these two points when connecting the ground wire.

This is fiddly, some have had success doing this with the leads of an led, I used a pair of metal tweezers. If you have difficulty, or you'll be doing this a lot, it may be worth rigging up an inline switch for the last FDTI wire so you can make the connection more easily when shorting these two points.

The rest of the process is the same as before.

Now that you've one (or more) sonoffs flashed, the next article will be on controlling them with node-red and an MQTT broker.

For subsequent sonoffs, you would only need to change the

#define PROJECT                "sonoff1"


#define FRIENDLY_NAME        "Sonoff1"

so that each sonoff had it's own unique identifier.

I should add one more thing, sonoffs don't have an earth wire, but your device may need one.  If that's the case the you should have an earth wire that bypasses the sonoff.  If that's the case then I would suggest that you also place your sonoff in an enclosure - I'd actually always recommend this.  That also has the advantage that you'll be able to add additional cable strain relief to the sonoff wires, no bad thing as you don't want it to be possible to pull a live mains wire free from the end of your device.

See for some safety advice

It's possible to apply OTA updates to sonoffs, or have them check an appstore for new firmwares, but that's not covered here.

No comments:

Post a Comment