High-Level Architecture Design Specification¶

This document defines the high-level system architecture for the ESP32 Distance Sensor, including component interactions, layering, and integration patterns.

Document Version: 2.0 Last Updated: 2025-11-12

Architecture Overview¶

Design Specification: ESP32 Distance Sensor Layered Architecture SPEC_ARCH_LAYERS_1

status: approved

tags: architecture, layering

links outgoing: REQ_SYS_ARCH_1

links incoming: SPEC_DEV_README_INTRO, SPEC_DEV_GUIDE_DEBUG_FEATURES

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:

User Application Layer: Entry point (main.c), application-specific logic
Component Library: Reusable example components (config, web, networking)
ESP-IDF HAL: Framework-provided hardware abstraction
Hardware: Physical ESP32 or QEMU emulation

Design Rationale: Layered architecture enables:

Independent testing of each layer
Component reuse across projects
Clear upgrade paths when ESP-IDF updates
Hardware/emulator abstraction

Component Design Specifications¶

Design Specification: Configuration Manager Component Design SPEC_ARCH_CONFIG_1

status: approved

tags: component, config

links outgoing: REQ_SYS_CFG_1

Description: Example component demonstrating NVS-based configuration patterns.

Purpose: Provide reference implementation for persistent configuration management.

Key Design Decisions:

NVS Storage: Uses ESP-IDF Non-Volatile Storage API
Runtime Cache: Configuration cached in RAM for fast access
Validation Framework: All parameters validated before persistence
Factory Reset: Recovery mechanism included

Location: main/components/config_manager/

API Pattern: Getter/setter functions with validation

See Also: JSON-Based Configuration Manager Design for detailed design

Design Specification: Web Server Component Design SPEC_ARCH_WEB_1

status: approved

tags: component, web, network

links outgoing: REQ_SYS_WEB_1

Description: Example HTTP server with WiFi management and captive portal.

Purpose: Provide reference implementation for web-based device configuration.

Key Design Decisions:

HTTP Server: ESP-IDF esp_http_server component
Static Files: Embedded in firmware using EMBED_FILES
Captive Portal: DNS server redirects all requests to device
WiFi Manager: Automatic AP/STA mode switching with NVS credentials
Fallback Logic: AP mode if STA connection fails

Location: main/components/web_server/

API Pattern: Initialization function, REST endpoints for configuration

Status: ✅ HTTP working, 🚧 HTTPS in progress

See Also: Web server requirements in Web Server Requirements

Design Specification: Certificate Handler Component Design SPEC_ARCH_CERT_1

status: draft

tags: component, security

links outgoing: REQ_SYS_WEB_1

Description: Automated SSL certificate management for HTTPS (work in progress).

Purpose: Enable HTTPS for web server without manual certificate management.

Key Design Decisions:

Build-Time Generation: Certificates generated during build if missing
Dual Tool Support: OpenSSL binary (preferred) or Python cryptography fallback
Firmware Embedding: Uses ESP-IDF EMBED_FILES feature
Long Validity: 25-year certificate lifetime for device lifecycle

Location: main/components/cert_handler/

Status: 🚧 Implementation in progress, HTTPS not working in QEMU yet

Known Limitation: HTTPS support in QEMU requires additional testing

Design Specification: Network Tunnel Component Design SPEC_ARCH_NETIF_1

status: approved

tags: component, qemu, network

links outgoing: REQ_SYS_SIM_1

Description: QEMU-specific network bridge enabling full TCP/IP stack in emulation.

Purpose: Enable hardware-free development with real network connectivity.

Key Design Decisions:

UART-Based Tunnel: Uses UART1 for frame transport
Ethernet Encapsulation: IP packets wrapped in Ethernet frames
Length-Prefix Protocol: 2-byte big-endian length header per frame
Python Bridge: Host-side TUN device management
Conditional Compilation: Only built for QEMU target

Architecture:

ESP32 lwIP Stack → UART1 → Python Bridge → Host TUN Device

Location: main/components/netif_uart_tunnel/

Performance: ~10 KB/s throughput (limited by 115200 baud UART)

See Also: QEMU Network Internals for implementation details

Data Flow Architecture¶

Design Specification: Component Communication Pattern SPEC_ARCH_COMM_1

status: approved

tags: dataflow, communication

links outgoing: REQ_SYS_ARCH_1

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:

Mutexes: Protect shared configuration state
Queues: Producer-consumer data flow between tasks
Event Groups: Task coordination and signaling
Semaphores: Resource counting and blocking

Design Principle: Components expose clean APIs; internal synchronization is hidden from users

Design Specification: Configuration Data Flow SPEC_ARCH_CONFIG_FLOW_1

status: approved

tags: dataflow, config

links outgoing: REQ_SYS_CFG_1

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

Design Specification: WiFi Manager Design Details SPEC_ARCH_WIFI_1

status: approved

tags: network, wifi

links outgoing: REQ_SYS_NET_1, REQ_SYS_WEB_1

Description: WiFi management with automatic reconnection and AP fallback, including recovery strategy after network loss.

WiFi Operation Modes:

Station (STA) Mode: Connect to existing WiFi network
Access Point (AP) Mode: Create configuration network
Fallback Logic: Auto-switch to AP if STA fails

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:

Purpose: Handle scenarios where network is unavailable after power loss
AP Entry: System enters AP mode with captive portal when STA connection fails
Retry Strategy: Attempts to reconnect to configured network every 5 minutes
Recovery Timeout: After 5 minutes in AP mode without successful STA connection, system performs reset
Rationale: Prevents indefinite AP mode if network hardware has failed or credentials are invalid; ensures system attempts network recovery periodically

Credential Management:

WiFi SSID/password stored in NVS
Factory reset clears credentials
Web interface provides credential update

Status: ✅ Complete with NVS integration

Design Specification: HTTP Server Architecture Details SPEC_ARCH_HTTP_1

status: approved

tags: network, http, web

links outgoing: REQ_SYS_WEB_1

Description: HTTP server provides web interface and REST API.

Server Features:

Static file serving from embedded filesystem
RESTful API endpoints for configuration
Captive portal detection and redirect
CORS headers for development

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¶

Design Specification: QEMU Hardware Abstraction SPEC_ARCH_QEMU_1

status: approved

tags: qemu, emulation

links outgoing: REQ_SYS_SIM_1

links incoming: SPEC_DEV_GUIDE_QEMU_START

Description: Template supports QEMU emulation for hardware-free development.

Emulation Strategy:

Network Stack: Full TCP/IP via UART tunnel (not WiFi simulation)
Component Abstraction: Optional simulator implementations with identical APIs
Build System: CMake automatically selects hardware vs. simulator components
Clean Code: No #ifdef conditionals in application code

Network Architecture:

Browser (Host) → HTTP Proxy → TUN Bridge → QEMU UART1 → ESP32 lwIP

Components:

QEMU Emulator: ESP32 hardware emulation
Network Tunnel: netif_uart_tunnel_sim.c driver
TUN Bridge: tools/serial_tun_bridge.py (Python)
HTTP Proxy: tools/http_proxy.py for browser access

Benefits:

Fast iteration without hardware flashing
CI/CD automation without physical devices
GDB debugging with VS Code integration
Cross-platform development

Design Specification: QEMU Component Selection SPEC_ARCH_QEMU_BUILD_1

status: approved

tags: qemu, build

links outgoing: REQ_SYS_SIM_1

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: idf.py menuconfig → “Build for QEMU emulator”

Design Benefits:

Same header files for both implementations
No code pollution with conditional compilation
Easy to add simulator support to any component

Threading Architecture¶

Design Specification: FreeRTOS Task Organization SPEC_ARCH_TASKS_1

status: approved

tags: threading, rtos

links outgoing: REQ_SYS_ARCH_1

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:

Core 0 for application tasks
Core 1 reserved for WiFi/network (best performance)
Priority range: 0-25 (higher = more important)
Monitor stack with uxTaskGetStackHighWaterMark()

Design Specification: Memory Management Strategy SPEC_ARCH_MEMORY_1

status: approved

tags: memory, performance

links outgoing: REQ_SYS_HW_1

Description: Memory managed with FreeRTOS heap and ESP-IDF capabilities.

Allocation Strategy:

Static: Component structures at compile time (predictable)
Dynamic: Runtime allocations use heap_caps_malloc()
DMA Buffers: Use MALLOC_CAP_DMA capability
IRAM: Use IRAM_ATTR only for time-critical ISRs

Memory Configuration:

4MB flash (CONFIG_ESPTOOLPY_FLASHSIZE_4MB)
~41% free flash after base system
Monitor: esp_get_free_heap_size()

Design Principle: Prefer static allocation for predictable memory usage

Build System Integration¶

Design Specification: ESP-IDF CMake Integration SPEC_ARCH_BUILD_1

status: approved

tags: build, cmake

links outgoing: REQ_SYS_HW_1

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:

sdkconfig: ESP-IDF configuration (flash, partition table)
CMakeLists.txt: Build definitions
main/Kconfig.projbuild: Custom menuconfig options

Design Specification: Flash Memory Configuration SPEC_ARCH_FLASH_1

status: approved

tags: flash, memory

links outgoing: REQ_SYS_HW_1

Description: Template configured for 4MB flash with optimized partitions.

Flash Layout:

Flash Size: 4MB (suitable for most ESP32 modules)
Partition Table: Single App Large (maximizes app space)
Free Space: ~41% available for growth
HTTPS Ready: Sufficient space for SSL certificates

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: idf.py size shows memory usage

Development Workflow Design¶

Design Specification: GitHub Codespaces Integration SPEC_ARCH_CODESPACES_1

status: approved

tags: development, devcontainer

links outgoing: REQ_SYS_SIM_1

links incoming: SPEC_DEV_ENV_OPTIONS, SPEC_DEV_ENV_USAGE

Description: Template optimized for zero-setup development in GitHub Codespaces.

Development Environment:

DevContainer: Ubuntu 24.04 with ESP-IDF v5.4.1 pre-installed
QEMU: Integrated emulator for hardware-free testing
VS Code: Pre-configured extensions (ESP-IDF, C/C++, Python)
Pre-commit Hooks: Quality gates for documentation

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¶

Design Specification: Logging and Diagnostics Strategy SPEC_ARCH_LOGGING_1

status: approved

tags: logging, diagnostics, debugging

links outgoing: REQ_SYS_REL_1

Description: Consistent logging strategy using ESP-IDF logging framework for diagnostics and debugging.

Log Levels:

ESP_LOGI: Normal operational events (initialization, state transitions)
ESP_LOGW: Recoverable issues (degraded mode, fallback actions)
ESP_LOGE: Error conditions requiring attention (failed operations)
ESP_LOGD: Debug information (disabled in production builds)

Logging Guidelines:

Component TAGs: Each file defines static const char* TAG with component name
Error Context: Always include esp_err_to_name() for ESP-IDF error codes
Initialization: Log start and completion of major initialization steps
State Changes: Log WiFi mode changes, connection events, system transitions
User Actions: Log web API requests and configuration changes

Build Configuration:

Production: INFO level (boot sequence, errors, warnings)
Development: DEBUG level (detailed operational data)
Configure via menuconfig: Component config → Log output → Default log verbosity

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¶

Design Specification: Error Recovery and Reset Strategy SPEC_ARCH_ERROR_RECOVERY_1

status: approved

tags: error-handling, reliability, reset

links outgoing: REQ_SYS_REL_1

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:

Protocol-Level Errors → Handle gracefully
- TCP packet loss: Let lwIP retry
- HTTP timeouts: Return error to client
- Transient WiFi drops: Reconnection logic handles
- Configuration validation failures: Reject and log
System-Level Errors → Reset device
- WiFi total failure after retries
- NVS corruption detection
- Critical component initialization failure
- Unrecoverable state machine deadlock

Watchdog Protection:

Task watchdog enabled (CONFIG_ESP_TASK_WDT)
Prevents infinite loops and deadlocks
Automatic reset on watchdog timeout

Design Rationale:

✅ Simpler code with fewer state machines
✅ Fast boot time makes reset acceptable
✅ NVS survives reset (configuration preserved)
✅ Reduced attack surface (less recovery code = fewer bugs)
✅ Deterministic recovery path

Trade-offs:

May lose transient runtime state (acceptable for stateless IoT device)
Debugging requires log analysis (logging captures failure context)

Performance Targets¶

Design Specification: System Performance Requirements SPEC_ARCH_PERF_1

status: approved

tags: performance, requirements

links outgoing: REQ_SYS_PERF_1

Description: Template targets reasonable performance for IoT applications.

Performance Targets:

Boot Time: < 3 seconds to WiFi connection
Web Response: < 500ms for configuration API calls
Memory Usage: < 100KB application heap usage
Task Latency: < 100ms for application tasks

Monitoring:

Use ESP_LOGI() for timing measurements
Monitor heap with esp_get_free_heap_size()
Check stack usage with uxTaskGetStackHighWaterMark()
Profile with ESP-IDF performance tools

Traceability¶

All traceability is automatically generated by Sphinx-Needs based on the :links: attributes in each specification.

ID	Title	Status	Tags
API_COMP_CERT_HANDLER	Certificate Handler	implemented
API_COMP_CONFIG_MANAGER	Config Manager	implemented
API_COMP_DISPLAY_LOGIC	Display Logic	implemented
API_COMP_DISTANCE_SENSOR	Distance Sensor	implemented
API_COMP_LED_CONTROLLER	LED Controller	implemented
API_COMP_NETIF_TUNNEL	Network Tunnel	implemented
API_COMP_STARTUP_TESTS	Startup Tests	implemented
API_COMP_WEB_SERVER	Web Server	implemented
API_COMP_WIFI_MGR	WiFi Manager	implemented
API_FUNC_CERT_HANDLER_GET_CA_CERT	cert_handler_get_ca_cert	implemented
API_FUNC_CERT_HANDLER_GET_INFO	cert_handler_get_info	implemented
API_FUNC_CERT_HANDLER_GET_SERVER_CERT	cert_handler_get_server_cert	implemented
API_FUNC_CERT_HANDLER_GET_SERVER_KEY	cert_handler_get_server_key	implemented
API_FUNC_CERT_HANDLER_INIT	cert_handler_init	implemented
API_FUNC_CONFIG_COMMIT	config_commit	implemented
API_FUNC_CONFIG_FACTORY_RESET	config_factory_reset	implemented
API_FUNC_CONFIG_GET_ALL_AS_JSON	config_get_all_as_json	implemented
API_FUNC_CONFIG_GET_BOOL	config_get_bool	implemented
API_FUNC_CONFIG_GET_INT16	config_get_int16	implemented
API_FUNC_CONFIG_GET_INT32	config_get_int32	implemented
API_FUNC_CONFIG_GET_SCHEMA_JSON	config_get_schema_json	implemented
API_FUNC_CONFIG_GET_STRING	config_get_string	implemented
API_FUNC_CONFIG_INIT	config_init	implemented
API_FUNC_CONFIG_SET_ALL_FROM_JSON	config_set_all_from_json	implemented
API_FUNC_CONFIG_SET_BOOL	config_set_bool	implemented
API_FUNC_CONFIG_SET_BOOL_NO_COMMIT	config_set_bool_no_commit	implemented
API_FUNC_CONFIG_SET_INT16	config_set_int16	implemented
API_FUNC_CONFIG_SET_INT16_NO_COMMIT	config_set_int16_no_commit	implemented
API_FUNC_CONFIG_SET_INT32	config_set_int32	implemented
API_FUNC_CONFIG_SET_STRING	config_set_string	implemented
API_FUNC_CONFIG_SET_STRING_NO_COMMIT	config_set_string_no_commit	implemented
API_FUNC_CONFIG_WRITE_FACTORY_DEFAULTS	config_write_factory_defaults	implemented
API_FUNC_DISPLAY_LOGIC_START	display_logic_start	implemented
API_FUNC_DISTANCE_SENSOR_GET_LATEST	distance_sensor_get_latest	implemented
API_FUNC_DISTANCE_SENSOR_GET_QUEUE_OVERFLOWS	distance_sensor_get_queue_overflows	implemented
API_FUNC_DISTANCE_SENSOR_HAS_NEW_MEASUREMENT	distance_sensor_has_new_measurement	implemented
API_FUNC_DISTANCE_SENSOR_INIT	distance_sensor_init	implemented
API_FUNC_DISTANCE_SENSOR_IS_RUNNING	distance_sensor_is_running	implemented
API_FUNC_DISTANCE_SENSOR_MONITOR	distance_sensor_monitor	implemented
API_FUNC_DISTANCE_SENSOR_START	distance_sensor_start	implemented
API_FUNC_DISTANCE_SENSOR_STOP	distance_sensor_stop	implemented
API_FUNC_LED_CLEAR_ALL	led_clear_all	implemented
API_FUNC_LED_CLEAR_PIXEL	led_clear_pixel	implemented
API_FUNC_LED_COLOR_BRIGHTNESS	led_color_brightness	implemented
API_FUNC_LED_COLOR_RGB	led_color_rgb	implemented
API_FUNC_LED_CONTROLLER_DEINIT	led_controller_deinit	implemented
API_FUNC_LED_CONTROLLER_INIT	led_controller_init	implemented
API_FUNC_LED_GET_ALL_COLORS	led_get_all_colors	implemented
API_FUNC_LED_GET_COUNT	led_get_count	implemented
API_FUNC_LED_GET_PIXEL	led_get_pixel	implemented
API_FUNC_LED_IS_INITIALIZED	led_is_initialized	implemented
API_FUNC_LED_SET_PIXEL	led_set_pixel	implemented
API_FUNC_LED_SHOW	led_show	implemented
API_FUNC_NETIF_TUNNEL_DEINIT	netif_uart_tunnel_deinit	implemented
API_FUNC_NETIF_TUNNEL_GET_HANDLE	netif_uart_tunnel_get_handle	implemented
API_FUNC_NETIF_TUNNEL_INIT	netif_uart_tunnel_init	implemented
API_FUNC_STARTUP_TESTS_MULTIPLE_CYCLES	led_running_test_multiple_cycles	implemented
API_FUNC_STARTUP_TESTS_RAINBOW	led_running_test_rainbow	implemented
API_FUNC_STARTUP_TESTS_SINGLE_CYCLE	led_running_test_single_cycle	implemented
API_FUNC_WEB_GET_PORT	web_server_get_port	implemented
API_FUNC_WEB_INIT	web_server_init	implemented
API_FUNC_WEB_IS_RUNNING	web_server_is_running	implemented
API_FUNC_WEB_START	web_server_start	implemented
API_FUNC_WEB_STATIC_FILE	static_file_handler	implemented
API_FUNC_WEB_STOP	web_server_stop	implemented
API_FUNC_WIFI_CLEAR_CRED	wifi_manager_clear_credentials	implemented
API_FUNC_WIFI_GET_IP	wifi_manager_get_ip_address	implemented
API_FUNC_WIFI_GET_STATUS	wifi_manager_get_status	implemented
API_FUNC_WIFI_INIT	wifi_manager_init	implemented
API_FUNC_WIFI_MONITOR	wifi_manager_monitor	implemented
API_FUNC_WIFI_SET_CRED	wifi_manager_set_credentials	implemented
API_FUNC_WIFI_START	wifi_manager_start	implemented
API_FUNC_WIFI_STOP	wifi_manager_stop	implemented
API_FUNC_WIFI_SWITCH_AP	wifi_manager_switch_to_ap	implemented
API_STRUCT_DISTANCE_SENSOR_ERROR	distance_sensor_error_t	implemented
API_STRUCT_DISTANCE_SENSOR_MEASUREMENT	distance_measurement_t	implemented
API_STRUCT_DISTANCE_SENSOR_RAW_MEASUREMENT	distance_raw_measurement_t	implemented
API_STRUCT_LED_COLOR	led_color_t	implemented
API_STRUCT_NETIF_TUNNEL_CONFIG	netif_uart_tunnel_config_t	implemented
API_STRUCT_WEB_CONFIG	web_server_config_t	implemented
API_STRUCT_WIFI_CRED	wifi_credentials_t	implemented
API_STRUCT_WIFI_MODE	wifi_manager_mode_t	implemented
API_STRUCT_WIFI_STATUS	wifi_status_t	implemented
REQ_CFG_JSON_1	JSON Schema as Configuration Source of Truth	implemented	config; schema; architecture
REQ_CFG_JSON_10	Web Interface Integration Support	approved	config; integration
REQ_CFG_JSON_11	NVS Error Graceful Handling	implemented	config; error-handling; reliability
REQ_CFG_JSON_12	Configuration Initialization on Boot	implemented	config; boot
REQ_CFG_JSON_13	Simple Process to Add Configuration Fields	implemented	config; extensibility; developer-experience
REQ_CFG_JSON_14	Type Safety via Optional Static Validation	implemented	config; validation; developer-experience
REQ_CFG_JSON_15	Configuration Schema Versioning and Migration	open	config; versioning; migration; future
REQ_CFG_JSON_2	Parameter Grouping for UI Organization	implemented	config; ui; schema
REQ_CFG_JSON_3	Parameter Type System	implemented	config; types
REQ_CFG_JSON_4	Build-Time Factory Defaults Generation	implemented	config; build; code-generation
REQ_CFG_JSON_5	No Runtime JSON Parsing in C Code	implemented	config; performance; memory
REQ_CFG_JSON_6	Key-Based NVS Storage	implemented	config; storage; nvs
REQ_CFG_JSON_7	Type-Safe Configuration API	implemented	config; api; type-safety
REQ_CFG_JSON_8	Persistent Configuration Storage	implemented	config; storage; nvs
REQ_CFG_JSON_9	Factory Reset Capability	implemented	config; reset
REQ_DEV_DOC_1	Supporting Documentation Traceability	implemented	developer; documentation; traceability
REQ_DEV_ENV_1	Supported Development Environments	implemented	developer; devcontainer; codespaces
REQ_DEV_GUIDE_DEBUG_1	Debugging Guide Content	implemented	developer; documentation; debugging
REQ_DEV_GUIDE_FLASH_1	Web Flasher Guide Content	implemented	developer; documentation; flasher
REQ_DEV_GUIDE_MODES_1	Switching Dev Modes Guide Content	implemented	developer; documentation; devmodes
REQ_DEV_GUIDE_QEMU_1	QEMU Emulator Guide Content	implemented	developer; documentation; qemu
REQ_DEV_LIMITS_1	Known Limitations Documentation	implemented	developer; limitations; known-issues
REQ_DEV_OV_HW_1	Hardware Specifications Content	implemented	developer; documentation; hardware
REQ_DEV_OV_INDEX_1	Overview Index Content	implemented	developer; documentation; overview
REQ_DEV_OV_QS_1	Quick Start Content	implemented	developer; documentation; quickstart
REQ_DEV_README_1	README Content Scope	implemented	developer; documentation; readme
REQ_DSP_1	Hardware Platform	approved	display; hardware; integration
REQ_DSP_2	Configuration Integration	approved	display; configuration; integration
REQ_DSP_3	Core Visualization Concept	approved	display; ux; visualization
REQ_DSP_4	Below Minimum Distance Warning	approved	display; ux; safety
REQ_DSP_5	Out of Range Display	approved	display; ux; error-handling
REQ_LED_1	WS2812 LED Strip Support	approved	led; hardware; ws2812
REQ_LED_2	Individual Pixel Control	approved	led; control; api
REQ_LED_3	Configurable LED Count	approved	led; configuration; flexibility
REQ_LED_4	Accurate Color Display	approved	led; quality; color-accuracy
REQ_LED_5	LED State Read API	approved	led; api; monitoring; web-interface
REQ_NETIF_TUNNEL_1	QEMU UART Network Bridge	approved	emulation; network; qemu; uart
REQ_NETIF_TUNNEL_2	Packet Encapsulation	approved	emulation; protocol
REQ_NETIF_TUNNEL_3	Host-Side Bridge Script	approved	emulation; tooling; host
REQ_NETIF_TUNNEL_4	DHCP Client Support	approved	emulation; network; dhcp
REQ_NETIF_TUNNEL_5	Conditional Compilation	approved	emulation; build
REQ_NETIF_TUNNEL_DOC_1	Emulation Setup Documentation	approved	emulation; documentation
REQ_NETIF_TUNNEL_NF_1	Tunnel Throughput	approved	emulation; performance
REQ_NETIF_TUNNEL_NF_2	Packet Loss Handling	approved	emulation; reliability
REQ_SNS_1	Component Initialization	approved	sensor; initialization; gpio
REQ_SNS_10	Timing and Performance	approved	sensor; performance; timing
REQ_SNS_11	Accuracy and Calibration	approved	sensor; accuracy; calibration
REQ_SNS_12	Timeout Error Handling	approved	sensor; error-handling; timeout
REQ_SNS_13	Range Validation	approved	sensor; error-handling; validation
REQ_SNS_14	Queue Overflow Management	approved	sensor; error-handling; queue
REQ_SNS_2	Trigger Pulse Generation	approved	sensor; trigger; timing
REQ_SNS_3	Real-Time Timestamp Capture	approved	sensor; isr; timing; real-time
REQ_SNS_4	Measurement Processing	approved	sensor; processing; filtering
REQ_SNS_5	Blocking API Access	approved	sensor; api; synchronization
REQ_SNS_6	Task Lifecycle Management	approved	sensor; lifecycle; freertos
REQ_SNS_7	Health Monitoring	approved	sensor; monitoring; diagnostics
REQ_SNS_8	Real-Time ISR Constraints	approved	sensor; performance; real-time; isr
REQ_SNS_9	Memory Resource Limits	approved	sensor; memory; resource
REQ_STARTUP_1	LED Controller Initialization	approved	startup; initialization; led
REQ_STARTUP_2	Visual Boot Sequence	approved	startup; ux; validation
REQ_STARTUP_3	Timing Performance	approved	startup; performance; timing
REQ_SYS_1	Garage Parking Assistance System	approved	system; parking; garage
REQ_SYS_ARCH_1	Component-based Architecture	approved	architecture; modularity
REQ_SYS_CFG_1	Non-volatile Configuration Storage	approved	storage; nvs; configuration
REQ_SYS_HW_1	ESP32 Hardware Platform	approved	hardware; platform
REQ_SYS_NET_1	WiFi Connectivity	approved	network; wifi
REQ_SYS_PERF_1	Memory Management	approved	performance; memory
REQ_SYS_REL_1	Error Handling and Recovery	approved	reliability; error-handling
REQ_SYS_SEC_1	HTTPS Support	open	security; https; future
REQ_SYS_SIM_1	Emulator Support	approved	emulator; qemu; testing
REQ_SYS_SIM_2	Emulator Network Connectivity	approved	emulator; qemu; network; development
REQ_SYS_TIME_1	System Time and NTP Support	open	time; ntp; future
REQ_SYS_WEB_1	Web-based Configuration	approved	web; configuration
REQ_WEB_1	Real-time Status Display	approved	web; ui; monitoring
REQ_WEB_2	Configuration Interface	approved	web; ui; configuration
REQ_WEB_3	WiFi Setup Interface	approved	web; wifi; network
REQ_WEB_4	Web Interface Navigation	approved	web; ui; navigation
REQ_WEB_5	HTTP Server Concurrency	approved	web; performance
REQ_WEB_CONF_1	Configuration REST API	approved	web; api; config
REQ_WEB_LED_1	LED State API Endpoint	approved	web; api; led; visualization
REQ_WEB_NF_1	Web UI Responsiveness	approved	web; performance; ux
REQ_WEB_NF_2	Mobile-First Design	approved	web; ui; mobile
REQ_WEB_SCHEMA_1	Schema-Driven Configuration Form	approved	web; ui; config
SPEC_ARCH_BUILD_1	ESP-IDF CMake Integration	approved	build; cmake
SPEC_ARCH_CERT_1	Certificate Handler Component Design	draft	component; security
SPEC_ARCH_CODESPACES_1	GitHub Codespaces Integration	approved	development; devcontainer
SPEC_ARCH_COMM_1	Component Communication Pattern	approved	dataflow; communication
SPEC_ARCH_CONFIG_1	Configuration Manager Component Design	approved	component; config
SPEC_ARCH_CONFIG_FLOW_1	Configuration Data Flow	approved	dataflow; config
SPEC_ARCH_ERROR_RECOVERY_1	Error Recovery and Reset Strategy	approved	error-handling; reliability; reset
SPEC_ARCH_FLASH_1	Flash Memory Configuration	approved	flash; memory
SPEC_ARCH_HTTP_1	HTTP Server Architecture Details	approved	network; http; web
SPEC_ARCH_LAYERS_1	ESP32 Distance Sensor Layered Architecture	approved	architecture; layering
SPEC_ARCH_LOGGING_1	Logging and Diagnostics Strategy	approved	logging; diagnostics; debugging
SPEC_ARCH_MEMORY_1	Memory Management Strategy	approved	memory; performance
SPEC_ARCH_NETIF_1	Network Tunnel Component Design	approved	component; qemu; network
SPEC_ARCH_PERF_1	System Performance Requirements	approved	performance; requirements
SPEC_ARCH_QEMU_1	QEMU Hardware Abstraction	approved	qemu; emulation
SPEC_ARCH_QEMU_BUILD_1	QEMU Component Selection	approved	qemu; build
SPEC_ARCH_TASKS_1	FreeRTOS Task Organization	approved	threading; rtos
SPEC_ARCH_WEB_1	Web Server Component Design	approved	component; web; network
SPEC_ARCH_WIFI_1	WiFi Manager Design Details	approved	network; wifi
SPEC_CFG_JSON_API_1	Type-Safe Configuration API	approved	api; interface; c-api
SPEC_CFG_JSON_ARCH_1	JSON Schema-Driven Architecture	draft	architecture; config; json-schema
SPEC_CFG_JSON_BULK_1	Bulk JSON Configuration API	approved	api; json; bulk-operations
SPEC_CFG_JSON_CODEGEN_1	Factory Reset via Bulk JSON Update	approved	build-process; code-generation; factory-reset
SPEC_CFG_JSON_EXTEND_1	Adding New Configuration Fields	approved	development; guide; extensibility
SPEC_CFG_JSON_SCHEMA_1	Configuration Schema Structure	approved	data-structure; schema
SPEC_CFG_JSON_SOURCE_1	JSON Schema as Single Source of Truth	approved	architecture; schema; design-pattern
SPEC_CFG_JSON_STORAGE_1	NVS Storage Format	approved	storage; nvs
SPEC_CFG_JSON_TYPESAFETY_1	Type Safety Without Code Generation	approved	type-safety; best-practices
SPEC_CFG_JSON_UI_1	JSON Schema for UI Generation	approved	web; ui; javascript
SPEC_CFG_WEB_ARCH_1	Configuration Webpage Architecture	implemented	frontend; javascript; ui
SPEC_CFG_WEB_COUNTDOWN_1	Device Reset Countdown Interface	implemented	ui; countdown; reset
SPEC_CFG_WEB_ERROR_1	Error Handling and User Feedback	implemented	error-handling; feedback
SPEC_CFG_WEB_FLOW_1	Configuration Data Flow	implemented	data-flow; json; api
SPEC_CFG_WEB_FORM_1	Dynamic Form Generation from Schema	implemented	form-generation; schema; javascript
SPEC_CFG_WEB_INIT_1	Complete Page Initialization Flow	implemented	initialization; lifecycle
SPEC_CFG_WEB_MAPPING_1	JSON Array to Form Field Mapping	implemented	data-mapping; json; form
SPEC_CFG_WEB_STATE_1	UI State Management	implemented	ui-state; javascript
SPEC_DEV_ENV_OPTIONS	Supported Development Environments — Options	implemented	developer; devcontainer; codespaces
SPEC_DEV_ENV_USAGE	Supported Development Environments — Setup Steps	implemented	developer; devcontainer; codespaces
SPEC_DEV_GUIDE_DEBUG_FEATURES	Debugging Guide — Debugging Features	implemented	developer; documentation; debugging
SPEC_DEV_GUIDE_DEBUG_START	Debugging Guide — Quick Start in QEMU	implemented	developer; documentation; debugging
SPEC_DEV_GUIDE_FLASH_OVERVIEW	Web Flasher Guide — Overview and Browser Requirements	implemented	developer; documentation; flasher
SPEC_DEV_GUIDE_FLASH_STEPS	Web Flasher Guide — Flash Procedure	implemented	developer; documentation; flasher
SPEC_DEV_GUIDE_MODES_DIFF	Dev Modes Guide — What Changes Between Modes	implemented	developer; documentation; devmodes
SPEC_DEV_GUIDE_MODES_HOW	Dev Modes Guide — How to Switch	implemented	developer; documentation; devmodes
SPEC_DEV_GUIDE_QEMU_START	QEMU Guide — Starting QEMU	implemented	developer; documentation; qemu
SPEC_DEV_GUIDE_QEMU_STOP	QEMU Guide — Stopping QEMU	implemented	developer; documentation; qemu
SPEC_DEV_GUIDE_QEMU_WEB	QEMU Guide — Accessing the Web Interface	implemented	developer; documentation; qemu
SPEC_DEV_LIMITS_STRUCTURE	Known Limitations File Structure and Process	implemented	developer; limitations; known-issues
SPEC_DEV_OV_HW_COMPONENTS	Hardware Components Listing	implemented	developer; documentation; hardware
SPEC_DEV_OV_HW_PINS	Hardware Pin Assignment Table	implemented	developer; documentation; hardware
SPEC_DEV_OV_INDEX_NAV	Overview Index — Navigation Section	implemented	developer; documentation; overview
SPEC_DEV_OV_INDEX_WHAT	Overview Index — Project Description	implemented	developer; documentation; overview
SPEC_DEV_OV_INDEX_WHO	Overview Index — Audience Section	implemented	developer; documentation; overview
SPEC_DEV_OV_QS_HW	Quick Start — Hardware Path	implemented	developer; documentation; quickstart; hardware
SPEC_DEV_OV_QS_QEMU	Quick Start — QEMU Path	implemented	developer; documentation; quickstart; qemu
SPEC_DEV_README_INTRO	README Introduction and Project Link	implemented	developer; documentation; readme
SPEC_DEV_README_META	README Metadata Section	implemented	developer; documentation; readme
SPEC_DSP_ALGO_1	Distance-to-Visual Mapping Algorithm	approved	display; algorithm; mapping
SPEC_DSP_ALGO_3	Embedded Arithmetic Architecture	approved	display; performance; arithmetic
SPEC_DSP_API_1	Public Display API	approved	display; api; interface
SPEC_DSP_ARCH_1	Task-Based Architecture	approved	display; freertos; task
SPEC_DSP_ARCH_2	Configuration Integration	approved	display; configuration
SPEC_DSP_OVERVIEW_1	WS2812 Hardware Integration	approved	display; hardware; integration
SPEC_LED_API_1	Pixel-Level Control API	approved	led; api; control
SPEC_LED_API_2	Batch Operations API	approved	led; api; batch
SPEC_LED_API_3	LED State Read API	approved	led; api; monitoring; thread-safety
SPEC_LED_ARCH_1	RMT Peripheral Hardware Abstraction	approved	led; rmt; hardware
SPEC_LED_ARCH_2	RAM Buffer Architecture	approved	led; memory; buffer
SPEC_LED_DATA_1	Color Representation and Conversion	approved	led; color; conversion
SPEC_LED_ERR_1	Error Handling and Validation	approved	led; error-handling; validation
SPEC_LED_MEM_1	Dynamic Memory Management	approved	led; memory; resource
SPEC_LED_SIM_1	LED Controller Simulator	approved	led; simulator; qemu
SPEC_LED_TIMING_1	WS2812 Timing Specification	approved	led; timing; ws2812
SPEC_NETIF_UART_ARCH_1	UART Tunnel Component Architecture	implemented	netif; qemu; uart; architecture
SPEC_NETIF_UART_BRIDGE_1	Host-Side Serial-TUN Bridge Script	implemented	netif; qemu; python; bridge; tooling
SPEC_NETIF_UART_COND_1	Conditional Compilation — QEMU-Only Build Guard	implemented	netif; qemu; build; kconfig
SPEC_NETIF_UART_DHCP_1	IP Configuration and DHCP Client Integration	implemented	netif; qemu; dhcp; ip
SPEC_NETIF_UART_DOC_1	Emulation Setup Documentation	implemented	netif; qemu; documentation
SPEC_NETIF_UART_PERF_1	Performance Characteristics and Known Limitations	implemented	netif; qemu; performance; limitations
SPEC_NETIF_UART_PROTO_1	UART Wire Protocol — Length-Prefix Framing	implemented	netif; qemu; protocol; framing
SPEC_SNS_ALGO_1	Distance Calculation Algorithm	approved	sensor; algorithm; calibration
SPEC_SNS_ALGO_2	EMA Smoothing Filter Design	approved	sensor; algorithm; filtering
SPEC_SNS_API_1	Public API Design	approved	sensor; api; interface
SPEC_SNS_ARCH_1	Dual-Queue Real-Time Architecture	approved	sensor; architecture; real-time
SPEC_SNS_ARCH_2	GPIO Interface Design	approved	sensor; gpio; hardware
SPEC_SNS_ERR_1	Error Handling Design	approved	sensor; error-handling; robustness
SPEC_SNS_ISR_1	Interrupt Service Routine Design	approved	sensor; isr; real-time
SPEC_SNS_SIM_1	Distance Sensor Simulator Design	approved	sensor; simulator; qemu
SPEC_SNS_TASK_1	Sensor Task Design	approved	sensor; freertos; task
SPEC_STARTUP_1	LED Controller Dependency Design	approved	startup; initialization; dependency
SPEC_STARTUP_2	Sequential LED Pattern Algorithm	approved	startup; algorithm; visual
SPEC_STARTUP_3	Startup Integration and Cleanup	approved	startup; integration; cleanup
SPEC_STARTUP_4	Component Architecture	approved	startup; architecture; component
SPEC_WEB_ARCH_1	Web Server Architecture	approved	web; architecture
SPEC_WEB_CAPTIVE_1	Captive Portal Design	approved	web; captive-portal; wifi
SPEC_WEB_CONFIG_1	HTTP Server Configuration	approved	web; config; performance
SPEC_WEB_EXTEND_1	Extension Guide for Web Pages	approved	web; extensibility; guide
SPEC_WEB_INTEGRATION_CFG_1	Config Manager Integration Pattern	approved	web; integration; config
SPEC_WEB_INTEGRATION_WIFI_1	WiFi Manager Integration Pattern	approved	web; integration; wifi
SPEC_WEB_NF_1	Mobile-First Responsive Design	approved	web; ui; mobile; responsive
SPEC_WEB_REST_CFG_1	Configuration API Endpoints	approved	web; api; config; schema
SPEC_WEB_REST_HEALTH_1	System Health API Endpoint	approved	web; api; diagnostics
SPEC_WEB_REST_LED_1	LED State API Endpoint	approved	web; api; led; visualization
SPEC_WEB_REST_WIFI_1	WiFi Management REST API Endpoints	approved	web; api; wifi
SPEC_WEB_ROUTES_1	URI Routing Table	approved	web; routing
SPEC_WEB_SECURITY_1	CORS Configuration	approved	web; security; cors
SPEC_WEB_STATIC_1	Static File Embedding Strategy	approved	web; build; embedding
SPEC_WEB_TEST_1	Web Server Testing Strategy	approved	web; testing
US_DEV_1	Modular Firmware Extensibility	implemented	developer; firmware; extensibility
US_DEV_2	Traceable Supporting Documentation	implemented	developer; documentation; traceability
US_DISPLAY_1	Visual Distance Feedback for Parking	approved	display; sensor; garage-user
US_RELIABLE_1	Appliance Reliability - Just Works on Power	approved	reliability; startup; garage-user
US_SETUP_1	Device Setup via Web Interface	approved	setup; wifi; web; maker