Skip to content
MicroPython project to free the Sonoff WiFi Smart Socket from the cloud by run a webserver on the device.
Python HTML Makefile Other
Branch: master
Clone or download
Pull request Compare This branch is 9 commits behind jedie:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
docker-yaota8266 @ 6a79743


badge.svg badge.svg badge.svg

MicroPython project to free the Sonoff WiFi Smart Socket from the cloud by run a webserver on the device.

Tested devices:

  • Sonoff S20 (Easy to connect. Solder joints prepared.)
  • Sonoff S26 (Harder to connect: Solder joints very small.)


  • web interface
  • schedule multiple timers
  • Handle time zones (set you time zone via web page)
  • Display an editable device name (Helpful if you have more than one device ;) )
  • The device name will also be used as DHCP hostname
  • OTA updates (currently without directory support)
  • turn the switch on/off by the web page or the device button
  • checkbox for each day of the week where timers are active
  • Reset the device by long pressing the button
  • supports multiple WIFI credentials
  • NTP sync

The device will do this on every boot:

  • boot
  • connect to your WiFi
  • get current time via ntp
  • make OTA Update (timeout: 15sec.)
  • serve web page

Some notes about the timer functionality:

The Device always tries to turn the power ON/OFF based on the current timer. Even after a power failure. However, this only works correctly if the current time is set correctly by the RTC. The current time is automatically retrieved from the Internet via NTP sync. At boot and also repeated after start. Of course, this can only work if the device is connected to the Internet via WiFi ;)

You can "overwrite" the current timer at any time by pressing the button on the device. This overwrite will stay until the next timer. After a power failure the "overwrite" information is deleted and the timer regulates the power again.


Things that will be implement in the near feature:

  • Insert new WiFi settings via web page
  • timer toggle flag to reverse: power is switched off during the specified periods

further away:

  • different timers for every weekday
  • Support directories via OTA Updates


The Web Page looks like this:

screenshot 1

screenshot 2

screenshot 3

screenshot 4

screenshot 5

All existing screenshots can be found here:


  • Open the device
  • make a connection with a UART-USB converter with 3.3V option and to the 3.3V, GND, TX and RX pins

Very good information to get started can you found here:


Clone the sources, and setup virtualenv via pipenv:

~$ git clone
~$ cd micropython-sonoff-webswitch
~/micropython-sonoff-webswitch$ make update


  • Generate yaota8266 RSA keys, create config.h and compile yaota8266 and firmware
  • Flash yaota8266 and firmware
  • format device flash to littlefs2 with: helpers/
  • create _config_wifi.json
  • Connect device to WiFi
  • start soft-OTA to put all missing files to the device

compile own firmware

To see all make targets, just call make, e.g.:

~/micropython-sonoff-webswitch$ make
make targets:
  help                     This help page
  docker-pull              pull docker images
  docker-build             pull and build docker images
  update                   update git repositories/submodules, virtualenv, docker images and build local docker image
  test                     Run pytest
  micropython_shell        start a bash shell in docker container "local/micropython:latest"
  unix-port-shell          start micropython unix port interpreter
  build-firmware-combined  compiles the micropython non-OTA firmware and store it here: /build/firmware-combined.bin
  build-ota-firmware       compiles the micropython OTA firmware and store it here: /build/firmware-ota.bin
  yaota8266-rsa-keys       Pull/build yaota8266 docker images and Generate RSA keys and/or print RSA modulus line for copy&paste into config.h
  yaota8266-build          Compile ota bootloader and store it here: build/yaota8266.bin
  verify                   Check RSA key, config.h and compiled "yaota8266.bin"
  erase-flash              call erase_flash
  flash-firmware-combined  Flash build/firmware-combined to location 0x3c000 via
  flash-yaota8266          Flash build/yaota8266.bin to location 0x0 via
  flash-ota-firmware       Flash build/firmware-ota.bin to location 0x3c000 via
  hard-ota                 Start yaota8266 live-ota to hard-OTA Update the firmware file build/firmware-ota.bin.ota
  soft-ota                 Start soft-OTA updates: Compile .py to .mpy and push missing/updated files (*.mpy, *.css, *.html etc.) to the device
  miniterm                 Low level debug device via (from pyserial) to /dev/ttyUSB0


You must create docker-yaota8266/yaota8266/config.h and insert your RSA modulus line.

To generate your RSA keys and display the needed line for config.h just call:

~/micropython-sonoff-webswitch$ make yaota8266-rsa-keys
Copy&paste this RSA modulus line into your config.h:
#define MODULUS "\xce\x4a\xaf\x65\x0d\x4a\x74\xda\xc1\x30\x59\x80\xcf\xdd\xe8\x2a\x2e\x1d\xf7\xa8\xc9\x6c\xa9\x4a\x2c\xb7\x8a\x5a\x2a\x25\xc0\x2b\x7b\x2f\x58\x4c\xa8\xcb\x82\x07\x06\x08\x7e\xff\x1f\xce\x47\x13\x67\x94\x5f\x9a\xac\x5e\x7d\xcf\x63\xf0\x08\xe9\x51\x98\x95\x01"

The generated RSA key files are here:

  • docker-yaota8266/yaota8266/ota-client/priv.key
  • docker-yaota8266/yaota8266/ota-client/pub.key

You should backup theses files;


After you have created your own RSA keys and config.h, you can compile yaota8266.bin and firmware-ota.bin, e.g.:

~/micropython-sonoff-webswitch$ make yaota8266-build
~/micropython-sonoff-webswitch$ make build-firmware

The compiled files are stored here:

  • ~/micropython-sonoff-webswitch/build/yaota8266.bin
  • ~/micropython-sonoff-webswitch/build/firmware-ota.bin <- for flashing
  • ~/micropython-sonoff-webswitch/build/firmware-ota.bin.ota <- used in hard-OTA process

flash yaota8266 and firmware

After you have called make yaota8266-build and make build-firmware you can flash your device:

~/micropython-sonoff-webswitch$ make flash-yaota8266
~/micropython-sonoff-webswitch$ make flash-firmware

Importand: the flash make targets are for the Sonoff ESP8266 and may not work on other ESP8266 devices!

For other devices just use esptool directly, e.g.:

~/micropython-sonoff-webswitch$ pipenv run --port /dev/ttyUSB0 --baud 460800 write_flash 0 build/yaota8266.bin
~/micropython-sonoff-webswitch$ pipenv run --port /dev/ttyUSB0 --baud 460800 write_flash 0x3c000 build/firmware-ota.bin


The file firmware-ota.bin must be flash with not the firmware-ota.bin.ota ! This file is ues in hard-OTA update process.

flash micropython


  • Press and hold the power button before connecting
  • Connect device via UART-USB converter
  • Now you can release the button.
  • To erase the Flash with esptool, call: ./
  • disconnect the device from PC and reconnect with pressed button again
  • To flash micropython call: ./ (This script will download micropython, if not already done and compares the sha256 hash)
  • disconnect device and reconnect without pressing the power button

Notes: In my experience flashing the S20 needs -fs 1MB -fm dout 0x0.


The micropython version and the mpy_cross version must be the same! Otherwise the compiled .mpy can't run on the device!

WiFi config

To connect the device with your WIFI it needs the SSID/password. Several WLAN network access data can be specified.

Copy and edit _config_wifi-example.json to src/_config_wifi.json


If micropython is on the device, only the sources and your WiFi credentials file needs to be uploaded.

This 'bootstrapping' can be done in different ways.

bootstrap via USB

Connect device via TTL-USB-converter to your PC and run

This script will do this:

  • compile src files with mpy-cross to bdist
  • upload all files from bdist to the device via mpycntrl

The upload is a little bit slow. Bootstrap via WiFi is faster, see below:

bootstrap via WiFi


  • Connect the device to your WiFi network
  • put your _config_wifi.json to the root of the device
  • Run to upload all *.mpy compiled files

I used thonny for this. With thonny it's easy to upload the config file and execute scripts on the device.

To connect to your WiFi network, edit and run this:

import time, network
sta_if = network.WLAN(network.STA_IF)
sta_if.connect('your-ssid', 'Your-WiFi-Password')
while not sta_if.isconnected():
print('connected:', sta_if.ifconfig())

OTA updates

Note: There are two kinds of OTA updates:

  • 'hard' OTA update via yaota8266 bootloader that will replace the complete firmware.
  • 'soft' OTA updates via pure micropython script that will only upload new files to the flash filesystem.

The 'hard' OTA via yaota8266 is work-in-progress and will currenlty not work, see:

'soft' OTA updates

After the initial setup and when everything is working and the device is connected to your wlan, you can use OTA updates.

The device will run the /src/ on every boot.

The script waits some time for the OTA server and after the timeout the normal web server will be started.

To start the OTA Server, do this:

~$ cd micropython-sonoff-webswitch
~/micropython-sonoff-webswitch$ pipenv run

If server runs: reboot device and look to the output of the OTA server.

The OTA update implementation does:

  • compare device micropython version with installed mpy_cross version (If not match: deny update)
  • send only new/changed files
  • remove existing .py file on the device if .mpy file was send
  • replace existing files only after correct sha hash verify

project structure

  • ./bdist/ - Contains the compiled files that will be uploaded to the device.
  • ./helpers/ - Some device tests/helper scripts for developing (normaly not needed)
  • ./mpy_tests/ - tests that can be run on micropython device (will be also run by pytest with mocks)
  • ./ota/ - source code of the OTA server
  • ./src/ - device source files
  • ./tests/ - some pytest files (run on host with CPython)
  • ./utils/ - utils for local run (compile, code lint, sync with mpycntrl)
  • ./ - Starts the local OTA server (will compile, lint the src files and create bdist)
  • ./ - Upload files via USB (will compile, lint the src files and create bdist)


sub project links

Forum links


You can’t perform that action at this time.