Nexus-Guard-Suite/reference/esp32-agent

ESP32 Agent — Architecture Reference

Status: ARCHITECTURE ONLY (no code) Location: reference/esp32-agent/ (NOT a submodule)

Overview

This directory contains the architecture design and documentation for the ESP32-based WireGuard agent. It is NOT a git submodule — it is an architecture reference for future implementation.

Why reference/ not apps/?

If ESP32 agent is implemented as a submodule in the future, it will be added to apps/device-agent-embedded/. This reference/ directory stores the architecture docs separately to avoid conflicts.

Purpose

• Document the ESP32 agent architecture
• Define the API contract (shared with server-core)
• Hardware reference for LW840X module
• Track implementation status and TODOs

When to Implement

When ready to build the ESP32 agent:

1. Create a new repo: nexus-agent-embedded
2. Add as submodule: apps/device-agent-embedded/
3. Use ESP-IDF v5.2+ toolchain
4. Follow the architecture in docs/DESIGN.md

Files

File	Description
docs/DESIGN.md	Technical design document (full architecture)
docs/HARDWARE.md	ESP32/LW840X hardware reference
docs/API_COMPAT.md	Server API contract (shared protocol)
docs/ARCHITECTURE.md	Module architecture + implementation status

Architecture Summary

┌─────────────────────────────────────────────────────────┐
│                    ESP32 (FreeRTOS)                      │
├─────────────────────────────────────────────────────────┤
│  Application Layer                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ provision│ │ heartbeat│ │  tunnel  │ │  config  │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘  │
│       │             │            │             │         │
│  ┌────┴─────────────┴────────────┴─────────────┴────┐  │
│  │                   crypto.c                       │  │
│  │           AES-256-GCM decrypt (mbedtls)          │  │
│  └──────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────┤
│  Network Stack (lwIP)                                  │
│  ┌──────────────────────────────────────────────────┐  │
│  │              WireGuard (lwIP socket API)         │  │
│  └──────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────┤
│  Hardware Layer                                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │   WiFi   │ │   NVS    │ │   UART   │ │   GPIO   │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└─────────────────────────────────────────────────────────┘

Implementation Status

Module	Status	Notes
tunnel.c	❌ STUB	Needs wireguard-esp32 component integration
heartbeat.c	✅ Real	HTTP loop working, config sync TODO
provision.c	✅ Real	HTTP provisioning working
crypto.c	✅ Real	mbedtls AES-256-GCM
config.c	✅ Real	NVS storage
wifi.c	✅ Real	WiFi STA management

Dependencies

• ESP-IDF: v5.2+
• mbedtls: AES-256-GCM, SHA-256 (built-in)
• lwIP: TCP/IP stack (built-in)
• FreeRTOS: RTOS (built-in)
• wireguard-esp32: WireGuard tunnel library (NOT YET INTEGRATED)

API Contract (Shared with Server)

POST /api/v1/provision   → { token, hwid } → { encrypted_config }
POST /api/v1/heartbeat   → { device_id, tunnel_up, last_handshake } → { config sync }

See docs/API_COMPAT.md for full specification.

Related

• Server Core API
• Device Agent (Go)
• Android Agent

License

Proprietary - NexusGuard