Getting MicroPython on a Sonoff Smart Switch
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.
Hacking the Hardware
ESP8266 if programmed via the serial port. Both Sonoff Basic and Sonoff Dual have it on the PCD:
You may need to solider a pin header on the PCB to easily connect a USB-UART adapter.
Hacking the Software
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 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 solider 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:
esptool.py --port /dev/ttyUSB0 erase_flash
You may need to run
esptool.py as a superuser to access the serial port.
If the erasure was successful, cut the board’s power, boot the ESP8266 in the Flash Mode again, and flash your firmware:
esptool.py --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!
Welcome to MicroPython!
For online docs please visit http://docs.micropython.org/en/latest/esp8266/ .
For diagnostic information to include in bug reports execute 'import port_diag'.
Basic WiFi configuration:
sta_if = network.WLAN(network.STA_IF); sta_if.active(True)
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>")
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)
With Cloud4RPi, you can control your Raspberry Pi and other IoT devices remotely in real time. Visit our site and connect unlimited devices for free.