Use Homie Firmware to Drive Sonoff Switch Module (ESP8266 Based)


This is a followup instructable, I’ve written this one a bit after “Building Homie Devices for IoT or Home Automation“. The later was focusing on basic monitoring (DHT22 FR/DE, DS18B20 FR/DE, light) around D1 Mini boards.

This time, I’d like to show how to add a serial header for FTDI adapter (FR/DE) on a Sonoff WiFi Wireless Smart Switch (FR/DE) and flash Homie for ESP8266 to the Sonoff device. Using a Homie firmware, the device can be controlled over MQTT and the button will turn relay on/off.

Oh, this Sonoff device is a ESP8266 powered from AC (90-250V 10A) and controlling a relay for AC output. It also has a LED and a button. If you need 16A look at Sonoff TH10/TH16: Temperature and Humidity Monitoring WiFi Smart Switch (FR/DE) for instance. They have a whole range.

There are quite a lot of hacks available for the Sonoff. This range from this simple “add a serial header” to actually adding more GPIOs by connecting to the bare chip directly. I’ll let that as an exercise to the reader.

Warning : You won’t be able to revert to default Sonoff firmware.

If you’d like to support me in writing other instructables, please buy hardware from the Amazon sponsored links.

Sonoff switch

Adding a Serial Header to the Sonoff

Depending on your skills, this might be the easiest to do. The Sonoff products are hackers friendly. You need:

  1. A Sonoff board, we’ll focus on Sonoff – WiFi Wireless Smart Switch;
  2. One 4 or 5 pins header (FR/DE) (5 if you want to access the extra GPIO 14);
  3. Soldering iron, solder, solder flux and related stuff (kit FR/DE).

Place the header right under the push button near the capacitor. That’s it. You now have access to the serial chip and can flash your own firmware (whatever it is). If you used a 5 pins header, you also gained access to the GPIO 14 pin.

Location of header
Sonoff board – Focus on pins

Physically Connecting the Board to the Computer Over Serial

Before flashing the Sonoff device, you’ll need to connect it to your computer. Once we have the serial header soldered, grab :

  • Four dupont cables (FR/DE), choose whatever connectors you need for the specific headers you have (Sonoff side and FTDI side). In my case this is male (Sonoff) – female (FTDI);
  • A FTDI to USB adapter (FR/DE);
  • A USB cable suitable for your adapter.

Connect cables to Sonoff, connect cables to FTDI, connect FTDI to USB, connect USB to computer. After having tested this, I’ve decided to glue together the connectors pins on the cable. As there is a gap on FTDI side between ground and TX/RX/VCC, I’ve added a dupont plastic pin without any cable as a filler. I also marked the GND cable on each side to prevent any mistake.

WARNING 1 : The port on the Sonoff is 3.3V, make sure you use proper FTDI adapter and/or set its voltage accordingly.

WARNING 2 : Do NOT connect AC at the same time as the FTDI!

FTDI to USB board
FTDI Cable
Sonoff Board – FTDI plugged in
Sonoff with FTDI-USB all plugged and flashing

Building and Flashing the Firmware


In order to compile and flash a firmware you need:

I’ve built my project based on Homie’ sample sketch IteadSonoffButton. I made very little changes, mainly cosmetic (comments + logging) and IDE (PlatformIO IDE instead of Arduino IDE).


Make sure you can compile sources. It is particularly important to make sure you use the proper target controller, for this Sonoff device you’ll need to select “Espressif Generic ESP8266 ESP-01 1M” (esp01_1m in platformio.ini).

Once compilation goes fine, we can proceed to actual flashing.


The Sonoff won’t listen to you as-is, unplug it, press its button and release it after you plugged it back. It is required to have button pressed BEFORE powering it to enter “flash mode”. This actually drives GPIO 0 down by connecting it to GND.

Now that Sonoff waits for flashing, send it the firmware.

It’s alive!

Congratulations! You are now the proud owner of a hacked Sonoff device with custom firmware!

Make sure to read Homie’s Getting started page. You’ll need to focus on how to configure the WIFI and MQTT broker, look out the Configuration – HTTP JSON API (direct links to mobile app and web page).

Flashing the board from Platform IO
Platform IO code and console
Platform IO code

Testing the Device


In order to make sure it does work:

  1. Unplug everything, you don’t want to fry the Sonoff nor yourself;
  2. Connect an AC cable to the input of the device;
  3. Plug the cable into main.

Once this is done, the Sonoff should boot into “normal mode”. That is, it’ll do its job.


The homie device will advertise itself to the MQTT broker. For this I like quite a lot to:

  1. Use homie-ota for quick overview of the devices and their capabilities. However its main purpose to make OTA updates;
  2. use MQTT.fx (I’m on Windows) to sniff messages on the broker. I also use it to send messages to the devices.

Software : homie-ota

This is python script starting a web server. You can from there log into the website and it’ll flush details for you.

Make sure you read install / readme and create your own configuration file.

Device details
Devices discovery

Software : MQTT.fx

This is a Windows application showing subscribed topics and giving ability to send messages plus extra stuff. It will be a kind of a serial output for all your devices at once. As this can be pretty verbose, you can restrict (“subscribe”) to specific topics only.

For a more generic “hacker” proof tool, see mosquitto_pub and mosquitto_sub.

Platform IO code and console

Final Words

We’ve covered quite a lot of subjects to “just flash a firmware”.

This is however the very core subject of this kind of IoT devices hacking. You need to connect all of them together and connect them to the real world.

Since my previous instructables about “home automation”, this is the first time real world gets affected. How exciting!

Make sure to look out:

Hmm, looks like I should write a PiDome (on Twitter, a lot more up-to-date infos) instructable now 🙂


This article was originally posted by me to my Instructables.

Post Author: Shut

Leave a Reply

Your email address will not be published. Required fields are marked *