High-Level Architecture Design Specification¶
This document defines the high-level system architecture for the ESP32 Template, including component interactions, layering, and integration patterns.
Overview¶
Description: The system implements a four-layer architecture for clear separation of concerns. Architecture Layers: ┌─────────────────────────────────────────────────────────────┐
│ User Application Layer │
│ (main.c - User customizable) │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ Example Component Library │
├───────────────┬──────────────┬──────────────┬───────────────┤
│ config_manager│ web_server │ cert_handler │ netif_tunnel │
│ - NVS mgmt │ - HTTP API │ - SSL certs │ - QEMU net │
│ - Validation │ - WiFi mgr │ - Auto-gen │ - UART tun │
│ - Runtime │ - Captive │ - Embedding │ - Bridge │
└───────────────┴──────────────┴──────────────┴───────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ ESP-IDF Hardware Abstraction Layer │
│ NVS | HTTP | WiFi | GPIO | FreeRTOS | Netif | TCP/IP │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ ESP32 Hardware / QEMU Emulator │
└─────────────────────────────────────────────────────────────┘
Layer Responsibilities:
Design Rationale: Layered architecture enables:
|
Component Design Specifications¶
Description: Example component demonstrating NVS-based configuration patterns. Purpose: Provide reference implementation for persistent configuration management. Key Design Decisions:
Location: API Pattern: Getter/setter functions with validation See Also: JSON-Based Configuration Manager Design for detailed design |
Description: Example HTTP server with WiFi management and captive portal. Purpose: Provide reference implementation for web-based device configuration. Key Design Decisions:
Location: API Pattern: Initialization function, REST endpoints for configuration Status: ✅ HTTP working, 🚧 HTTPS in progress See Also: Web server requirements in Web Server Requirements |
Description: Automated SSL certificate management for HTTPS (work in progress). Purpose: Enable HTTPS for web server without manual certificate management. Key Design Decisions:
Location: Status: 🚧 Implementation in progress, HTTPS not working in QEMU yet Known Limitation: HTTPS support in QEMU requires additional testing |
Description: QEMU-specific network bridge enabling full TCP/IP stack in emulation. Purpose: Enable hardware-free development with real network connectivity. Key Design Decisions:
Architecture: ESP32 lwIP Stack → UART1 → Python Bridge → Host TUN Device
Location: Performance: ~10 KB/s throughput (limited by 115200 baud UART) See Also: QEMU Network Internals for implementation details |
Data Flow Architecture¶
Description: Components communicate through well-defined APIs and FreeRTOS primitives. Communication Patterns: User Application
↕ (Function calls)
Component APIs
↕ (FreeRTOS primitives)
ESP-IDF HAL
↕ (Hardware registers)
Hardware
Synchronization Mechanisms:
Design Principle: Components expose clean APIs; internal synchronization is hidden from users |
Description: Configuration flows through the system with caching and validation. Flow Stages: Boot: NVS → config_load() → Runtime Cache → Application
Runtime: Application → config_get() → Runtime Cache (fast)
Update: Web UI → Validation → config_save() → NVS → Cache
Factory: Factory Reset → Defaults → NVS → Cache
Performance Optimization: Runtime cache enables sub-microsecond config access Data Integrity: All updates validated before NVS write |
Description: WiFi management with automatic reconnection and AP fallback, including recovery strategy after network loss. WiFi Operation Modes:
Connection Flow: Boot → Load NVS Credentials → STA Connection Attempt
↓ (success)
STA Connected
↓ (failure after timeout)
AP Mode + Captive Portal
(retries STA every 5 min)
↓ (5 min timeout reached)
Reset & Boot
AP Mode Failsafe Recovery:
Credential Management:
Status: ✅ Complete with NVS integration |
Description: HTTP server provides web interface and REST API. Server Features:
URL Structure: / → index.html (main page)
/settings → settings.html (configuration)
/wifi-setup → wifi-setup.html (captive portal)
/api/config → REST API (GET/POST)
/api/wifi → WiFi management API
Status: ✅ HTTP working, 🚧 HTTPS in progress |
QEMU Emulation Architecture¶
Description: Template supports QEMU emulation for hardware-free development. Emulation Strategy:
Network Architecture: Browser (Host) → HTTP Proxy → TUN Bridge → QEMU UART1 → ESP32 lwIP
Components:
Benefits:
|
Description: Build system automatically selects appropriate component implementations. Selection Mechanism: # Component CMakeLists.txt pattern
if(CONFIG_TARGET_EMULATOR)
set(COMPONENT_SRCS "component_sim.c")
else()
set(COMPONENT_SRCS "component.c")
endif()
Configuration: Design Benefits:
|
Threading Architecture¶
Description: Application uses FreeRTOS tasks with priority-based scheduling. Task Structure: Core 0: Application Tasks (user-defined)
├── Main Task (Priority 1)
│ └── Initialization and coordination
└── User Tasks (Priority varies)
└── Application-specific logic
Core 1: WiFi/Network Stack (ESP-IDF managed)
├── WiFi Management (Priority 2+)
├── TCP/IP Stack (lwIP)
└── HTTP Server
Design Guidelines:
|
Description: Memory managed with FreeRTOS heap and ESP-IDF capabilities. Allocation Strategy:
Memory Configuration:
Design Principle: Prefer static allocation for predictable memory usage |
Build System Integration¶
Description: Project uses ESP-IDF CMake build system with component registration. Build Structure: # Top-level CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(esp32-template)
# Component CMakeLists.txt
idf_component_register(
SRCS "component.c"
INCLUDE_DIRS "."
REQUIRES esp_http_server nvs_flash
)
Configuration Files:
|
Description: Template configured for 4MB flash with optimized partitions. Flash Layout:
Partition Layout: Name Type Offset Size
nvs data 0x9000 24K (config storage)
phy_init data 0xf000 4K (RF calibration)
factory app 0x10000 ~3.8MB (firmware)
Verification: |
Development Workflow Design¶
Description: Template optimized for zero-setup development in GitHub Codespaces. Development Environment:
Workflow: Fork Template → Open in Codespaces → Customize main.c →
Build → Test in QEMU → Flash to Hardware
Benefits: Consistent environment, no local setup, works in browser |
Logging and Diagnostics¶
Description: Consistent logging strategy using ESP-IDF logging framework for diagnostics and debugging. Log Levels:
Logging Guidelines:
Build Configuration:
Performance Consideration: Logging is synchronous and blocks the calling task. Avoid logging in time-critical paths (ISRs, high-frequency tasks). Example Usage: static const char* TAG = "wifi_manager";
ESP_LOGI(TAG, "Initializing WiFi manager");
esp_err_t ret = esp_wifi_init(&cfg);
if (ret != ESP_OK) {
ESP_LOGE(TAG, "WiFi init failed: %s", esp_err_to_name(ret));
return ret;
}
|
Error Recovery Strategy¶
Description: Reset-first error recovery strategy for IoT device reliability. Recovery Philosophy: System uses reset as primary recovery mechanism for system-level failures, leveraging fast boot time (~3 seconds) and NVS persistence. Error Classification:
Watchdog Protection:
Design Rationale:
Trade-offs:
|
Performance Targets¶
Description: Template targets reasonable performance for IoT applications. Performance Targets:
Monitoring:
|
Traceability¶
All traceability is automatically generated by Sphinx-Needs based on the :links: attributes in each specification.
ID |
Title |
Status |
Tags |
|---|---|---|---|
Certificate Handler |
implemented |
||
Config Manager |
implemented |
||
Network Tunnel |
implemented |
||
cert_handler_get_ca_cert |
implemented |
||
cert_handler_get_info |
implemented |
||
cert_handler_get_server_cert |
implemented |
||
cert_handler_get_server_key |
implemented |
||
cert_handler_init |
implemented |
||
config_commit |
implemented |
||
config_factory_reset |
implemented |
||
config_get_all_as_json |
implemented |
||
config_get_bool |
implemented |
||
config_get_int16 |
implemented |
||
config_get_int32 |
implemented |
||
config_get_schema_json |
implemented |
||
config_get_string |
implemented |
||
config_init |
implemented |
||
config_set_all_from_json |
implemented |
||
config_set_bool |
implemented |
||
config_set_bool_no_commit |
implemented |
||
config_set_int16 |
implemented |
||
config_set_int16_no_commit |
implemented |
||
config_set_int32 |
implemented |
||
config_set_string |
implemented |
||
config_set_string_no_commit |
implemented |
||
config_write_factory_defaults |
implemented |
||
netif_uart_tunnel_deinit |
implemented |
||
netif_uart_tunnel_get_handle |
implemented |
||
netif_uart_tunnel_init |
implemented |
||
netif_uart_tunnel_config_t |
implemented |
||
JSON Schema as Configuration Source of Truth |
draft |
config; schema; architecture |
|
Web Interface Integration Support |
approved |
config; integration |
|
NVS Error Graceful Handling |
draft |
config; error-handling; reliability |
|
Configuration Initialization on Boot |
draft |
config; boot |
|
Simple Process to Add Configuration Fields |
draft |
config; extensibility; developer-experience |
|
Type Safety via Optional Static Validation |
draft |
config; validation; developer-experience |
|
Configuration Schema Versioning and Migration |
open |
config; versioning; migration; future |
|
Parameter Grouping for UI Organization |
draft |
config; ui; schema |
|
Parameter Type System |
draft |
config; types |
|
Build-Time Factory Defaults Generation |
draft |
config; build; code-generation |
|
No Runtime JSON Parsing in C Code |
draft |
config; performance; memory |
|
Key-Based NVS Storage |
draft |
config; storage; nvs |
|
Type-Safe Configuration API |
draft |
config; api; type-safety |
|
Persistent Configuration Storage |
draft |
config; storage; nvs |
|
Factory Reset Capability |
draft |
config; reset |
|
QEMU UART Network Bridge |
approved |
emulation; network; qemu; uart |
|
Packet Encapsulation |
approved |
emulation; protocol |
|
Host-Side Bridge Script |
approved |
emulation; tooling; host |
|
DHCP Client Support |
approved |
emulation; network; dhcp |
|
Conditional Compilation |
approved |
emulation; build |
|
Emulation Setup Documentation |
approved |
emulation; documentation |
|
Tunnel Throughput |
approved |
emulation; performance |
|
Packet Loss Handling |
approved |
emulation; reliability |
|
Component-based Architecture |
approved |
architecture; modularity |
|
Non-volatile Configuration Storage |
approved |
storage; nvs; configuration |
|
ESP32 Hardware Platform |
approved |
hardware; platform |
|
WiFi Connectivity |
approved |
network; wifi |
|
Memory Management |
approved |
performance; memory |
|
Error Handling and Recovery |
approved |
reliability; error-handling |
|
HTTPS Support |
open |
security; https; future |
|
Emulator Support |
approved |
emulator; qemu; testing |
|
Emulator Network Connectivity |
approved |
emulator; qemu; network; development |
|
System Time and NTP Support |
open |
time; ntp; future |
|
Web-based Configuration |
approved |
web; configuration |
|
Real-time Status Display |
approved |
web; ui; monitoring |
|
Configuration Interface |
approved |
web; ui; configuration |
|
WiFi Setup Interface |
approved |
web; wifi; network |
|
Web Interface Navigation |
approved |
web; ui; navigation |
|
HTTP Server Concurrency |
approved |
web; performance |
|
Configuration REST API |
approved |
web; api; config |
|
Web UI Responsiveness |
approved |
web; performance; ux |
|
Mobile-First Design |
approved |
web; ui; mobile |
|
Schema-Driven Configuration Form |
approved |
web; ui; config |
|
ESP-IDF CMake Integration |
approved |
build; cmake |
|
Certificate Handler Component Design |
draft |
component; security |
|
GitHub Codespaces Integration |
approved |
development; devcontainer |
|
Component Communication Pattern |
approved |
dataflow; communication |
|
Configuration Manager Component Design |
approved |
component; config |
|
Configuration Data Flow |
approved |
dataflow; config |
|
Error Recovery and Reset Strategy |
approved |
error-handling; reliability; reset |
|
Flash Memory Configuration |
approved |
flash; memory |
|
HTTP Server Architecture Details |
approved |
network; http; web |
|
ESP32 Template Layered Architecture |
approved |
architecture; layering |
|
Logging and Diagnostics Strategy |
approved |
logging; diagnostics; debugging |
|
Memory Management Strategy |
approved |
memory; performance |
|
Network Tunnel Component Design |
approved |
component; qemu; network |
|
System Performance Requirements |
approved |
performance; requirements |
|
QEMU Hardware Abstraction |
approved |
qemu; emulation |
|
QEMU Component Selection |
approved |
qemu; build |
|
FreeRTOS Task Organization |
approved |
threading; rtos |
|
Web Server Component Design |
approved |
component; web; network |
|
WiFi Manager Design Details |
approved |
network; wifi |
|
Type-Safe Configuration API |
approved |
api; interface; c-api |
|
JSON Schema-Driven Architecture |
draft |
architecture; config; json-schema |
|
Bulk JSON Configuration API |
approved |
api; json; bulk-operations |
|
Factory Reset via Bulk JSON Update |
approved |
build-process; code-generation; factory-reset |
|
Adding New Configuration Fields |
approved |
development; guide; extensibility |
|
Configuration Schema Structure |
approved |
data-structure; schema |
|
JSON Schema as Single Source of Truth |
approved |
architecture; schema; design-pattern |
|
NVS Storage Format |
approved |
storage; nvs |
|
Type Safety Without Code Generation |
approved |
type-safety; best-practices |
|
JSON Schema for UI Generation |
approved |
web; ui; javascript |
|
Configuration Webpage Architecture |
open |
frontend; javascript; ui |
|
Device Reset Countdown Interface |
open |
ui; countdown; reset |
|
Error Handling and User Feedback |
open |
error-handling; feedback |
|
Configuration Data Flow |
open |
data-flow; json; api |
|
Dynamic Form Generation from Schema |
open |
form-generation; schema; javascript |
|
Complete Page Initialization Flow |
open |
initialization; lifecycle |
|
JSON Array to Form Field Mapping |
open |
data-mapping; json; form |
|
UI State Management |
open |
ui-state; javascript |
|
Web Server Architecture |
approved |
web; architecture |
|
Captive Portal Design |
approved |
web; captive-portal; wifi |
|
HTTP Server Configuration |
approved |
web; config; performance |
|
Extension Guide for Web Pages |
approved |
web; extensibility; guide |
|
Config Manager Integration Pattern |
approved |
web; integration; config |
|
WiFi Manager Integration Pattern |
approved |
web; integration; wifi |
|
Configuration API Endpoints |
approved |
web; api; config; schema |
|
System Health API Endpoint |
approved |
web; api; diagnostics |
|
WiFi Management REST API Endpoints |
approved |
web; api; wifi |
|
URI Routing Table |
approved |
web; routing |
|
CORS Configuration |
approved |
web; security; cors |
|
Static File Embedding Strategy |
approved |
web; build; embedding |
|
Web Server Testing Strategy |
approved |
web; testing |
SPEC_ARCH_LAYERS_1¶