Flashing a Custom Firmware to Sonoff wifi switch with Arduino IDE

Sonoff wifi switches work quite well with the default firmware. However if you want to do more than the basic operations or integrate with your home automation system then you need to flash it with your custom firmware.

The Sonoff Basic comes with a ESP8266 chip with power supply, relay switch, a push button and an LED in a nice small case. We are going to write a custom firmware on the ESP8266 chip.


  • Sonoff Basic wifi switch.
  • 3.3V FTDI USB-to-Serial converter.
  • A computer with Arduino IDE (I used version 1.8.5 on Mac OS).
  • Basic knowledge of electronics and some soldering skills.

Preparing the Software:

  1. Install the latest version of Arduino IDE.
  2. Open Arduino IDE and go to Preferences.
  3. Under Additional Boards Manager URLs field, enter http://arduino.esp8266.com/stable/package_esp8266com_index.json (separate multiple URLs by comma).
  4. Open Tools > Board > Boards Manager.
  5. Search for ESP8266 and install.
Arduino Preferences — Additional Boards Manager URLs
Boards Manager — Install ESP8266

Preparing the Hardware:

Add header pins to Sonoff board

This is a Sonoff Basic switch.

Sonoff Basic

When you open it up, you can find a board with the ESP8266 chip, relay, LED, push button and other components.

  • Identify the 5 pin holes next to the push button.
  • Insert pin headers and solder it.

The pins, starting from the push button are:

  1. 3.3V
  2. RX
  3. TX
  4. GND
  5. GPIO14 (we won’t use this pin)

The Sonoff board is ready for flashing.

Connect the USB-to-Serial convertor to the Sonoff board

To connect the ESP8266 (on the Sonoff board) to your computer, you need a 3.3V FTDI USB-to-Serial converter.

Note: You need to install drivers for the FTDI converter (refer your vendor website).

Attach wires to the FTDI converter pins 3.3V, Tx, Rx and Gnd.

Note: Some converters have a single Vcc pin with jumper to switch between 5V and 3.3V. Make sure you have it set to 3.3V.

Now, connect the FTDI converter pins with the ESP8266 pins (on the Sonoff board) as follows:

FTDI converter → Sonoff ESP8266

  1. 3.3V → 3.3V
  2. Tx → Rx
  3. Rx → Tx
  4. Gnd → Gnd

Flash Mode

Now that the hardware and software is ready. We can try uploading a cutom firmware to the Sonoff switch. To do this, we need to boot the ESP8266 in flash mode.

  • Do not plug into the USB on your computer.
  • Do not connect the Sonoff to mains power.
  • Press and hold the push button on the Sonoff board.
  • Insert the FTDI converter USB in your computer (while holding the push button).
  • After 2–3 seconds, release the push button.
  • Now it’s in flash mode.

Upload Firmware

Test Simple Firmware

Start by testing a simple program to blink the LED.

The built-in LED in the Sonoff switch is connected to the GPIO-13 pin with active low (the LED will be ON when the pin is LOW).

Verify, Compile and upload

  • Load the sketch file in Arduino IDE
  • Click on Verify / Compile.
  • Check the settings….

Custom Firmware for On / Off Control

Now that we got the basic example working, we can connect to wifi and run a simple web server to listen to /on and /off commands and control the relay.

Repeat same steps (verify, compile and upload). You can modify the firmware to do more. Enjoy :)


Arduino Upload Error: espcomm_open failed:

I spent a lot of time debugging the software and configuration but later found out the issue was with a dry soldering joint on one of the pins. Fixing the soldering fixed the issue for me.

Wifi connects for the first time, but fails if ESP8266 is restarted:

This is a known issue with ESP8266 core for Arduino as of version 2.3.0. Use the following code for workaround.

if (WiFi.status() != WL_CONNECTED) {
WiFi.begin(ssid, password);

(Read mode about the issue here)

Reference Links:


ESP8266 wiki:


ESP8266 wifi connection issue: