How to Flash MicroPython Firmware on a ESP8266 Based Sonoff Smart Switch





Introduction: How to Flash MicroPython Firmware on a ESP8266 Based Sonoff Smart Switch

What’s Sonoff?

Sonoff is a device line for Smart Home developed by ITEAD. One of the most flexible and inexpensive devices from that line are Sonoff Basic and Sonoff Dual. These are Wi-Fi enabled switches based on a great chip, ESP8266. While the Sonoff infrastructure may work quite well for basic users, others may want to hack into that hardware and run their own code on it. The hardware of Sonoff Smart Switches is amazing, considering its low price:

  • ESP8266 with 1MB flash
  • 220V AC integrated power adapter
  • 10A Relay (or two in Sonoff Dual)
  • Onboard LED (or two in Sonoff Dual)
  • Onboard Button

If you want to take a full control over this hardware using your favorite programming language, this tutorial is for you.

Step 1: Hacking the Hardware

ESP8266 is programmed via the serial port. Both Sonoff Basic and Sonoff Dual have it on the PCD.

You may need to solder a pin header on the PCB to easily connect a USB-UART adapter.

Step 2: Preparing to Hacking the Software

I love Python, so I’m going to use the MicroPython firmware. You can also use any supported SDK. Let’s proceed to flashing MicroPython instead of the proprietary Sonoff firmware:

Install the esptool python package that makes flashing the ESP8266 easier:

pip install esptool 

Download the latest stable MicroPython firmware from the MicroPython downloads page. Connect a USB-UART adapter to the board. For safety, it’s recommended to power the board from the adapter instead of the 220V AC socket. Note that you may only use 3.3V, if you connect the ESP8266 chip to a 5V power source, it will die.

Boot ESP8266 into the Flash Mode. You can do it by pulling down the GPIO0 pin while powering the device on:

  • On Sonoff Basic, the GPIO0 is simply the button. Connect the USB-UART adapter to your PC while holding the button and you are in the Flash Mode.
  • On Sonoff Dual, things are a bit harder. You need to short circuit two pads on the PCB while powering the board. The required pads are shown on the picture above. Use tweezers or solder a small wire between them.

When the ESP8266 is in the Flash Mode, the board’s LED should not flash.

Make sure that you can access the serial port opened by the the USB-UART adapter. On Linux it’s probably \dev\ttyUSB0, on Mac you should search for something like “usbserial” or “usbmodem” in the ls \dev\cu.* or ls \dev\tty.* command output, on Windows it should be COM3 or higher. Install the USB-UART adapter drivers if necessary.

Erase the flash using the esptool. Replace the /dev/ttyUSB0 for your port if required: --port /dev/ttyUSB0 erase_flash

You may need to run as a superuser to access the serial port.

Step 3: Flashing

If the erasure was successful, cut the board’s power, boot the ESP8266 in the Flash Mode again, and flash your firmware: --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-20170823-v1.9.2.bin

If the flashing was successful, cut the board’s power, connect it again without pressing the button, and open the serial port in a terminal. On Linux and Mac you can use screen /dev/ttyUSB0 115200 (replace the /dev/ttyUSB0 for your port if required), on Windows you can use PuTTY (the default baud rate is 115200). Once you connect, press Enter, and if you see three angle brackets of Python shell, than everything works!

>>> help() Welcome to MicroPython! For online docs please visit . For diagnostic information to include in bug reports execute 'import port_diag'. Basic WiFi configuration: import network sta_if = network.WLAN(network.STA_IF); sta_if.scan() # Scan for available access points sta_if.connect("<AP_name>", "<password>") # Connect to an AP sta_if.isconnected() # Check for successful connection # Change name/password of ESP8266's AP: ap_if = network.WLAN(network.AP_IF) ap_if.config(essid="<AP_NAME>", authmode=network.AUTH_WPA_WPA2_PSK, password="<password>") Control commands: CTRL-A -- on a blank line, enter raw REPL mode CTRL-B -- on a blank line, enter normal REPL mode CTRL-C -- interrupt a running program CTRL-D -- on a blank line, do a soft reset of the board CTRL-E -- on a blank line, enter paste mode For further help on a specific object, type help(obj) >>>

In the next instructable, we will describe how to interact with the Cloud4RPi platform via an MQTT protocol.



    • Epilog Challenge 9

      Epilog Challenge 9
    • Paper Contest 2018

      Paper Contest 2018
    • Pro Tips Challenge

      Pro Tips Challenge

    We have a be nice policy.
    Please be positive and constructive.




    It took me forever to find out why this does not work for me. The system *seems* to be flashing, but I could not get the prompt. Turns out I needed to set the flashmode to dout (us the flag -fm dout when uploading the firmware ) for this to work properly. This is probably because of the version of the esp8266 chip used (pure speculation on my part)

    See for more info.

    sudo --port /dev/ttyUSB0 --baud 460800 write_flash --verify --flash_size=detect -fm dout 0x0 ~/Downloads/esp8266-20171101-v1.9.3.bin

    Thank you for the great advice!

    Maybe it would be nice to have an example what to to with the Sonoff once it is flashed?

    Sure, we are going to publish an instructable about its usage soon

    You lost me... so if I'm using a Windows machine, do I need to have Python installed on it and run the esptools in that Python install?

    Yes, you are right - you need to install Python and then install esptools