Files

T

datadunia e523398fa8 feat: add ESP32 embedded agent + namespace VRF reference docs + update android-agent submodule

- 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

2026-09-13 14:39:24 +07:00

3.5 KiB

Raw Permalink Blame History

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

# Follow official guide: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/
# ESP-IDF v5.2+ required

2. Configure Server

# 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

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

Create device in server dashboard
Copy registration token
Configure agent with token (menuconfig or NVS)
Agent boots → connects WiFi → provisions → builds tunnel

Heartbeat

Agent sends heartbeat every 30 seconds:

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

License

Proprietary - NexusGuard

3.5 KiB Raw Permalink Blame History