WakeLink Protocol v1.0

Secure Remote Device Management • ChaCha20 • Cloud & Local Modes

Author: deadboizxc
Version: 1.0 • Release: November 2025
License: NGC License - Free for personal use

License Note: NGC License v1.0 — non-commercial use permitted. commercial use requires prior written permission from the copyright holder; redistribution of modified versions must clearly indicate the original author and retain the license notice. see LICENSE_REQUEST_TEMPLATE.md for a template to request permission.

---

Language / Мова / Язык

English	Українська
README_EN.md	README_UA.md

---

🚀 What's New in v1.0

• Smart CLI Client - Intuitive command-line interface
• Enhanced Encryption - ChaCha20 + SHA256 security
• Unified Protocol - Single protocol for all modes
• Device Management - Saved configurations
• Extended Commands - OTA, restart, web control, crypto info

wss support

• cloud relay supports secure websocket (wss) connections from devices for nat traversal. server is a transparent pipe and does not inspect encrypted payloads. use /api/push and /api/pull or websocket endpoints under /api/ws/*.

curl examples:

curl -X POST "${base_url}/api/device/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_TOKEN_HERE" \
  -d '{"device_id":"device_id","device_token":"device_token"}'

curl -X POST "${base_url}/api/push" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_TOKEN_HERE" \
  -d '{"device_id":"device_id","device_token":"device_token","payload":"your_encrypted_data_here","signature":"signature","version":"1.0"}'

---

Features

Feature	Description
ChaCha20 + SHA256	End-to-end encryption with hashing
Cloud + Local TCP	Dual-mode operation
Web UI	http://192.168.4.1 for setup
OTA Updates	Wireless firmware updates
Token Auth	Secure device & API tokens
Docker Server	Cloud relay in container
Smart CLI	Intuitive command interface
Zero Storage	No logs, no sensitive data stored

---

Quick Start

1. Upload Firmware

# Open WakeLink.ino in Arduino IDE
# Select ESP8266/ESP32 board
# Upload to device

2. Initial Setup

# Connect to WakeLink-Setup (password: configure123)
# Open http://192.168.4.1 in browser
# Configure WiFi and get device token

3. Use Smart CLI Client

the CLI follows the syntax used in client/wakelink.py. examples:

cd client

# make executable and add to PATH
chmod +x wl
sudo ln -s $(pwd)/wl /usr/local/bin/wl

# add a local tcp device (positional form)
wl add pico token your_token ip 192.168.1.50

# register a cloud device (positional form)
wl register pico device-id WL123 api-token sk-xxx

# list configured devices
wl list

# remove a device
wl remove pico

# device commands (positional device name)
wl pico ping
wl pico info
wl pico wake 00:11:22:33:44:55
wl pico restart

# alternate flag forms are also supported
wl --add-device myesp --ip 192.168.1.100 --token YOUR_DEVICE_TOKEN
wl --register-device mycloud --device-id WL123 --api-token API_TOKEN

---

Project Structure

WakeLink/
├── client/              # Python CLI Client
│   ├── wl              # Main executable
│   ├── config/         # Device management
│   ├── protocol/       # Commands & packets
│   ├── handlers/       # TCP & Cloud clients
│   └── core/           # Crypto & base commands
├── firmware/           # ESP8266/ESP32 Firmware
│   └── WakeLink/       # Main firmware
│       ├── WakeLink.ino
│       ├── config.h/cpp
│       ├── CryptoManager.h/cpp
│       ├── command.h/cpp
│       ├── tcp_handler.h/cpp
│       ├── cloud_client.h/cpp
│       └── ... (23 files)
└── server/             # Cloud Relay (FastAPI)
    ├── main.py
    ├── core/           # Database, auth, models
    ├── routes/         # API endpoints
    └── templates/      # Web UI

---

Cloud Server (Docker)

# docker-compose.yml
services:
  wakelink-server:
    build: ./server
    ports: ["9009:9009"]
    restart: unless-stopped
    volumes:
      - ./data:/app/data

docker-compose up -d

Manual Installation

cd server
pip install -r requirements.txt
python main.py

---

Smart CLI Usage

Device Management

wl --add-device myesp --ip 192.168.1.100 --token DEVICE_TOKEN
wl --add-device mycloud --token DEVICE_TOKEN --api-token API_TOKEN --cloud
wl list

Device Commands

wl d myesp info                    # Device information
wl device myesp ping               # Connectivity check
wl -d myesp wake AA:BB:CC:DD:EE:FF # Wake-on-LAN
wl d myesp restart                 # Restart device
wl device myesp ota                # OTA update
wl d myesp crypto                  # Crypto information

Web Server Control

wl d myesp site-on                 # Enable web server
wl d myesp site-off                # Disable web server  
wl d myesp site-status             # Web server status

---

Protocol v1.0

Secure Packet Format

[2 bytes: data length] + [ChaCha20 ciphertext] + [16 bytes: nonce]

Encrypted JSON Command

{
  "command": "wake",
  "data": {"mac": "AA:BB:CC:DD:EE:FF"},
  "device_id": "esp01", 
  "timestamp": 1630000000000
}

Communication Modes

• Local TCP: Port 99, encrypted JSON over TCP
• Cloud HTTP: /api/push & /api/pull endpoints
• Authentication: Device token + API token (cloud)

---

Available Commands

Command	Parameters	Description
ping	-	Connectivity check
info	-	Device information
wake	mac	Send Wake-on-LAN
restart	-	Restart device
ota_start	-	Start OTA update
open_setup	-	Open configuration AP
web_control	action	Web server management
crypto_info	-	Crypto system info
counter_info	-	Request statistics
reset_counter	-	Reset request counter

---

Security Features

• ChaCha20 Encryption - Stream cipher for all commands
• SHA256 Hashing - Token and key derivation
• Unique Nonce - Each packet gets fresh nonce
• Request Limiting - Protection against brute force
• Token Authentication - Two-tier token system
• No Sensitive Storage - Keys not persisted

---

Port Configuration

Service	Port	Protocol	Purpose
TCP Server	99	TCP	Local encrypted commands
Web Server	80	HTTP	Configuration interface
UDP WOL	9	UDP	Wake-on-LAN packets
Cloud API	9009	HTTP	Cloud relay server

---

Troubleshooting

Common Issues:

1. "Device not found" - Check device_token match
2. "Connection refused" - Verify TCP server on port 99
3. "Decrypt failed" - Ensure token consistency
4. WOL not working - Check MAC format and network

Diagnostics:

# Check device status
wl d myesp info

# Monitor serial output
# Arduino IDE: Tools → Serial Monitor (115200 baud)

# Test cloud connectivity  
curl http://localhost:9009/api/health

---

Admin & Monitoring

Web Dashboard

http://your-server:9009/dashboard

API Health Check

curl http://localhost:9009/api/health
curl http://localhost:9009/api/stats

---

WakeLink v1.0 - Secure Remote Device Management
Wake your devices. Securely. From anywhere.