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>
104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
# 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](../../server-core/docs/)
|
|
- [Device Agent (Go)](../../apps/device-agent/)
|
|
- [Android Agent](../../apps/android-agent/)
|
|
|
|
## License
|
|
|
|
Proprietary - NexusGuard
|