{"id":15662377,"url":"https://github.com/jedie/micropython-sonoff-webswitch","last_synced_at":"2025-05-05T23:25:21.130Z","repository":{"id":137348293,"uuid":"220410172","full_name":"jedie/micropython-sonoff-webswitch","owner":"jedie","description":"MicroPython project to free the Sonoff WiFi Smart Socket from the cloud by run a webserver on the device.","archived":false,"fork":false,"pushed_at":"2022-10-18T19:37:41.000Z","size":496,"stargazers_count":19,"open_issues_count":4,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-07T03:02:31.879Z","etag":null,"topics":["esp8266","micropython","micropython-esp8266","python","web-application","webserver","wifi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jedie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-08T07:23:52.000Z","updated_at":"2024-05-24T05:03:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"47ce3f82-f9ab-44b4-b39d-c271919620d4","html_url":"https://github.com/jedie/micropython-sonoff-webswitch","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fmicropython-sonoff-webswitch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fmicropython-sonoff-webswitch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fmicropython-sonoff-webswitch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedie%2Fmicropython-sonoff-webswitch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jedie","download_url":"https://codeload.github.com/jedie/micropython-sonoff-webswitch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252591750,"owners_count":21773143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp8266","micropython","micropython-esp8266","python","web-application","webserver","wifi"],"created_at":"2024-10-03T13:32:11.912Z","updated_at":"2025-05-05T23:25:21.117Z","avatar_url":"https://github.com/jedie.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# micropython-sonoff-webswitch\n\n![badge.svg](https://github.com/jedie/micropython-sonoff-webswitch/workflows/Run%20Tests/badge.svg?branch=master)\n![badge.svg](https://github.com/jedie/micropython-sonoff-webswitch/workflows/Compile%20yaota8266.bin/badge.svg?branch=master)\n![badge.svg](https://github.com/jedie/micropython-sonoff-webswitch/workflows/Compile%20MicroPython%20Firmware/badge.svg?branch=master)\n\nMicroPython project to free the Sonoff WiFi Smart Socket from the cloud by run a webserver on the device.\n\nTested devices:\n\n* Sonoff S20 (Easy to connect. Solder joints prepared.)\n* Sonoff S26 (Harder to connect: Solder joints very small.)\n\n\n## Features\n\n* web interface\n* schedule multiple timers\n* Handle time zones (set you time zone via web page)\n* Display an editable device name (Helpful if you have more than one device ;) )\n* The device name will also be used as DHCP hostname\n* OTA updates (currently without directory support)\n* turn the switch on/off by the web page or the device button\n* checkbox for each day of the week where timers are active\n* Reset the device by long pressing the button\n* supports multiple WIFI credentials\n* NTP sync\n\nThe device will do this on every boot:\n\n* boot\n* connect to your WiFi\n* get current time via ntp\n* make OTA Update (timeout: 15sec.)\n* serve web page\n\nSome notes about the timer functionality:\n\nThe Device always tries to turn the power ON/OFF based on the current timer. Even after a power failure.\nHowever, this only works correctly if the current time is set correctly by the RTC.\nThe current time is automatically retrieved from the Internet via NTP sync. At boot and also repeated after start.\nOf course, this can only work if the device is connected to the Internet via WiFi ;)\n\nYou can \"overwrite\" the current timer at any time by pressing the button on the device.\nThis overwrite will stay until the next timer.\nAfter a power failure the \"overwrite\" information is deleted and the timer regulates the power again.\n\n\n## Roadmap\n\nThings that will be implement in the near feature:\n\n* Insert new WiFi settings via web page\n* timer toggle flag to reverse: power is switched off during the specified periods\n\nfurther away:\n\n* different timers for every weekday\n* Support directories via OTA Updates\n\n\n## Screenshot\n\n\nThe Web Page looks like this:\n\n![screenshot 1](https://raw.githubusercontent.com/jedie/jedie.github.io/master/screenshots/WebSwitch/2019-12-14%20Sonoff%20S20%20WebServer%20v0.8.1a.png)\n\n![screenshot 2](https://raw.githubusercontent.com/jedie/jedie.github.io/master/screenshots/WebSwitch/2019-12-14%20Sonoff%20S20%20WebServer%20v0.8.1b.png)\n\n![screenshot 3](https://raw.githubusercontent.com/jedie/jedie.github.io/master/screenshots/WebSwitch/2019-12-14%20Sonoff%20S20%20WebServer%20v0.8.1c.png)\n\n![screenshot 4](https://raw.githubusercontent.com/jedie/jedie.github.io/master/screenshots/WebSwitch/2019-12-14%20Sonoff%20S20%20WebServer%20v0.8.1d.png)\n\n![screenshot 5](https://raw.githubusercontent.com/jedie/jedie.github.io/master/screenshots/WebSwitch/2019-12-14%20Sonoff%20S20%20WebServer%20v0.8.1e.png)\n\n\nAll existing screenshots can be found here:\n\n* [jedie.github.io/blob/master/screenshots/WebSwitch/](https://github.com/jedie/jedie.github.io/blob/master/screenshots/WebSwitch/README.creole)\n\n\n### OTA overview\n\n![ESP8266_OTA.png](https://raw.githubusercontent.com/jedie/jedie.github.io/master/diagrams/micropython/ESP8266_OTA.png)\n\n\n\n# setup a device\n\n\n## prepare the hardware:\n\n* Open the device\n* make a connection with a UART-USB converter with 3.3V option and to the `3.3V`, `GND`, `TX` and `RX` pins\n* **WARNING:** DO NOT CONNECT DEVICES TO MAINS POWER WHILE THE COVER IS OPEN AND CIRCUIT BOARD IS EXPOSED!!!\n\nVery good information to get started can you found here:\n\n- https://templates.blakadder.com/sonoff_S20.html\n- https://github.com/tsaarni/mqtt-micropython-smartsocket\n\n\n## Overview of installing the software on the device:\n\n* Generate yaota8266 RSA keys, create `config.h` and compile yaota8266 and firmware\n* Flash yaota8266 and firmware\n* create `_config_wifi.json`\n* Connect device to WiFi\n* start soft-OTA to put all missing files to the device\n\n\n## setup project\n\nClone the sources, and setup virtualenv via `pipenv`:\n```bash\n~$ git clone https://github.com/jedie/micropython-sonoff-webswitch.git\n~$ cd micropython-sonoff-webswitch\n~/micropython-sonoff-webswitch$ make update\n```\n\nTo see all make targets, just call make, e.g.:\n```bash\n~/micropython-sonoff-webswitch$ make\nmake targets:\n  help                     This help page\n  docker-pull              pull docker images\n  docker-build             pull and build docker images\n  update                   update git repositories/submodules, virtualenv, docker images and build local docker image\n  thonny                   run Thonny IDE to access the Micropython REPL (Python prompt)\n  test                     Run pytest\n  micropython_shell        start a bash shell in docker container \"local/micropython:latest\"\n  unix-port-shell          start micropython unix port interpreter\n  build-firmware-combined  compiles the micropython non-OTA firmware and store it here: /build/firmware-combined.bin\n  build-ota-firmware       compiles the micropython OTA firmware and store it here: /build/firmware-ota.bin\n  yaota8266-rsa-keys       Pull/build yaota8266 docker images and Generate RSA keys and/or print RSA modulus line for copy\u0026paste into config.h\n  yaota8266-build          Compile ota bootloader and store it here: build/yaota8266.bin\n  verify                   Check RSA key, config.h and compiled \"yaota8266.bin\"\n  erase-flash              call esptool.py erase_flash\n  flash-firmware-combined  Flash build/firmware-combined to location 0x3c000 via esptool.py\n  flash-yaota8266          Flash build/yaota8266.bin to location 0x0 via esptool.py\n  flash-ota-firmware       Flash build/firmware-ota.bin to location 0x3c000 via esptool.py\n  hard-ota                 Start yaota8266 live-ota to hard-OTA Update the firmware file build/firmware-ota.bin.ota\n  soft-ota                 Start soft-OTA updates: Compile .py to .mpy and push missing/updated files (*.mpy, *.css, *.html etc.) to the device\n  miniterm                 Low level debug device via miniterm.py (from pyserial) to /dev/ttyUSB0\n```\n\n## compile own firmware\n\n### docker-yaota8266/yaota8266/config.h\n\nYou must create `docker-yaota8266/yaota8266/config.h` and insert your RSA modulus line.\n\nTo generate your RSA keys and display the needed line for `config.h` just call:\n```bash\n~/micropython-sonoff-webswitch$ make yaota8266-rsa-keys\n...\nCopy\u0026paste this RSA modulus line into your config.h:\n----------------------------------------------------------------------------------------------------\n#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\"\n----------------------------------------------------------------------------------------------------\n```\n\nThe generated RSA key files are here:\n\n* `docker-yaota8266/yaota8266/ota-client/priv.key`\n* `docker-yaota8266/yaota8266/ota-client/pub.key`\n\nYou should backup theses files;\n\n\n### compile\n\nAfter you have created your own RSA keys and `config.h`, you can compile `yaota8266.bin` and `firmware-ota.bin`, e.g.:\n```bash\n~/micropython-sonoff-webswitch$ make yaota8266-build\n~/micropython-sonoff-webswitch$ make build-ota-firmware\n```\n\nThe compiled files are stored here:\n\n* `~/micropython-sonoff-webswitch/build/yaota8266.bin`\n* `~/micropython-sonoff-webswitch/build/firmware-ota.bin` \u003c- for flashing\n* `~/micropython-sonoff-webswitch/build/firmware-ota.bin.ota` \u003c- used in hard-OTA process\n\n\n### Deploying the firmware: flash yaota8266 and firmware\n\nESP8266 needs to be put into Programming Mode before the firmware can be uploaded. To put the ESP8266 into Programming Mode:\n\n* Press and hold the power button before connecting\n* Connect device via UART-USB converter\n* After about 2 seconds: release the button\n\nMaybe you must give the user the permissions to access the USB Port, e.g.: `sudo usermod -a -G dialout $USER` Otherwise you will get a error message like: `Permission denied: '/dev/ttyUSB0'`\n\nNow `esptool` can be used. But only for *one* operation! After each esptool call, you must disconnect the device from the USB and repeat this procedure!\n\nThe first time, the flash memory must be erased, call:\n\n```bash\n~/micropython-sonoff-webswitch$ make erase-flash\n```\n\nAfter `erase-flash` and after you have called `make yaota8266-build` and `make build-ota-firmware` you can flash your device:\n\n```bash\n# put into Programming Mode and call:\n~/micropython-sonoff-webswitch$ make flash-yaota8266\n\n# Again, put into Programming Mode and call:\n~/micropython-sonoff-webswitch$ make flash-ota-firmware\n```\n\n**Importand**: These flash commands are for the Sonoff device and may **not work** on other ESP8266 devices!\n\nFor other devices just use `esptool` directly, e.g.:\n```bash\n~/micropython-sonoff-webswitch$ pipenv run esptool.py --port /dev/ttyUSB0 write_flash 0 build/yaota8266.bin\n~/micropython-sonoff-webswitch$ pipenv run esptool.py --port /dev/ttyUSB0 write_flash 0x3c000 build/firmware-ota.bin\n```\n\n**Note:**\n\nThe file `firmware-ota.bin` must be flash with `esptool.py` **not** the `firmware-ota.bin.ota` ! This file is ues in hard-OTA update process.\n\nMore information about flashing can be found in the official documentation here: http://docs.micropython.org/en/latest/esp8266/tutorial/intro.html\n\n### access the Micropython REPL\n\nOnce you have the firmware on the device you can access the Micropython REPL (Python prompt).\nThere are different ways to do this. I used [thonny](https://github.com/thonny/thonny/) and his [MicroPython support](https://github.com/thonny/thonny/wiki/MicroPython)\n\n`thonny` is installed via pipenv, to start the IDE, just call:\n```bash\n~/micropython-sonoff-webswitch$ make thonny\n```\n\nFirst steps in thonny:\n* Activate ESP8266 mode: `Tools / Options / Interpreter` select: `MicroPython (ESP8266)`\n* Activate `files` Tab: `View / Files`\n\nNow you should be able to access the Micropython REPL via `Ctrl-F2`.\nYou can also start scripts on the device:\n\n* In `This computer` TAB go to: `.../micropython-sonoff-webswitch/helpers`\n* Open a file by double-click e.g.: `mpy_information.py` in the editor\n* Run the script on the device by `F5`\n\n### copy missing files to the device\n\nAfter format the flash filesystem as `littlefs2`: copy missing files to the device, using soft-OTA:\n\n* Connect Device to your WiFi network\n* start soft-OTA client and server\n\n\n#### create src/_config_wifi.json\n\nThe device needs SSID/passwords to be able to log in to different WLANs. It reads the credentials from the file `_config_wifi.json`. This file must be created. The template is [_config_wifi-example.json](https://github.com/jedie/micropython-sonoff-webswitch/blob/master/_config_wifi-example.json).\n\nCopy and edit [_config_wifi-example.json](https://github.com/jedie/micropython-sonoff-webswitch/blob/master/_config_wifi-example.json) to `src/_config_wifi.json`\n\nAll missing files in `src` will be copied to device via soft-OTA.\n\n\n#### connect device to WiFi\n\nTo connect the device on the fist start to your WiFi network, edit and run this:\n\n```python\nimport time, network\nsta_if = network.WLAN(network.STA_IF)\nsta_if.active(True)\nsta_if.connect('your-ssid', 'Your-WiFi-Password')\nwhile not sta_if.isconnected():\n    time.sleep(0.5)\nprint('connected:', sta_if.ifconfig())\n```\n\nJust copy\u0026paste this code snippet into Thonny IDE, insert your credentials and run it via `F5`\n\n\n### run soft-OTA manually\n\nAfter the device is connected to your WiFi, it can run soft-OTA and copy all missing `src` files.\n\nStart soft-OTA server with:\n```bash\n~/micropython-sonoff-webswitch$ make soft-ota\n```\n\nAt the same time, open [.../micropython-sonoff-webswitch/src/ota_client.py](https://github.com/jedie/micropython-sonoff-webswitch/blob/master/src/ota_client.py) in Thonny and start it via `F5`.\n\n\nNow the soft-OTA should be run:\n\n* The device will be connected\n* All missing/new files from `src` will be transfered to the device\n\n\nNow the device setup is done ;)\n\n\n### OTA updates\n\n**Note**: There are two kinds of OTA updates:\n\n* 'hard' OTA update via **yaota8266** bootloader that will replace the complete firmware.\n* 'soft' OTA updates via pure micropython script that will only upload new files to the flash filesystem.\n\nThe 'hard' OTA via **yaota8266** is work-in-progress, see: https://github.com/jedie/micropython-sonoff-webswitch/issues/33\n\n#### 'soft' OTA updates\n\nAfter the initial setup and when everything is working and the device is connected to your wlan, you can use OTA updates.\n\nThe device will run the [/src/ota_client.py](https://github.com/jedie/micropython-sonoff-webswitch/blob/master/src/ota_client.py) on every boot.\n\nThe script waits some time for the OTA server and after the timeout the normal web server will be started.\n\nTo start the `soft-OTA Server`, do this:\n\n```bash\n~/micropython-sonoff-webswitch$ make soft-ota\n```\n\nIf server runs: reboot device and look to the output of the OTA server.\n\nThe OTA update implementation does:\n\n* compare device micropython version with installed `mpy_cross` version (If not match: deny update)\n* send only new/changed files\n* remove existing `.py` file on the device if `.mpy` file was send\n* replace existing files only after correct sha hash verify\n\n\n## project structure\n\n* `./bdist/` - compiled `.mpy` files (and `.html`, `.css` files) that will be uploaded to the device in `soft-OTA`\n* `./build/` - compiled firmware files (`firmware-*.bin` and `yaota8266.bin`) for flashing and `hard-OTA`\n* `./docker-yaota8266/` - git submodule https://github.com/jedie/docker-yaota8266 to compile yaota8266.bin via docker\n* `./helpers/` - Some device tests/helper scripts for bootstrap and developing\n* `./micropython_config/` - Config files used to compile MicroPython Firmware\n* `./mpy_tests/` - tests that can be run on micropython device (will be also run by pytest with mocks)\n* `./sdist/` - Contains all modules that will be freezes into firmware, created via `utils/make_sdist.py`\n* `./soft_ota/` - source code of the OTA server\n* `./src/` - device source files\n* `./tests/` - some pytest files (run on host with CPython)\n* `./utils/` - utils for local run (compile, code lint, sync with mpycntrl)\n\n\n## Links\n\n### sub project links\n\n* Compile `yaota8266.bin` via docker: https://github.com/jedie/docker-yaota8266\n* Compile micropython firmware via docker: https://github.com/jedie/docker-micropython\n\n### Forum links\n\n* OTA updates: https://forum.micropython.org/viewtopic.php?f=2\u0026t=7300\n* free RAM: https://forum.micropython.org/viewtopic.php?f=2\u0026t=7345\n\n### misc\n\n* S20 Wifi Smart Socket Schematic: https://www.itead.cc/wiki/S20_Smart_Socket\n\n\n## history\n\n\n- *dev* - [compare v0.12.0...master](https://github.com/jedie/micropython-sonoff-webswitch/compare/v0.12.0...master)\n  - TBC\n- v0.12.0 - 2020-02-06 - [compare v0.11.1...v0.12.0](https://github.com/jedie/micropython-sonoff-webswitch/compare/v0.11.1...v0.12.0)\n  - Refactory reset handling: Reset only after 7h WiFi/NTP lost\n- ...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedie%2Fmicropython-sonoff-webswitch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjedie%2Fmicropython-sonoff-webswitch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedie%2Fmicropython-sonoff-webswitch/lists"}