datadunia
84689b208e
- reference/esp32-agent/: DESIGN, HARDWARE, API_COMPAT, ARCHITECTURE, README - reference/ios-agent/: DESIGN, API_COMPAT, UI_DESIGN, ARCHITECTURE, README - Both mirror Android agent architecture, UI design, and heartbeat flow - Architecture-only (no code) — avoids submodule conflicts Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
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:
- Create a new repo:
nexus-agent-embedded - Add as submodule:
apps/device-agent-embedded/ - Use ESP-IDF v5.2+ toolchain
- 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
License
Proprietary - NexusGuard