wol-dashboard/README.md

⚡ Wake-on-LAN Dashboard

A modern, self-hosted web dashboard to remotely power on PCs via Magic Packet. Built with Python (Flask) and a responsive HTML/CSS/JS frontend — works on desktop and mobile.

---

📋 Features

• ⚡ Wake up PCs remotely via Magic Packet (Wake-on-LAN)
• 🟢 Real-time Online/Offline status via Ping
• 🔍 Automatic network scan to discover devices (nmap)
• ➕ Manually add devices (Name, MAC, IP)
• 🗑 Remove devices from the list
• 📱 Fully responsive — works on mobile and desktop
• 🔄 Auto-refresh status every 30 seconds

---

🗂 Project Structure

wol-dashboard/ ├── app.py # Flask backend for Windows ├── app_linux.py # Flask backend for Linux ├── devices.json # Device database (auto-created on first save) ├── README.md └── templates/ └── index.html # Web frontend (shared for both platforms)

---

🖥️ Installation — Windows

Step 1 — Install Python

Open PowerShell or CMD as Administrator and run:

winget install -e --id Python.Python.3.13

Close and reopen CMD after installation. Verify:

python --version
pip --version

Tip: If python opens the Microsoft Store instead, go to: Settings → Apps → Advanced App Settings → App Execution Aliases and disable python.exe and python3.exe.

---

Step 2 — Install nmap

winget install -e --id Insecure.Nmap

Close and reopen CMD. Verify:

nmap --version

---

Step 3 — Set up the project

cd C:\Users\<YourName>\Desktop\wol-dashboard

python -m venv venv
venv\Scripts\activate

pip install flask wakeonlan

---

Step 4 — Create project files

Make sure your folder contains these files: wol-dashboard/ ├── app.py ├── devices.json ← optional, auto-created └── templates/ └── index.html

Create the templates folder if it doesn't exist:

mkdir templates

---

Step 5 — Start the server

venv\Scripts\activate
python app.py

You should see: Running on http://0.0.0.0:5000

Open in your browser: http://localhost:5000

---

Optional — Allow port 5000 through Windows Firewall

netsh advfirewall firewall add rule name="Flask WOL" dir=in action=allow protocol=TCP localport=5000

---

🐧 Installation — Linux (Debian / Ubuntu)

Step 1 — Install system dependencies

sudo apt update
sudo apt install python3 python3-venv python3-full nmap -y

Verify:

python3 --version
nmap --version

---

Step 2 — Set up the project

cd ~/DEV/wol-dashboard

python3 -m venv venv
source venv/bin/activate

pip install flask wakeonlan

---

Step 3 — Grant nmap network permissions (once)

nmap needs elevated privileges for ARP scans. Instead of running as root, grant capabilities once:

sudo setcap cap_net_raw,cap_net_admin+eip $(which nmap)

---

Step 4 — Create project files

mkdir -p templates
# Place app_linux.py and templates/index.html in the folder

---

Step 5 — Start the server

source venv/bin/activate
python app_linux.py

You should see: Running on http://0.0.0.0:5000

Open in your browser: http://localhost:5000

---

Optional — Auto-start on boot with systemd

Create a service file:

sudo nano /etc/systemd/system/wol-dashboard.service

Paste the following (adjust paths):

[Unit]
Description=Wake-on-LAN Dashboard
After=network.target

[Service]
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME/DEV/wol-dashboard
ExecStart=/home/YOUR_USERNAME/DEV/wol-dashboard/venv/bin/python app_linux.py
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable wol-dashboard
sudo systemctl start wol-dashboard
sudo systemctl status wol-dashboard

---

📱 Accessing from Phone or Other Devices

1. Find your server IP:

   • Windows: Open CMD → ipconfig → look for IPv4 Address
   • Linux: Run hostname -I

2. Open on any device in the same network: http://192.168.x.x:5000

---

⚙️ Wake-on-LAN Setup on Target PCs

For a PC to be woken up, it must be configured correctly.

BIOS / UEFI

• Enter BIOS on boot (usually DEL, F2, or F12)
• Find and enable: Wake-on-LAN, Power On By PCI-E, or Resume By LAN

Windows Target PC

1. Open Device Manager
2. Expand Network Adapters → right-click your adapter → Properties
3. Tab Power Management:

• ✅ Allow this device to wake the computer

4. Tab Advanced:

• Set Wake on Magic Packet → Enabled

Linux Target PC

sudo apt install ethtool

# Check current WoL status
sudo ethtool eth0 | grep Wake

# Enable WoL (replace eth0 with your adapter name)
sudo ethtool -s eth0 wol g

To make it permanent, add to /etc/rc.local or create a systemd service.

Find your adapter name with:

ip link show

---

🗄 devices.json

Devices are stored in devices.json in the project root. It is created automatically when you save the first device via the UI.

You can also edit it manually:

[
{
 "name": "Gaming-PC",
 "mac": "AA:BB:CC:DD:EE:FF",
 "ip": "192.168.1.100"
},
{
 "name": "Work Laptop",
 "mac": "11:22:33:44:55:66",
 "ip": "192.168.1.105"
}
]

Field	Required	Description
name	✅	Display name shown on the dashboard card
mac	✅	MAC address — colons or dashes both accepted
ip	❌	IP address — required for online status ping

---

🔄 Daily Usage

Windows

cd C:\Users\<YourName>\Desktop\wol-dashboard
venv\Scripts\activate
python app.py

Linux

cd ~/DEV/wol-dashboard
source venv/bin/activate
python app_linux.py

Or create a startup script start.sh:

#!/bin/bash
cd ~/DEV/wol-dashboard
source venv/bin/activate
python app_linux.py

chmod +x start.sh
./start.sh

---

🔍 Platform Differences

Feature	app.py (Windows)	app_linux.py (Linux)
Ping command	ping -n 1 -w 500	ping -c 1 -W 1
ARP command	arp -a	arp -n
MAC format in ARP	AA-BB-CC-DD-EE-FF	aa:bb:cc:dd:ee:ff
nmap line endings	\r\n	\n
Elevated rights	Run CMD as Admin	setcap once
Auto-start	Task Scheduler	systemd service
index.html	✅ Shared	✅ Shared

---

📦 Dependencies

Package	Install via	Purpose
flask	pip	Web framework
wakeonlan	pip	Send Magic Packets
nmap	System	Network device scanning

Install Python packages:

pip install flask wakeonlan

---

🔒 Security Notice

This dashboard is designed for trusted local networks only. It has no authentication built in. Do not expose port 5000 to the internet without:

• A reverse proxy (e.g. nginx) with HTTPS
• HTTP Basic Auth or a login system
• A VPN (e.g. WireGuard, Tailscale)

---

🛠 Troubleshooting

Problem	Solution
python opens Microsoft Store	Disable App Execution Aliases in Windows Settings
nmap not found	Install nmap and restart terminal
venv\Scripts\activate fails	Run python -m venv venv first
PC does not wake up	Enable WoL in BIOS and network adapter settings
Status always shows Offline	Make sure IP is correct and target allows ping (check firewall)
Port 5000 blocked on Windows	Add firewall rule: netsh advfirewall firewall add rule name="Flask WOL" dir=in action=allow protocol=TCP localport=5000
Scan finds no devices	Run setcap on Linux or start CMD as Admin on Windows
Page not loading	Check Flask is running and no error in terminal
externally-managed-environment	Use a virtual environment: python3 -m venv venv

---

📄 License

MIT License — free to use, modify and distribute.