{"id":15962200,"url":"https://github.com/albertogeniola/micropython-wol","last_synced_at":"2025-06-29T11:36:52.125Z","repository":{"id":222023830,"uuid":"522621487","full_name":"albertogeniola/Micropython-WoL","owner":"albertogeniola","description":"Micropython utility that runs on a ESP32 used to issue wake-on-lan commands via a simple web interface","archived":false,"fork":false,"pushed_at":"2024-04-06T13:21:37.000Z","size":5307,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-09T22:19:17.605Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/albertogeniola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2022-08-08T16:13:17.000Z","updated_at":"2024-04-03T15:10:53.000Z","dependencies_parsed_at":"2024-02-11T21:25:48.169Z","dependency_job_id":"cb157489-0ec0-440c-8a98-94d375a1635f","html_url":"https://github.com/albertogeniola/Micropython-WoL","commit_stats":{"total_commits":76,"total_committers":2,"mean_commits":38.0,"dds":0.02631578947368418,"last_synced_commit":"9dadcb1d146c2c116655c266b3cb1ed6c8f3ab5c"},"previous_names":["albertogeniola/esp32-wol"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertogeniola%2FMicropython-WoL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertogeniola%2FMicropython-WoL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertogeniola%2FMicropython-WoL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertogeniola%2FMicropython-WoL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/albertogeniola","download_url":"https://codeload.github.com/albertogeniola/Micropython-WoL/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247175949,"owners_count":20896378,"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":[],"created_at":"2024-10-07T16:01:54.168Z","updated_at":"2025-04-04T12:24:14.102Z","avatar_url":"https://github.com/albertogeniola.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Micropython WOL: a tiny Wake-on-Lan delegate\n\n\u003cimg src=\"docs/images/case-3d/front_orange.jpg\" height=300\u003e \u003cimg src=\"docs/images/case-3d/interior.jpg\" height=300\u003e\n\n## What is Micropython-WOL?\nMicropython-WoL is a firmware that enables Wake-on-lan functionality on tiny microcontrollers. This utility is written in python and runs on top of microptyhon. \n\nSo far, this utility is compatible with the Expressif ESP32 and the ESP8266 devices.\n\nThis tool is suited for people who want to turn on their PC-devices via Wake-On-Lan,\nbut cannot do that using their current home gateways or have no domotic/server device\nwhere to install such a service.\n\n## Why ESP32/8266?\nBoth devices are a small, cheap, low-power and powerful.\nThis project turns those tiny chips into Wake-On-Lan service providers \nexposed via a self-hosted web-ui, which can be reached from all-over the internet. \n\nOf course, you might use other devices/servers to do the same thing.\nBut, if you don't have any, and you just need a small, power-efficient device to \nturn on you other devices on the network, the Micropython-WoL is what you are looking for.\n\nLet's have a look at some possible alternatives in the following table.\n\n|                     | ESP32-WoL    | Raspberry with HA | Home Server |\n|---------------------|--------------|:-----------------:|------------:|\n| Hardware cost       | \u003c 10 USD     |     ~ 60 USD      |    100+ USD |\n| Power consumption   | \u003c 1 W        |       4~5 W       |      ~ 15 W |\n| Occupied space      | 2 coins size | Credit card size  |   Mini ITX+ |\n| Installation effort | Minimum      |      Medium       |        High |\n\nIn general, if you already have a home-server or a HomeAssistant device in your LAN,\nthen you probably don't need this firmware. \nHowever, there might be various cases in which this utility comes handy.\nFor instance, I needed to run WoL packets into different VLANs: my HomeAssistant device was \nnot able to reach all the subnets segments (and the router correctly forbid magic packet broadcast across vlans). Thus, I've decided to implement this utility.\n\n## Compatible Devices\n\nI've tested the following devices:\n- ESP8266 NodeMCU (CP2102)\n- ESP32-WROOM\n\nMore micropython-enabled microcontrollers might be supported, but I haven't explicitly tested them.\n\n## Flash instructions\n\nThe Micropython-WoL can be installed in two ways:\n- Flashing a pre-compiled firmware **(recommended!)**\n- Flashing the python source on the device\n\n### Option A: Install by flashing the firmware\nThis method is the recommended way of flashing the firmware utility, but only supports a limited\nnumber of hardware microcontrollers: ESP8266_GENERIC, ESP32_GENERIC_S2, ESP32_GENERIC_C3.\n\nThe firmware flash procedure is the following:\n\n1. Download the latest firmware from the [release section of this repository](https://github.com/albertogeniola/Micropython-WoL/releases) or just [grab the latest](https://github.com/albertogeniola/Micropython-WoL/releases/latest).\n2. Ensure you have the right OS serial port-drivers installed for your device (e.g. [CP210X](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers), [CH340](https://learn.sparkfun.com/tutorials/how-to-install-ch340-drivers/all), etc)\n3. Ensure you have a valid python interpreter on your system and install esptool via the following command\n    ```bash\n    python -m pip install esptool adafruit-ampy\n    ```\n4. Run the appropriate flash command, based on your device.\n\n    For the ESP8266, run the following\n    ```bash\n    python -m esptool --chip esp8266 erase_flash\n    python -m esptool --chip esp8266 --port SERIAL_PORT write_flash --flash_mode dio --flash_size detect 0x0 path/to/downloaded/firmware.bin\n    ```\n\n    For the ESP32, run the following\n    ```bash\n    python -m esptool --chip esp8266 esp32\n    python -m esptool -p SERIAL_PORT -b 460800 --chip esp32 write_flash --flash_mode dio 0x1000 path/to/downloaded/firmware.bin\n    ```\n\n\u003e Note: replace **SERIAL_PORT** with the name of the serial port where the device is connected (e.g. COM5). Also, remember to update the firmware path parameter so that it points to the downloaded firmware.\n\n\u003e Note: run the flash command just after connecting the USB cable to the microcontroller, or make sure to press the FLASH button on the controller to enable download more.\n\n### Option B: Install by manual update\nThis installation method is the most general one, but requires you to install the latest micropython firmware on your own, and then upload the python source files directly into the controller.\n\nBefore proceeding with the installation, ensure you have flashed your microcontroller with a micropython firmware. [Here](https://micropython.org/download/esp32/) and [here](https://docs.micropython.org/en/latest/esp32/tutorial/intro.html#deploying-the-firmware) \nyou find the official instructions to do so.\n\nNow, proceed as follows:\n\n- Download this repository\n```bash\n  git clone https://github.com/albertogeniola/Micropython-WoL\n```\n\n- Install python virtual env and dependencies\n```bash\n  cd Micropython-WoL\n  python -m pip install virtualenv\n  python -m venv .venv\n  .\\.venv\\Scripts\\activate # Or \"source .venv/bin/activate\" if running on linux\n  python -m pip install -r requirements.txt\n```\n\nAfter that, we need to install the cross-compilation library (mpy-cross).\nRetrieve the specific version of your micropython installed version (in this example was `1.22.1`) and install the corresponding mpy-cross package, as follows:\n\n```bash\npython -m pip install mpy-cross==1.22.1\n```\n\nRemember: if you using a different version of micropython, change the `1.22.1` parameter accordingly.\n\nAt this point, we can now perform the program upload. To do so, disconnect your ESP32 device and run the following command. \n\nReplace `_COM_PORT_NAME_OR_TTY_` with the serial port path/name of your ESP32 device. On Windows, they are usually `COMX` (where X is an integer); on Linux it is in the form of `/dev/ttyUSB0`\n\n```bash\npython upload_mpy.py _COM_PORT_NAME_OR_TTY_\n```\n\nThen, plug the ESP32 device via USB within 30 seconds: the flashing process will start. \n\n```\n...\nPre-compiling ...\nPre-compiling ...\nPre-compiling ...\nUploading boot.py, main.py and hw.json\nWaiting 30 seconds for pyboard ....\n```\n\nWhen you are done, the onboard device led should start blinking slowly: that means the device entered the \"installation mode\". If that's the case, you can proceed with the next section. If the led does not blink, it probably means some error occurred during the upload or flash process. You should start over and make sure to follow every step again.\n\n## Configuration instructions\nAt this stage, the microptyhon-wol is ready to be configured! \n\nThe first step is to use your laptop or smartphone to connect to the Access Point named \"ESP_WOL\" that the ESP32 sets up when it is in installation mode. Connect to that WIFI using the the following password: `espwol123`.\n\nOnce connected to the WiFi, open a browser and navigate to `http://192.168.4.1`. \nFrom that page, you will configure:\n- The admin's password to log in to the ESP32 tool\n- Your local WiFi SSID where the ESP32 should connect to\n- Advanced network setup (static ip address for the ESP32)\n\n*Note: you probably want to assign the ESP32 a static IP address.\nYou can do that via this web-ui or by configuring a DHCP static lease \n(or MAC-binding) at router/gateway/cpe level.* \n\nOnce the form is submitted, the ESP32-WoL will reboot itself and attempt to connect\nto the provided WiFi network, using the SSID and Password you provided via the form.\nDuring this process, the onboard led will blink quickly. \n\nIf the configuration fails, the device will reboot and put itself into installation mode\nagain. You will recognize that as the onboard led will start blinking slowly as it did \nbefore. If that happens, you should connect again to ESP_WOL wifi and start over the \nconfiguration.\n\nOn the contrary, if the ESP32 correctly connects to the target WiFi,\nthe onboard led will turn to FIXED-ON. When this happens, the web-ui should automatically redirect you to the ESP32-WoL web-administration page. If that does not happen, you can reach it by typing `http://\u003ctarget_ip\u003e` where `target_ip` is the IP address that the ESP32 device has been assigned via DHCP or has bound statically.\nThe ESP32_WOL will advertise its IP via bluetooth le. You can use the `BLE Scanner` android app to get this info: you jus need to launch the APP and scan for BLE device. You'll see an entry named `ESP32-WoL \u003cIP_ADDRESS\u003e`.\n\n### Allow internet access to ESP32-WoL\nIn order to be functional to its original objective, the ESP32-WoL should be accessible\nfrom internet. This means that you should:\n- Make sure the ESP32 always gets the same IP on the LAN\n- Enable port-forwarding from WAN IP to ESP32 internal IP, on TCP port 80 \n- Optionally configure dynamic dns on your router device in case you have a dynamic external IP address from the ISP\n\nSpecific instructions on how to achieve such configuration objectives are out of the scope of this document, as every cpe/router device might differ. The internet is full of tutorials on how to do so, though. Just google for your router model and \"how to port forward\" o \"how to static DHCP lease\" and you should find some nice tutorial to help you out.\n\n### Add WoL devices\nIf you made up to this stage, congratulations: you are done. \nIt is now time to register the LAN devices you would like to wake up via the ESP32-WoL, so that you don't need to remember their MAC address by memory.\n\nTo do so, simply access the Web-UI of the ESP32-WoL at `http://mywol` o `http://\u003cIP_OF_ESP32_WOL\u003e`, log in with the admin password and add a new device. For a new device to be valid you must specify its mac address and a name. You could optionally set also its IP (in case it is static): if you do so, the ESP32-WoL will be able to check whether the target device is already ON or OFF.\n\n*Note: if you don't specify the IP address of the target device, its \"ON\" or \"OFF\" status will be unreliable, but WoL packets will be delivered in any case, when you send them.*\n\n\n## Advanced Topics\n### API interactions\nIt is possible to interact with ESP32-WOL via REST APIs. You can find the API Open Specs in the `docs/swagger.yaml` file within this repository.\nYou can also test it directly via the nice swagger UI [from here](https://albertogeniola.github.io/ESP32-WoL/swagger).\n\n\n### 3D printable case\nThis repository contains a STL model for 3D printing. \nThe model is designed for the `JZK ESP-WROOM-32 ESP-32` ([available here on Amazon](https://p-nt-www-amazon-it-kalias.amazon.it/gp/product/B071JR9WS9/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8\u0026psc=1)).\n\nThe 3D printable model is designed to hold an oled display ssd1306 and has enough space for holding a small piezo-buzzer inside the case. \n\n\u003ca href=\"docs/images/case-3d/front_green.jpg\"\u003e\u003cimg src=\"docs/images/case-3d/front_green.jpg\" height=300\u003e\u003c/a\u003e\n\u003ca href=\"docs/images/case-3d/composition.png\"\u003e\u003cimg src=\"docs/images/case-3d/composition.png\" height=300\u003e\u003c/a\u003e\n\u003ca href=\"docs/images/case-3d/colored.png\"\u003e\u003cimg src=\"docs/images/case-3d/colored.png\" height=300\u003e\u003c/a\u003e\n\nYou can find the 3D printable files on [ThingVerse](https://www.thingiverse.com/thing:6511323).\n\n\n### Hardware Setup\nAt the moment, Micropython-wol supports two hardware devices:\n- A SSD1306 oled display, connected via I2C\n- A passive piezobuzzer\n\nYou need to configure the firmware to correctly handle the communication with the hardware.\nDepending on the device being used and on its specific pinout, you need to specify the connection parameters into a file called `hw.json`, to be placed into the root of the controller, composed as follows.\n\n```json\n{\n    \"display\": {\n        \"type\": \"ssd1306\",\n        \"config\": {\n            \"sda_pin\": 21,\n            \"scl_pin\": 22\n            }\n    },\n    \"buzzer\": {\n        \"type\": \"piezo_passive\",\n        \"config\": {\n            \"pin\": 23\n        }\n    }\n}\n```\n\nChange the pin numbers according to your specific device. For instance, the example above tells how to connect the ssd1306 display to a [ESP32-WROOM-32](docs/images/image.png) using its standard I2C pins: SDA on pin GPIO21 and SCL on pin GPIO22; the buzzer is instead connected to GPIO23. \n\nWhen choosing the pins, please make sure to refer to GPIO numbering and make sure the pins you are using are compatibile with the signals. As an example, you should avoit using pins destinated to RST commands or connected to on-board leds.\n\nOnce created the hw.json file, you can upload it to the board by using the following command:\n\n```bash\nampy --port __SERIAL_PORT__ --baud 115200 put hw.json\n```\n\nPlease update __SERIAL_PORT__ with the serial port identifier to which the device is connected.\nOnce uploaded, reset the device (just disconnect and reconnect the power cable) and you should be good to go!\n\n### Configure wifi via config.json\nThere are cases in which it is advisable to pre-configure the device so that you don't need to interact with the web-interface to set it up. In such cases, you can prepare the `config.json` file and upload it directly on the device, specifying your desired configuration.\n\nHere's an example:\n```json\n{\n  \"config\": {\n    \"users\": {\n      \"admin\": \"ADMIN_PASSWORD_IN_CLEAR_TEXT\"\n    },\n    \"network\": {\n      \"ssid\": \"SSID_NAME\",\n      \"password\": \"SSID_PASSWORD\",\n      \"static_ip\": null,\n      \"netmask\": null,\n      \"gateway\": null,      \n      \"dns\": null\n    }\n  },\n  \"error\": null\n}\n```\n\nUpdate the following values:\n-  __ADMIN_PASSWORD_IN_CLEAR_TEXT__ : Password to access the WebUI of the Micropython-WOL\n-  __SSID_NAME__ : Name of the Network's SSID to which the device should connect\n-  __SSID_PASSWORD__ : Network's SSID password\n\nIf you wish to assign a static IP to the device, populate the following:\n- static_ip: ip to assign, e.g. 192.168.1.100\n- netmask: network netmask, e.g. 255.255.255.0\n- gateway: network's default gateway, e.g. 192.168.1.1\n- dns: network's dns, e.g. 192.168.1.1\n\nOnce ready, upload the file to the device, using the following command:\n\n```bash\nampy --port __SERIAL_PORT__ --baud 115200 put config.json\n```\n\nOnce uploaded, reset the device (just disconnect and reconnect the power cable) and you should be good to go!\n\n## Some Screenshots\n\u003ca href=\"docs/images/login.png\"\u003e\u003cimg src=\"docs/images/login.png\" width=300\u003e\u003c/a\u003e\n\u003ca href=\"docs/images/main.png\"\u003e\u003cimg src=\"docs/images/main.png\" width=300\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertogeniola%2Fmicropython-wol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbertogeniola%2Fmicropython-wol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertogeniola%2Fmicropython-wol/lists"}