JSON-Based Configuration Manager Requirements¶

This document specifies component-level requirements for the JSON-Schema-Driven Configuration Management System. These requirements refine the high-level system requirement Non-volatile Configuration ... (REQ_SYS_CFG_1) (Non-volatile Configuration Storage).

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

Component Overview¶

The JSON-based configuration manager component provides centralized configuration management through a single JSON schema source of truth. Configuration is stored persistently in NVS and accessed via type-safe C API. The web interface generates forms dynamically from the schema.

Configuration Schema Definition¶

Requirement: JSON Schema as Configuration Source of Truth REQ_CFG_JSON_1

status: implemented

tags: config, schema, architecture

priority: mandatory

links outgoing: REQ_SYS_CFG_1

links incoming: US_SETUP_1, REQ_CFG_JSON_2, REQ_CFG_JSON_3, REQ_CFG_JSON_4, REQ_CFG_JSON_6, REQ_CFG_JSON_10, REQ_CFG_JSON_13, REQ_CFG_JSON_15, REQ_DSP_2, SPEC_CFG_JSON_ARCH_1, SPEC_CFG_JSON_SOURCE_1, SPEC_CFG_JSON_SCHEMA_1, SPEC_CFG_JSON_CODEGEN_1, SPEC_CFG_JSON_EXTEND_1, SPEC_DSP_ARCH_2, API_COMP_CONFIG_MANAGER

Description: The configuration manager SHALL define all configuration parameters in a single JSON schema file (config_schema.json) that serves as the authoritative source of truth for parameter definitions, default values, and UI metadata.

Rationale: Single source of truth prevents duplication across C code, web forms, and documentation. Schema-driven approach enables code generation for factory defaults and dynamic UI generation.

Acceptance Criteria:

AC-1: JSON schema file SHALL define all user-configurable parameters
AC-2: Schema SHALL include parameter type, label, default value, and validation constraints
AC-3: Parameters organized in groups for UI section structure
AC-4: Schema SHALL be embeddable in flash for browser access
AC-5: Schema format SHALL be human-readable and maintainable

Requirement: Parameter Grouping for UI Organization REQ_CFG_JSON_2

status: implemented

tags: config, ui, schema

priority: optional

links outgoing: REQ_CFG_JSON_1

links incoming: US_SETUP_1, SPEC_CFG_JSON_SCHEMA_1

Description: The configuration schema SHALL support logical grouping of parameters into sections for organization in the web interface.

Rationale: Logical organization improves usability for configuration with many parameters.

Acceptance Criteria:

AC-1: Each group SHALL have id, label, and description
AC-2: Fields SHALL reference group by id
AC-3: UI SHALL display fields grouped and ordered as specified in schema
AC-4: Each group SHALL be collapsible/expandable (optional UI feature)

Requirement: Parameter Type System REQ_CFG_JSON_3

status: implemented

tags: config, types

priority: mandatory

links outgoing: REQ_CFG_JSON_1

links incoming: US_SETUP_1, SPEC_CFG_JSON_SCHEMA_1

Description: The configuration system SHALL support basic parameter types: string, password, integer, boolean, and hidden.

Rationale: Covers typical IoT configuration needs while remaining simple. Separate types enable appropriate UI widgets and validation.

Acceptance Criteria:

AC-1: String type SHALL support min/max length and regex pattern validation
AC-2: Password type SHALL be string type with hidden display in UI
AC-3: Integer type SHALL support min/max range and step constraints
AC-4: Boolean type SHALL map to checkbox in UI
AC-5: Hidden type SHALL not appear in web form (internal config)

Configuration Generation and Defaults¶

Requirement: Build-Time Factory Defaults Generation REQ_CFG_JSON_4

status: implemented

tags: config, build, code-generation

priority: mandatory

links outgoing: REQ_CFG_JSON_1, REQ_SYS_CFG_1

links incoming: US_SETUP_1, REQ_CFG_JSON_5, REQ_CFG_JSON_9, SPEC_CFG_JSON_CODEGEN_1, API_COMP_CONFIG_MANAGER, API_FUNC_CONFIG_WRITE_FACTORY_DEFAULTS

Description: The build system SHALL automatically generate C code to initialize factory default configuration from the JSON schema during build time.

Rationale: Eliminates manual default value maintenance in C code. Generated code is compiled into firmware, ensuring defaults match schema without runtime JSON parsing.

Acceptance Criteria:

AC-1: Python script SHALL parse config_schema.json during build
AC-2: Script SHALL generate config_factory_generated.c with config_write_factory_defaults() function
AC-3: Generated function SHALL call config_set_xxx() for each schema field with default value
AC-4: Build SHALL fail if schema is invalid JSON
AC-5: Generated code SHALL be included in firmware compilation

Requirement: No Runtime JSON Parsing in C Code REQ_CFG_JSON_5

status: implemented

tags: config, performance, memory

priority: mandatory

links outgoing: REQ_CFG_JSON_4

links incoming: US_SETUP_1, SPEC_CFG_JSON_CODEGEN_1

Description: The ESP32 application code SHALL NOT parse JSON at runtime. JSON parsing SHALL occur only at build time (code generation) or in browser (UI).

Rationale: Eliminates runtime overhead and memory overhead of JSON parser on resource-constrained ESP32. Simplifies C code and improves performance.

Acceptance Criteria:

AC-1: C code SHALL NOT include JSON parser library
AC-2: NVS access SHALL use direct key-value API (no JSON deserialization)
AC-3: Factory reset SHALL call pre-generated config_write_factory_defaults() function
AC-4: Runtime memory usage SHALL not include JSON parser structures

NVS Storage and Access¶

Requirement: Key-Based NVS Storage REQ_CFG_JSON_6

status: implemented

tags: config, storage, nvs

priority: mandatory

links outgoing: REQ_CFG_JSON_1, REQ_SYS_CFG_1

links incoming: US_SETUP_1, REQ_CFG_JSON_7, REQ_CFG_JSON_8, REQ_CFG_JSON_11, REQ_CFG_JSON_12, SPEC_CFG_JSON_ARCH_1, SPEC_CFG_JSON_STORAGE_1, SPEC_CFG_JSON_API_1, API_COMP_CONFIG_MANAGER

Description: Configuration parameters SHALL be stored in NVS using the schema “key” field directly as the NVS key.

Rationale: Direct key usage simplifies storage format and eliminates need for separate UUID system. Keys are human-readable for debugging.

Acceptance Criteria:

AC-1: Each schema field key SHALL be valid NVS key (≤15 characters)
AC-2: NVS storage SHALL use “config” namespace for isolation
AC-3: Parameter values SHALL be stored individually (not as single blob)
AC-4: NVS key SHALL directly match schema field key

Requirement: Type-Safe Configuration API REQ_CFG_JSON_7

status: implemented

tags: config, api, type-safety

priority: mandatory

Description: The configuration manager SHALL provide type-specific getter and setter functions for configuration access.

Rationale: Type-specific functions enforce compile-time type checking via function signature. Different functions for different types prevent accidental type mismatches at call site.

Acceptance Criteria:

AC-1: Getters SHALL be: config_get_string(), config_get_int32(), config_get_int16(), config_get_bool()
AC-2: Setters SHALL be: config_set_string(), config_set_int32(), config_set_int16(), config_set_bool()
AC-3: All functions SHALL take key as string parameter (matches schema key)
AC-4: Functions SHALL return ESP_OK or error code (ESP_ERR_INVALID_ARG, ESP_ERR_NVS_*)
AC-5: Caller SHALL use matching function for parameter type in schema

Requirement: Persistent Configuration Storage REQ_CFG_JSON_8

status: implemented

tags: config, storage, nvs

priority: mandatory

links outgoing: REQ_CFG_JSON_6

links incoming: SPEC_CFG_JSON_STORAGE_1, API_COMP_CONFIG_MANAGER, API_FUNC_CONFIG_COMMIT

Description: Configuration changes SHALL be immediately persisted to NVS on each config_set_xxx() call.

Rationale: Ensures configuration survives power loss and system resets.

Acceptance Criteria:

AC-1: config_set_xxx() SHALL write to NVS before returning
AC-2: Write failures SHALL be logged but not crash system
AC-3: Configuration SHALL be reloaded from NVS on next system boot
AC-4: NVS corruption SHALL be handled gracefully with defaults

Requirement: Factory Reset Capability REQ_CFG_JSON_9

status: implemented

tags: config, reset

priority: mandatory

links outgoing: REQ_CFG_JSON_4, REQ_SYS_CFG_1

links incoming: SPEC_CFG_JSON_CODEGEN_1, API_COMP_CONFIG_MANAGER, API_FUNC_CONFIG_FACTORY_RESET

Description: The system SHALL provide config_factory_reset() function to reset all configuration to schema-defined defaults.

Rationale: Users need ability to recover from misconfiguration without firmware rebuild.

Acceptance Criteria:

AC-1: Factory reset SHALL erase all values in “config” NVS namespace
AC-2: Factory reset SHALL call config_write_factory_defaults() to restore defaults
AC-3: Factory reset SHALL return success/error status
AC-4: Factory reset errors SHALL be logged

Web Interface Integration¶

Requirement: Web Interface Integration Support REQ_CFG_JSON_10

status: approved

tags: config, integration

priority: optional

links outgoing: REQ_SYS_WEB_1, REQ_CFG_JSON_1, REQ_CFG_JSON_7

links incoming: SPEC_CFG_JSON_UI_1, SPEC_WEB_INTEGRATION_CFG_1

Description: The configuration system SHOULD provide integration points for web-based configuration interfaces.

Rationale: Web servers need access to configuration schema and runtime values to provide user interfaces. Config Manager provides the data layer; Web Server provides the HTTP/UI layer.

Acceptance Criteria:

AC-1: Configuration schema file (config_schema.json) SHALL be embeddable in web server
AC-2: C API functions (config_get_*, config_set_*) SHALL be callable from web request handlers
AC-3: Schema format SHALL support web form generation use cases
AC-4: API SHALL return error codes suitable for HTTP status mapping

Note: Detailed web interface requirements (HTML forms, REST API endpoints, validation) are specified in Web Server Requirements (Configuration REST API (REQ_WEB_CONF_1)). This requirement ensures Config Manager provides necessary integration points without knowing HTTP details.

Error Handling¶

Requirement: NVS Error Graceful Handling REQ_CFG_JSON_11

status: implemented

tags: config, error-handling, reliability

priority: mandatory

links outgoing: REQ_CFG_JSON_6, REQ_SYS_REL_1

links incoming: REQ_CFG_JSON_12, SPEC_CFG_JSON_UI_1, API_COMP_CONFIG_MANAGER

Description: The configuration system SHALL gracefully handle NVS errors and continue operating with default values.

Rationale: NVS corruption or wear should not prevent system operation.

Acceptance Criteria:

AC-1: NVS read failures SHALL log error and use schema default value
AC-2: NVS write failures SHALL log error but not crash application
AC-3: System SHALL boot successfully even if NVS namespace is corrupted
AC-4: Web interface SHALL indicate NVS error status to user

Requirement: Configuration Initialization on Boot REQ_CFG_JSON_12

status: implemented

tags: config, boot

priority: mandatory

links outgoing: REQ_CFG_JSON_6, REQ_CFG_JSON_11

links incoming: SPEC_CFG_JSON_BULK_1, SPEC_CFG_WEB_ARCH_1, API_COMP_CONFIG_MANAGER, API_FUNC_CONFIG_INIT, API_FUNC_CONFIG_GET_SCHEMA_JSON, API_FUNC_CONFIG_GET_ALL_AS_JSON

Description: On first boot, config_init() SHALL initialize NVS with factory defaults from schema if NVS “config” namespace is empty or uninitialized.

Rationale: New devices need sensible defaults on first boot.

Acceptance Criteria:

AC-1: config_init() SHALL check if NVS “config” namespace exists
AC-2: If empty, config_init() SHALL call config_factory_reset() to write defaults
AC-3: On subsequent boots, config_init() SHALL load values from NVS
AC-4: Process SHALL be atomic (no partial updates)

Development Guide¶

Requirement: Simple Process to Add Configuration Fields REQ_CFG_JSON_13

status: implemented

tags: config, extensibility, developer-experience

priority: optional

links outgoing: REQ_CFG_JSON_1

links incoming: SPEC_CFG_JSON_BULK_1, SPEC_CFG_JSON_EXTEND_1, SPEC_CFG_WEB_ARCH_1, API_COMP_CONFIG_MANAGER, API_FUNC_CONFIG_SET_ALL_FROM_JSON

Description: Adding new configuration parameters SHALL require modification of only config_schema.json, with C code and web UI auto-updating.

Rationale: Low friction for extending configuration reduces development time.

Acceptance Criteria:

AC-1: New field added to config_schema.json SHALL appear in web form on next page reload
AC-2: Developer SHALL call config_get_xxx(“key”) in C code matching schema key
AC-3: Factory defaults auto-generated from schema (no manual C code needed)
AC-4: Documentation SHALL provide step-by-step guide for adding fields

Requirement: Type Safety via Optional Static Validation REQ_CFG_JSON_14

status: implemented

tags: config, validation, developer-experience

priority: optional

links outgoing: REQ_CFG_JSON_7

links incoming: SPEC_CFG_JSON_TYPESAFETY_1

Description: The build system SHOULD provide optional pre-build validation script that detects type mismatches between schema and C code.

Rationale: Catches developer errors early without requiring code generation. Optional to keep build simple.

Acceptance Criteria:

AC-1: Validator script SHALL parse config_schema.json
AC-2: Script SHALL search C source files for config_get_xxx(“key”) calls
AC-3: Script SHALL verify function type matches schema type
AC-4: Script SHALL output errors for mismatches
AC-5: Integration into build pipeline SHALL be optional (can be skipped)

Future Enhancements¶

Requirement: Configuration Schema Versioning and Migration REQ_CFG_JSON_15

status: open

tags: config, versioning, migration, future

priority: optional

links outgoing: REQ_CFG_JSON_1

Description: The configuration system MAY support schema versioning and automatic migration of configuration data across firmware updates.

Rationale: As firmware evolves, configuration structure may change (new fields, renamed keys, changed types). Schema versioning enables detection and migration of old configurations. However, embedded devices are typically “programmed out” thoroughly before production deployment, minimizing schema changes after deployment.

Acceptance Criteria (if implemented):

AC-1: config_schema.json includes “schema_version” field
AC-2: config_init() detects NVS schema version mismatch
AC-3: Migration functions upgrade old config to new schema
AC-4: Migration preserves user settings where possible
AC-5: Failed migration triggers factory reset with user warning

Note: This requirement is marked “open” as schema changes are rare in production embedded systems. Hardware constraints typically stabilize configuration structure early in development. For most deployments, factory reset on major firmware updates is acceptable alternative to complex migration logic.

Traceability¶

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

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