datadunia
e523398fa8
- apps/device-agent-embedded/: ESP32 WireGuard agent (C, ESP-IDF, mbedTLS) - reference/namespace-vrf/: Linux namespace/VRF network isolation docs - apps/android-agent: VPN permission check, StartResult sealed class
127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# NexusGuard Embedded Agent
|
|
|
|
ESP32-based WireGuard agent for IoT/edge devices. Connects to NexusGuard Server Core via HTTP provisioning + heartbeat, manages WireGuard tunnel via lwIP stack.
|
|
|
|
## Overview
|
|
|
|
This agent runs on ESP32 (LW840X and compatible) with FreeRTOS + ESP-IDF. It provides:
|
|
|
|
- **Zero-Trust VPN Tunnel**: WireGuard over lwIP
|
|
- **Auto-Provisioning**: HTTP-based key exchange with server
|
|
- **Heartbeat Monitoring**: Periodic status reports + config sync
|
|
- **NVS Config Persistence**: WireGuard keys stored in flash (never disk)
|
|
- **Independent Build**: No dependency on main NexusGuard repo
|
|
|
|
## Hardware Requirements
|
|
|
|
| Component | Specification |
|
|
|-----------|---------------|
|
|
| MCU | ESP32 (Xtensa LX7) or ESP32-S3 |
|
|
| RAM | ≥ 320KB SRAM |
|
|
| Flash | ≥ 4MB |
|
|
| WiFi | 802.11 b/g/n |
|
|
| antenna | U.FL or PCB trace |
|
|
|
|
## Quick Start
|
|
|
|
### 1. Install ESP-IDF
|
|
|
|
```bash
|
|
# Follow official guide: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/
|
|
# ESP-IDF v5.2+ required
|
|
```
|
|
|
|
### 2. Configure Server
|
|
|
|
```bash
|
|
# Set server URL, registration token, and WiFi credentials
|
|
idf.py menuconfig
|
|
# Navigate to: Component config → NexusGuard Agent
|
|
```
|
|
|
|
Or edit `sdkconfig.defaults` directly:
|
|
|
|
```
|
|
CONFIG_NEXUS_SERVER_URL="https://api-nexus.datadunia.com"
|
|
CONFIG_NEXUS_REG_TOKEN="your-registration-token"
|
|
CONFIG_NEXUS_SERVER_SALT="your-server-salt"
|
|
CONFIG_NEXUS_WIFI_SSID="your-wifi-ssid"
|
|
CONFIG_NEXUS_WIFI_PASSWORD="your-wifi-password"
|
|
```
|
|
|
|
### 3. Build & Flash
|
|
|
|
```bash
|
|
idf.py set-target esp32
|
|
idf.py build
|
|
idf.py -p /dev/ttyUSB0 flash monitor
|
|
```
|
|
|
|
## Server Configuration
|
|
|
|
The agent requires the following server configuration:
|
|
|
|
| Parameter | Description | Where to Find |
|
|
|-----------|-------------|---------------|
|
|
| Server URL | API endpoint | `https://api-nexus.datadunia.com` |
|
|
| Registration Token | Single-use provisioning token | Server admin dashboard |
|
|
| Server Salt | AES-256-GCM key derivation | Server `.env` file (`SERVER_SALT`) |
|
|
|
|
### Provisioning Flow
|
|
|
|
1. Create device in server dashboard
|
|
2. Copy registration token
|
|
3. Configure agent with token (menuconfig or NVS)
|
|
4. Agent boots → connects WiFi → provisions → builds tunnel
|
|
|
|
### Heartbeat
|
|
|
|
Agent sends heartbeat every 30 seconds:
|
|
|
|
```json
|
|
POST /api/v1/heartbeat
|
|
{
|
|
"device_id": "uuid",
|
|
"status": "connected",
|
|
"tunnel_up": true,
|
|
"last_handshake": "2026-06-26T09:00:00Z"
|
|
}
|
|
```
|
|
|
|
Server responds with config sync (detects changes, triggers rebuild).
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
nexus-agent-embedded/
|
|
├── main/
|
|
│ ├── main.c # Entry point
|
|
│ ├── provision.c # HTTP provisioning
|
|
│ ├── heartbeat.c # HTTP heartbeat loop
|
|
│ ├── tunnel.c # WireGuard via lwIP
|
|
│ ├── crypto.c # AES-256-GCM decrypt
|
|
│ ├── config.c # NVS config storage
|
|
│ └── wifi.c # WiFi management
|
|
├── components/
|
|
│ └── wireguard-esp32/ # WireGuard library
|
|
├── docs/
|
|
│ ├── DESIGN.md # Technical design
|
|
│ ├── API_COMPAT.md # Server API compatibility
|
|
│ └── HARDWARE.md # Hardware reference
|
|
├── CMakeLists.txt
|
|
├── Kconfig # Menuconfig options
|
|
├── sdkconfig.defaults
|
|
├── AGENTS.md # AI agent knowledge base
|
|
└── README.md
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Technical Design](docs/DESIGN.md)
|
|
- [API Compatibility](docs/API_COMPAT.md)
|
|
- [Hardware Reference](docs/HARDWARE.md)
|
|
|
|
## License
|
|
|
|
Proprietary - NexusGuard
|