Wake-on-LAN ESP32 + Shutdown + MQTT + OTA + LAN (offline) + Portal (Wi-Fi) v6.1

Important

UPGRADE: This project has been updated and migrated. Follow the latest version here: Wake-On-Lan_ESP32C3_Zephyr

Advanced ESP32 project for sending Wake-on-LAN (WOL) Magic Packets and Shutdown Magic Packets over Wi-Fi and a dedicated wired LAN port (SPI), with full MQTT support, OTA updates, ping-based status checks, and a configuration portal hosted on the device using SPIFFS.

This project supports hardware button-triggered WOL, scheduled ping after WOL, OTA updates with MQTT progress reporting, optional factory reset, and the ability to Shutdown the PC, wake it up, and check its ping after 1 minute, this is possible from anywhere in the world via MQTT.

📋 Features

🌐 Wi-Fi Integration: Connects to your local Wi-Fi network.
🖥️ Wake-on-LAN (WOL): Sends n magic packets to wake compatible PCs (n = 10).
🔌 Redundant WOL (SPI LAN): Sends magic packets over wired LAN port (W5500) (offline mode).
🖥️ Shutdown: Sends n magic packets to Shutdown compatible PCs (n = 10).
🔘 User Button WOL: D0 button sends WOL on >1s press.
🔘 User command PinOut 1: D4 output LOW or HIGH (Default LOW).
🔘 User command PinOut 2: D5 output LOW or HIGH (Default LOW).
☁️ MQTT Support:
- Subscribes to wol/event for "TurnOn", "TurnOff", "CheckUpdate", "FactoryReset", "PingPC", "PinOut1On", "PinOut1Off", "PinOut2On" or "PinOut2Off" commands.
- publishes logs/status to wol/log and wol/status.
🔄 Automatic Ping After WOL or Shutdown: Schedules a ping 1min after sending WOL (non-blocking).
🕵️ Ping-based Status Check: Uses ESP32Ping to verify if the target device is online.
🔆 LED Indicator: D1 LED flashes to indicate WOL, ping, or OTA progress.
💾 OTA Updates: Checks for firmware every 12h; publishes progress to MQTT every 10%.
🛠️ Factory Reset: Holding D2 button LOW at boot deletes config.json.
📄 Configuration Portal: Hosts HTML page on SPIFFS to configure Wi-Fi, MQTT, target IP/MAC, and UDP port.

👉 Important: OTA updates only replace the firmware.

The configuration stored in /config.json (set via the WiFi/MQTT portal) is preserved and not modified by the update.

✅ The code is compatible with:

Microcontroller

ESP32-C3 (e.g., Seeed Studio XIAO ESP32-C3 [Tested], DevKitM-1, Lolin C3 Mini).
ESP32-S3 (DevKit, Seeed Studio XIAO S3, AiThinker modules, etc.).
ESP32 original (ESP32-WROOM-32, ESP32-WROVER, DevKit V1).
ESP32-S2 (DevKit, XIAO ESP32-S2, etc.).
ESP32-PICO-D4 (with 4 MB flash).

Peripheral

W5500 (Ethernet Network Module Hardware SPI to LAN).

🛠️ Requirements

1. Prerequisites

Before starting, ensure you have all the tools and libraries correctly installed:

Arduino IDE
- Version 1.8.18 recommended ( >2.0 Upload ESP32 DATA don't work).
ESP32 Board Manager
- Add URL: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
- Install ESP32 Boards version 3.3.0 or higher.
Libraries
- ArduinoJson v7.4.2
- PubSubClient
- ESP32Ping
Internet Connection
- Required for OTA updates and MQTT.
MQTT Broker
- Example: Mosquitto, HiveMQ.
- Note broker IP, port, username, and password.

2. ESP32 Board & Partition Configuration

Board: XIAO-ESP32C3 (Seeed Studio)
Partition Scheme: Default 4MB (supports OTA)
Upload Speed: 921600 (optional)
Flash Size: 4MB
SPIFFS
- Store config.json and setup.html
- Upload via ESP32 Sketch Data Upload plugin.
- The data folder is used to store files that will be uploaded to the SPIFFS filesystem on the ESP32.
- Install the ESP32 Sketch Data Upload plugin for Arduino IDE if not already installed:
  - Follow instructions: https://randomnerdtutorials.com/install-esp32-filesystem-uploader-arduino-ide/

✅ After these steps, your ESP32 is ready for OTA, SPIFFS, JSON configuration, WOL, and MQTT.

📡 MQTT Topics

Topic	Purpose
`wol/event`	Subscribe to `"TurnOn"`, `"TurnOff"`, `"CheckUpdate"`, `"FactoryReset"`, `"PingPC"`, `"PinOut1On"`, `"PinOut1Off"`, `"PinOut2On"` or `"PinOut2Off"` commands
`wol/status`	Publishes `"MQTT Ready"`, firmware version, and status messages
`wol/log`	Publishes detailed logs (boot, WOL, ping, OTA)

⚡ Operation Modes

1️⃣ Button-triggered WOL

Press Button D0 (>1s) to send WOL magic packet.
LED flashes during WOL.
Schedules a ping 1 minutes later to check if PC is online.
PinOut 1 and PinOut 2 MQTT commands for custom config.

2️⃣ MQTT Commands

LED flashes during Commands.
"TurnOn": Sends WOL.
"TurnOff": Sends Shutdown (need script running in background).
"CheckUpdate": Manually trigger an OTA update check.
"FactoryReset": Manually trigger Factory Reset.
"PingPC": Pings the target and publishes online/offline status.
"PinOut1On": Command for D4 output HIGH.
"PinOut1Off": Command for D4 output LOW.
"PinOut2On": Command for D5 output HIGH.
"PinOut2Off": Command for D5 output LOW.

3️⃣ OTA Updates

Checks every 12h or Press Button D2 (only after boot) for new firmware (version.txt) on GitHub.
Downloads and flashes firmware directly to OTA partition.
Publishes progress via MQTT every 10%.
Reports:
- Download progress
- Flash writing
- Update success or errors
Device restarts automatically after OTA.

4️⃣ Factory Reset

Hold Button D2 LOW at boot to delete config.json.
Device restarts and launches the configuration portal if no config exists.

5️⃣ Configuration Portal

LED stay fixed ON
Hotspot: WOL_ESP32_Config if no config file.
HTML page allows:
- Wi-Fi SSID & password
- MQTT server, port, user, password
- Target IP & Broadcast IP
- MAC address for WOL
- UDP port
Submitting saves config and restarts device.

⚙️ Configuration

Portal via browser (http://192.168.4.1).

Or update by ESP32DATA config.json:

{
  "ssid": "YOUR_WIFI",
  "password": "YOUR_PASSWORD",
  "mqtt_server": "broker.local",
  "mqtt_port": 1883,
  "mqtt_user": "user",
  "mqtt_password": "pass",
  "target_ip": "192.168.1.100",
  "broadcastIP": "192.168.1.255",
  "mac_address": [0xDE,0xAD,0xBE,0xEF,0xFE,0xED],
  "udp_port": 9
}

🛠️ Pinout Summary

Pin	Function
D0	User button (send WOL)
D1	LED indicator
D2	Factory reset / config portal
D4	Output LOW or HIGH (MQTT)
D5	Output LOW or HIGH (MQTT)
D7	CS/SS (W5500)
D8	SCK (W5500)
D9	MISO (W5500)
D10	MOSI (W5500)

Shutdown Listener

A Python program that listens for special UDP packets to remotely shut down the computer.
Supports hidden background execution and can be converted into a Windows executable (.exe).

🚀 Running the program as a Windows Service (pre-login)

To have the executable run in the background even before any user logs in, you can register it as a Windows Service using NSSM (Non-Sucking Service Manager).

Download NSSM from: https://nssm.cc/download
Extract the files to a folder, for example: C:\nssm\nssm.exe
Install the service, open Command Prompt as Administrator and run: C:\nssm\nssm.exe install ShutdownListener
- To remove the service if wrong, open the Command Prompt as Administrator and run: C:\nssm\nssm.exe remove ShutdownListener
In the window that opens, configure:
- Path: full path to your executable, e.g., C:\Path\To\YourProgram.exe
- Startup directory: folder containing the exe
- Arguments: empty
- Service name: ShutdownListener (or another name of your choice)
Click Install service.
Start the service In CMD, run: C:\nssm\nssm.exe start ShutdownListener

✅ Now the program will run automatically in the background, even before login, ready to listen for the magic packet to shut down the PC.

💻 Creating the program executable (.exe)

To run the listener without opening Python, you can generate a Windows executable using PyInstaller.
This allows you to run the program with double-click in hidden background mode.

Install dependencies
Make sure PyInstaller is installed, Open Command Prompt as Administrator and run: pip install pyinstaller getmac
Convert the script to .exe, open PowerShell or Command Prompt and run: C:\PYTHONPATH\3.11.2\Scripts\pyinstaller.exe --onefile --noconsole --icon=C:\Path\To\Icon\icon.ico C:\Path\To\Script\Run_script-shutdown_win.py --onefile → generates a single .exe file
- --noconsole → runs hidden, without opening the black console window
- --icon → sets the executable icon (replace with the path to your .ico)
The executable will be created in the folder: dist\Run_script-shutdown_win.exe
Run the program, double-click the .exe and it will remain continuously listening in the background.

To test without shutting down the PC, run with the --simulate argument: Run_script-shutdown_win.exe --simulate

✅ The listener will continue monitoring UDP packets but will not execute the shutdown command.

💡 Notes

Button debounce: >1s press triggers WOL.
Magic Packet: Broadcast UDP to broadcastIP:udp_port using target MAC.
MQTT Logs: Full OTA, WOL, and ping progress published to wol/log.
SPIFFS HTML: setup.html must be uploaded via Arduino IDE or ESP32FS tool.
Firmware Version: Stored in FIRMWARE_VERSION constant (5.2); OTA compares with version.txt.

🚀 Project Status

🌐 Wake on Lan
📡 MQTT
📴 Shutdown
🔌 LAN W5500 (Offline mode)

✨ Thanks for using this project!

Developed for ESP32-C3 with Seeed Studio XIAO board.
Ideal for automating PC wake-up and monitoring over Wi-Fi.

⚡Image

Pinout Esp32C3

Pinout W5500

Schematic

Wi-Fi AP

Configuration Portal

Configuration Portal - SAVED!

Console HiveMQ Cloud (can be other)

IoT MQTT Panel (can be other)

IoT MQTT Panel - Dash (Customizable - send: wol/event - receive: wol/status and wol/log)

🎬 Video

WOL_ESP32_-_VideoSpeed_2X.mp4

Name		Name	Last commit message	Last commit date
Latest commit History 196 Commits
.vscode		.vscode
Shutdown_Script		Shutdown_Script
Tools		Tools
data		data
firmware		firmware
WOL_ESP32.ino		WOL_ESP32.ino
config.cpp		config.cpp
config.h		config.h
configPortal.cpp		configPortal.cpp
configPortal.h		configPortal.h
helpers.cpp		helpers.cpp
helpers.h		helpers.h
mqtt.cpp		mqtt.cpp
mqtt.h		mqtt.h
ota.cpp		ota.cpp
ota.h		ota.h
readme.md		readme.md
wifi_utils.cpp		wifi_utils.cpp
wifi_utils.h		wifi_utils.h
wol_ping.cpp		wol_ping.cpp
wol_ping.h		wol_ping.h

Folders and files

Latest commit

History

Repository files navigation

Wake-on-LAN ESP32 + Shutdown + MQTT + OTA + LAN (offline) + Portal (Wi-Fi) v6.1

📋 Features

✅ The code is compatible with:

Microcontroller

Peripheral

🛠️ Requirements

1. Prerequisites

2. ESP32 Board & Partition Configuration

📡 MQTT Topics

⚡ Operation Modes

1️⃣ Button-triggered WOL

2️⃣ MQTT Commands

3️⃣ OTA Updates

4️⃣ Factory Reset

5️⃣ Configuration Portal

⚙️ Configuration

🛠️ Pinout Summary

Shutdown Listener

🚀 Running the program as a Windows Service (pre-login)

💻 Creating the program executable (.exe)

💡 Notes

🚀 Project Status

✨ Thanks for using this project!

⚡Image

Pinout Esp32C3

Pinout W5500

Schematic

Wi-Fi AP

Configuration Portal

Configuration Portal - SAVED!

Console HiveMQ Cloud (can be other)

IoT MQTT Panel (can be other)

IoT MQTT Panel - Dash (Customizable - send: wol/event - receive: wol/status and wol/log)

🎬 Video

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages