# ⚡ 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.

![Python](https://img.shields.io/badge/Python-3.10+-blue)
![Flask](https://img.shields.io/badge/Flask-3.0+-lightgrey)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux-green)

---

## 📋 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:

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

Close and reopen CMD after installation. Verify:

```cmd
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

```cmd
winget install -e --id Insecure.Nmap
```

Close and reopen CMD. Verify:

```cmd
nmap --version
```

---

### Step 3 — Set up the project

```cmd
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:

```cmd
mkdir templates
```

---

### Step 5 — Start the server

```cmd
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

```cmd
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

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

Verify:

```bash
python3 --version
nmap --version
```

---

### Step 2 — Set up the project

```bash
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:

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

---

### Step 4 — Create project files

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

---

### Step 5 — Start the server

```bash
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:

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

Paste the following (adjust paths):

```ini
[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:

```bash
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
```bash
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:
```bash
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:

```json
[
{
 "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
```cmd
cd C:\Users\<YourName>\Desktop\wol-dashboard
venv\Scripts\activate
python app.py
```

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

Or create a startup script `start.sh`:

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

```bash
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:

```bash
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.
>>>>>>> edfb358 (Initial commit)