JSON-Based Configuration Manager Design¶

This document specifies the design for JSON-Schema-Driven Configuration System, covering architecture, data flow, schema design, and implementation approach.

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

Architecture Overview¶

Design Specification: JSON Schema-Driven Architecture SPEC_CFG_JSON_ARCH_1

status: draft

tags: architecture, config, json-schema

links outgoing: REQ_CFG_JSON_1, REQ_CFG_JSON_6

Description: The configuration system uses a single JSON schema as source of truth with build-time code generation and runtime NVS storage.

Architecture Layers:

┌──────────────────────────────────────────────┐
│          Application Layer                   │
│  (main.c, components)                        │
│  Uses: config_get_int32("led_count")         │
├──────────────────────────────────────────────┤
│     Configuration API Layer (NVS wrapper)    │
│  (config_manager.c, config_manager.h)        │
│  Direct key-based access, no JSON parsing    │
├──────────────────────────────────────────────┤
│         NVS Storage Layer                    │
│  Direct key→value mapping (no complexity)    │
├──────────────────────────────────────────────┤
│         Metadata (Build-Time)                │
│  config_schema.json (source of truth)        │
└──────────────────────────────────────────────┘

Browser UI Layer (Separate):

┌──────────────────────────────────────────────┐
│      Browser Client (JavaScript)             │
│  Fetches: /config_schema.json                │
│  Generates: Form UI dynamically              │
│  Validates: Client-side (min/max/pattern)    │
└──────────────────────────────────────────────┘

Key Design Principle: C code does NOT parse JSON at runtime. JSON is embedded as static file for browser only.

Layer Responsibilities:

Application Layer: Consumes configuration via simple API (config_get_xxx/config_set_xxx)
Config Manager: Thin NVS wrapper, type-safe getters/setters, no validation logic
NVS Layer: Simple key-value storage, no complex structures
JSON Schema: Defines structure, defaults, UI labels, validation rules (build/browser only)

Design Specification: JSON Schema as Single Source of Truth SPEC_CFG_JSON_SOURCE_1

status: approved

tags: architecture, schema, design-pattern

links outgoing: REQ_CFG_JSON_1

Description: Configuration schema defined once in JSON, used for multiple purposes without duplication.

Single Source of Truth Model:

config_schema.json (ONLY definition)
      │
      ├──→ C Code (config_factory_generated.c)
      │    Generates: config_write_factory_defaults() function
      │    Purpose: Initialize NVS with defaults at build-time
      │    When: Build-time Python script (no runtime parsing)
      │
      ├──→ Browser (fetched at runtime)
      │    Fetches: GET /config_schema.json
      │    Purpose: Generate form, validate inputs
      │    When: User loads settings page
      │
      └──→ Documentation/Reference
           Developers read schema to understand config fields

Benefits:

No Duplication: Update schema once, form auto-updates, defaults auto-generated
Type Safety: C code validates types match schema (optional validator script)
Self-Documenting: Schema contains labels, descriptions, validation rules
Zero Runtime Overhead: JSON parsing happens at build-time only, not on ESP32

Data Structure Design¶

Design Specification: Configuration Schema Structure SPEC_CFG_JSON_SCHEMA_1

status: approved

tags: data-structure, schema

links outgoing: REQ_CFG_JSON_1, REQ_CFG_JSON_2, REQ_CFG_JSON_3

links incoming: SPEC_CFG_WEB_FORM_1

Description: JSON schema defines all configuration fields with metadata for type-safety and UI generation.

Schema File Location: main/components/config_manager/config_schema.json

Schema Structure:

{
  "schema_version": "1.0",
  "config_namespace": "esp32_app",
  "groups": [
    {
      "id": "wifi",
      "label": "📶 WiFi Settings",
      "description": "Network configuration",
      "order": 1
    }
  ],
  "fields": [
    {
      "key": "wifi_ssid",
      "type": "string",
      "label": "WiFi SSID",
      "default": "",
      "required": true,
      "maxLength": 32,
      "pattern": "^[^\\x00]{1,32}$",
      "group": "wifi",
      "order": 1
    }
  ]
}

Schema Elements:

schema_version: Version for future compatibility
config_namespace: NVS namespace name
groups: UI section grouping (order matters)
fields: Individual configuration parameters

Field Properties:

Property	Type	Purpose
key	string	NVS key name (≤15 chars), used directly: config_get(“key”)
type	enum	One of: “string”, “password”, “integer”, “boolean”, “hidden”
label	string	Human-readable label for UI
default	mixed	Default value if NVS not initialized
required	bool	If true, must have a value
group	string	Associates field with a group (from groups.id)
order	int	Display order (within group, lower = first)
minLength / maxLength	int	(string/password) Length constraints
min / max	int	(integer) Range constraints
step	int	(integer) UI increment step
pattern	regex	(string/password) Validation regex (browser-only)

Type Mapping to C API:

// Browser forms generated based on type
"string"   → <input type="text">
"password" → <input type="password">
"integer"  → <input type="number">
"boolean"  → <input type="checkbox">
"hidden"   → <input type="hidden">

// C code uses matching getters
"string" / "password"  → config_get_string(key, buf, len)
"integer"             → config_get_int32(key, &value) or config_get_int16(key, &value)
"boolean"             → config_get_bool(key, &value)
"hidden"              → config_get_string(key, buf, len)  (internal config)

Design Rationale:

Direct Key Usage: Using key directly as NVS key eliminates separate UUIDs (saves flash)
Flat Attributes: No nested validation objects (simpler JSON, smaller file)
Type Defines Input: Single type field eliminates redundant inputType property
Groups for Organization: Sections on settings page without separate metadata structure
Order Field: Ensures predictable UI layout (JSON object order not guaranteed)

Design Specification: Factory Reset via Bulk JSON Update SPEC_CFG_JSON_CODEGEN_1

status: approved

tags: build-process, code-generation, factory-reset

links outgoing: REQ_CFG_JSON_1, REQ_CFG_JSON_4, REQ_CFG_JSON_5, REQ_CFG_JSON_9

Description: Factory reset uses the bulk JSON configuration system for consistent data processing and validation.

JSON-Based Factory Reset Architecture:

config_schema.json
      │
      └──→ tools/generate_config_factory.py (Python 3)
           │
           └──→ config_factory_generated.c (auto-generated, compiled)

                const char* config_factory_defaults_json =
                "["
                "  {\"key\":\"wifi_ssid\",\"type\":\"string\",\"value\":\"\"},"
                "  {\"key\":\"wifi_pass\",\"type\":\"string\",\"value\":\"\"},"
                "  {\"key\":\"ap_ssid\",\"type\":\"string\",\"value\":\"ESP32-Setup\"},"
                "  {\"key\":\"led_count\",\"type\":\"integer\",\"value\":50}"
                "]";

                esp_err_t config_write_factory_defaults(void) {
                    return config_set_all_from_json(config_factory_defaults_json);
                }

Generator Script (Simplified):

#!/usr/bin/env python3
import json
import sys

def generate_factory_json(schema_file, output_file):
    with open(schema_file) as f:
        schema = json.load(f)

    # Build factory defaults JSON array with {key, type, value} structure
    defaults_array = []
    for field in schema['fields']:
        defaults_array.append({
            'key': field['key'],
            'type': field['type'],
            'value': field['default']
        })

    factory_json = json.dumps(defaults_array, separators=(',', ':'))

    with open(output_file, 'w') as f:
        f.write('// Auto-generated - DO NOT EDIT\n')
        f.write('#include "config_manager.h"\n\n')
        f.write(f'const char* config_factory_defaults_json = "{factory_json}";\n\n')
        f.write('esp_err_t config_write_factory_defaults(void) {\n')
        f.write('    return config_set_all_from_json(config_factory_defaults_json);\n')
        f.write('}\n')

if __name__ == '__main__':
    generate_factory_json(sys.argv[1], sys.argv[2])

CMake Integration: (unchanged)

# Generate factory defaults from schema
add_custom_command(
    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/config_factory_generated.c
    COMMAND python3 ${CMAKE_CURRENT_SOURCE_DIR}/tools/generate_config_factory.py
            ${CMAKE_CURRENT_SOURCE_DIR}/config_schema.json
            ${CMAKE_CURRENT_BINARY_DIR}/config_factory_generated.c
    DEPENDS config_schema.json tools/generate_config_factory.py
    COMMENT "Generating factory config defaults from schema"
)

idf_component_register(
    SRCS "config_manager.c"
         "${CMAKE_CURRENT_BINARY_DIR}/config_factory_generated.c"
    INCLUDE_DIRS "include"
    EMBED_FILES "config_schema.json"
)

Key Design Properties:

Consistent API: Factory reset uses same config_set_all_from_json() function
Schema-Driven: Generator reads schema to create structured JSON array
Build-Time Generation: Factory defaults compiled into firmware
Atomic Operation: All defaults applied in single transaction

Design Specification: NVS Storage Format SPEC_CFG_JSON_STORAGE_1

status: approved

tags: storage, nvs

links outgoing: REQ_CFG_JSON_6, REQ_CFG_JSON_8

Description: Configuration parameters stored in NVS using schema keys directly.

Storage Strategy:

// NVS namespace: "config"
// NVS keys: schema "key" fields (≤15 chars required)

config_schema.json:
{
  "key": "wifi_ssid",
  "default": "ESP32-AP"
}

Stored in NVS as:
nvs_set_str(handle, "wifi_ssid", "ESP32-AP");

Retrieved with:
char ssid[33];
nvs_get_str(handle, "wifi_ssid", ssid, sizeof(ssid));

Key Properties:

Direct Keys: NVS key = schema “key” field (no transformation)
Key Length: Must be ≤15 characters (ESP-IDF NVS constraint)
Type-Specific Storage: Uses correct NVS function (nvs_set_str, nvs_set_i32, etc.)
Namespace Isolation: All config in “config” namespace, separate from other NVS users
Simple Structure: No metadata stored, only values

Example NVS Content:

Namespace: config
├─ "wifi_ssid"      → "ESP32-AP" (string)
├─ "wifi_password"  → "" (string)
├─ "led_count"      → 60 (integer)
└─ "ap_channel"     → 1 (integer)

Design Rationale:

No UUID System: Using meaningful keys directly is simpler and readable
Minimal Overhead: NVS overhead minimized with short, direct keys
Easy Debugging: Readable keys vs. UUID system

NVS Access Layer (Config Manager)¶

Design Specification: Type-Safe Configuration API SPEC_CFG_JSON_API_1

status: approved

tags: api, interface, c-api

links outgoing: REQ_CFG_JSON_7, REQ_CFG_JSON_6

Description: Thin NVS wrapper providing type-safe getters and setters for configuration values.

Core API:

// ====== Lifecycle ======
esp_err_t config_init(void);
esp_err_t config_factory_reset(void);

// ====== Type-Safe Getters (read from NVS) ======
esp_err_t config_get_string(const char* key, char* buf, size_t len);
esp_err_t config_get_int32(const char* key, int32_t* value);
esp_err_t config_get_int16(const char* key, int16_t* value);
esp_err_t config_get_bool(const char* key, bool* value);

// ====== Type-Safe Setters (write to NVS) ======
esp_err_t config_set_string(const char* key, const char* value);
esp_err_t config_set_int32(const char* key, int32_t value);
esp_err_t config_set_int16(const char* key, int16_t value);
esp_err_t config_set_bool(const char* key, bool value);

// ====== Generated Function ======
void config_write_factory_defaults(void);  // Auto-generated from schema

Implementation Characteristics:

Simple NVS Wrappers: Each function ~5-10 lines (minimal overhead)
No JSON Parsing: Direct NVS access, no runtime deserialization
No Validation Logic: Server trusts client (browser does validation)
No Domain Knowledge: Functions never mention WiFi, LEDs, etc.
Type Safety by API: Compiler enforces correct type via function signature

Typical Usage:

// Read configuration
char ssid[33];
config_get_string("wifi_ssid", ssid, sizeof(ssid));

int32_t led_count;
config_get_int32("led_count", &led_count);

// Write configuration
config_set_string("wifi_ssid", "MyNetwork");
config_set_int32("led_count", 120);

Error Handling:

int32_t value;
esp_err_t err = config_get_int32("led_count", &value);

if (err != ESP_OK) {
    ESP_LOGW(TAG, "Failed to read led_count: %s", esp_err_to_name(err));
    value = 60;  // Use default
}

Design Rationale:

No Validation in C: Validation happens in browser (simpler code)
Direct Key Access: Eliminates enum systems, more flexible
Key Duplication Accepted: Key appears in config_schema.json AND C code (This is intentional: explicit is better than implicit for embedded)

Web Interface Design¶

Design Specification: JSON Schema for UI Generation SPEC_CFG_JSON_UI_1

status: approved

tags: web, ui, javascript

links outgoing: REQ_CFG_JSON_10, REQ_CFG_JSON_11

Description: Browser fetches config_schema.json and generates settings form dynamically.

Form Generation Flow:

Browser loads /settings.html
      │
      └──→ JavaScript: fetch('/config_schema.json')
           │
           └──→ Parse schema, create groups
                │
                └──→ For each field:
                     ├─ Create input element (type-specific)
                     ├─ Apply validation attributes (min/max/pattern)
                     ├─ Set label, description
                     └─ Add to corresponding group div

Browser-Side Validation:

function generateFormFromSchema(schema) {
    for (const group of schema.groups) {
        const groupDiv = createGroupDiv(group);

        for (const field of schema.fields) {
            if (field.group === group.id) {
                // Create input based on field type
                const input = createInputElement(field);

                // Apply validation attributes
                if (field.type === 'integer') {
                    input.min = field.min;
                    input.max = field.max;
                    input.step = field.step || 1;
                }

                if (field.type === 'string' || field.type === 'password') {
                    input.minLength = field.minLength;
                    input.maxLength = field.maxLength;
                    input.pattern = field.pattern;
                }

                // Add to form
                groupDiv.appendChild(createFormGroup(field, input));
            }
        }

        document.getElementById('settings').appendChild(groupDiv);
    }
}

Validation Rules:

Field Type	Browser Validation	Server Trust?
string	maxLength, pattern	Yes (no re-validation)
password	minLength, maxLength	Yes
integer	min, max, step	Yes
boolean	HTML5 checkbox	Yes

Design Rationale:

Browser-Only Validation: Simple approach for template (no server-side re-validation)
Self-Updating UI: No need to hardcode form HTML, schema drives generation
Validation Rules as Schema: Constraints visible in one place

Design Specification: Bulk JSON Configuration API SPEC_CFG_JSON_BULK_1

status: approved

tags: api, json, bulk-operations

links outgoing: REQ_CFG_JSON_12, REQ_CFG_JSON_13

links incoming: SPEC_CFG_WEB_FLOW_1, SPEC_CFG_WEB_MAPPING_1

Description: Configuration manager provides bulk JSON operations for efficient configuration management. These functions process all configuration fields in atomic operations.

Design Principle: Bulk JSON API is the primary interface for multi-field configuration operations. Individual field access remains available for specific use cases.

Function 1: Schema Access

/**
 * @brief Get embedded JSON schema for dynamic UI generation
 * @param[out] schema_json Pointer to embedded schema string (no free() needed)
 * @return ESP_OK on success, ESP_ERR_NOT_FOUND if schema not embedded
 */
esp_err_t config_get_schema_json(char **schema_json);

Function 2: Bulk Configuration Read

/**
 * @brief Read all configuration values as structured JSON array
 * @param[out] config_json Allocated JSON string (caller must free())
 * @return ESP_OK on success, ESP_ERR_NO_MEM on allocation failure
 */
esp_err_t config_get_all_as_json(char **config_json);

Implementation Strategy: - Read JSON schema to enumerate all defined fields - For each field, call appropriate config_get_*() function based on schema type - Build JSON array with {key, type, value} objects for all current values - Handle password masking (never expose sensitive fields)

Function 3: Bulk Configuration Write

/**
 * @brief Update configuration from structured JSON array
 * @param[in] config_json JSON array with {key, type, value} objects
 * @return ESP_OK on success, ESP_ERR_INVALID_ARG on validation failure
 */
esp_err_t config_set_all_from_json(const char *config_json);

Implementation Strategy: - Parse input JSON array to extract {key, type, value} objects - For each object, validate key exists in schema and type matches - Call appropriate config_set_*_no_commit() function based on type - Single config_commit() call for atomic update - Return error if any field validation fails

Error Handling: - Unknown key fields: ignored (forward compatibility) - Invalid type values: return ESP_ERR_INVALID_ARG - Type mismatch (type vs schema): return ESP_ERR_INVALID_ARG - Range violations: return ESP_ERR_INVALID_ARG - NVS errors: propagate ESP_ERR_NVS_* codes - Malformed JSON: return ESP_ERR_INVALID_ARG

JSON Format Example:

[
  {
    "key": "wifi_ssid",
    "type": "string",
    "value": "MyNetwork"
  },
  {
    "key": "wifi_pass",
    "type": "string",
    "value": "password123"
  },
  {
    "key": "ap_ssid",
    "type": "string",
    "value": "MyDevice-AP"
  },
  {
    "key": "led_count",
    "type": "integer",
    "value": 50
  },
  {
    "key": "led_bright",
    "type": "integer",
    "value": 128
  },
  {
    "key": "device_name",
    "type": "string",
    "value": "MyDevice"
  }
]

Design Properties: - No hardcoded fields in any client component - Schema-driven completeness (all fields included automatically) - Future-proof (new schema fields work without client changes) - Atomic updates (all changes committed together) - Type safety (schema validates types before NVS storage)

Primary Use Cases: - Web server HTTP endpoints: Use bulk APIs for GET/POST operations - Factory reset: Load default values with config_set_all_from_json() - Configuration export/import: System backup and restore - CLI commands: Batch configuration from command line - Remote management: Configuration updates from network protocols

Best Practices & Development Guide¶

Design Specification: Adding New Configuration Fields SPEC_CFG_JSON_EXTEND_1

status: approved

tags: development, guide, extensibility

links outgoing: REQ_CFG_JSON_1, REQ_CFG_JSON_13

Description: Simple process for adding new configuration fields to schema.

Step-by-Step Guide:

1. Define in config_schema.json:

{
  "key": "my_setting",
  "type": "integer",
  "label": "My Custom Setting",
  "description": "This is what my setting does",
  "default": 100,
  "min": 1,
  "max": 1000,
  "step": 10,
  "group": "application",
  "order": 1
}

2. Use in Application Code:

#include "config_manager.h"

int32_t my_setting;
esp_err_t err = config_get_int32("my_setting", &my_setting);

if (err != ESP_OK) {
    ESP_LOGW(TAG, "Failed to read my_setting: %s", esp_err_to_name(err));
    my_setting = 100;  // Fallback to default
}

// Use my_setting...

3. Web UI Auto-Updates:

Reload settings page
New field appears automatically with validation rules
Label and description shown from schema

Key Naming Rules:

Use snake_case (matches C naming conventions)
≤15 characters (NVS key length limit)
Avoid special characters except underscore
Make names descriptive (“led_count” better than “lc”)

Design Specification: Type Safety Without Code Generation SPEC_CFG_JSON_TYPESAFETY_1

status: approved

tags: type-safety, best-practices

links outgoing: REQ_CFG_JSON_7, REQ_CFG_JSON_14

Description: Achieving type safety through API design and optional validation rather than mandatory code generation.

Type Safety Mechanisms:

API Signature Type Safety:

// Compiler enforces types at call site
int32_t count;
config_get_int32("led_count", &count);  // ✅ Correct: matches schema type

char* str;
config_get_int32("wifi_ssid", (int32_t*)str);  // ❌ Logical error (caught by developer testing)

Schema Documents Correct Type:

{"key": "led_count", "type": "integer"}   → Use config_get_int32()
{"key": "wifi_ssid", "type": "string"}    → Use config_get_string()

Optional: Static Validator Script (Nice-to-Have):

# Pre-build validation (not required)
python3 tools/validate_config_schema.py

# Finds type mismatches in code:
# ERROR: src/main.c:42 - config_get_int32("wifi_ssid"):
#        schema says type="string", not integer

When Type Mismatches Happen:

❌ If schema says “string” but code calls config_get_int32(): - Result: Reads binary garbage as integer - Discovery: Runtime error during testing (type mismatch obvious) - Recovery: Trivial fix (change one line in C code)

For Templates, This is Acceptable:

Small number of config fields (5-10 typically)
Type errors obvious after one test run
No runtime overhead of validation
Code remains simple and understandable

When Additional Safety is Needed:

Projects with 20+ config fields
Pre-commit validator script (optional)
Or: Use code generation approach (separate branch/option)

Design Philosophy:

Explicit > Implicit: Keys appear in both JSON and C code (obvious when they match)
Simple > Magic: No hidden code generation unless chosen
Learnable > Complex: Beginners can understand entire system quickly

Traceability¶

ID	Title	Status
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
REQ_CFG_JSON_10	Web Interface Integration Support	approved
REQ_CFG_JSON_11	NVS Error Graceful Handling	implemented
REQ_CFG_JSON_12	Configuration Initialization on Boot	implemented
REQ_CFG_JSON_13	Simple Process to Add Configuration Fields	implemented
REQ_CFG_JSON_14	Type Safety via Optional Static Validation	implemented
REQ_CFG_JSON_15	Configuration Schema Versioning and Migration	open
REQ_CFG_JSON_2	Parameter Grouping for UI Organization	implemented
REQ_CFG_JSON_3	Parameter Type System	implemented
REQ_CFG_JSON_4	Build-Time Factory Defaults Generation	implemented
REQ_CFG_JSON_5	No Runtime JSON Parsing in C Code	implemented
REQ_CFG_JSON_6	Key-Based NVS Storage	implemented
REQ_CFG_JSON_7	Type-Safe Configuration API	implemented
REQ_CFG_JSON_8	Persistent Configuration Storage	implemented
REQ_CFG_JSON_9	Factory Reset Capability	implemented
REQ_DEV_DOC_1	Supporting Documentation Traceability	implemented
REQ_DEV_ENV_1	Supported Development Environments	implemented
REQ_DEV_GUIDE_DEBUG_1	Debugging Guide Content	implemented
REQ_DEV_GUIDE_FLASH_1	Web Flasher Guide Content	implemented
REQ_DEV_GUIDE_MODES_1	Switching Dev Modes Guide Content	implemented
REQ_DEV_GUIDE_QEMU_1	QEMU Emulator Guide Content	implemented
REQ_DEV_LIMITS_1	Known Limitations Documentation	implemented
REQ_DEV_OV_HW_1	Hardware Specifications Content	implemented
REQ_DEV_OV_INDEX_1	Overview Index Content	implemented
REQ_DEV_OV_QS_1	Quick Start Content	implemented
REQ_DEV_README_1	README Content Scope	implemented
REQ_DSP_1	Hardware Platform	approved
REQ_DSP_2	Configuration Integration	approved
REQ_DSP_3	Core Visualization Concept	approved
REQ_DSP_4	Below Minimum Distance Warning	approved
REQ_DSP_5	Out of Range Display	approved
REQ_LED_1	WS2812 LED Strip Support	approved
REQ_LED_2	Individual Pixel Control	approved
REQ_LED_3	Configurable LED Count	approved
REQ_LED_4	Accurate Color Display	approved
REQ_LED_5	LED State Read API	approved
REQ_NETIF_TUNNEL_1	QEMU UART Network Bridge	approved
REQ_NETIF_TUNNEL_2	Packet Encapsulation	approved
REQ_NETIF_TUNNEL_3	Host-Side Bridge Script	approved
REQ_NETIF_TUNNEL_4	DHCP Client Support	approved
REQ_NETIF_TUNNEL_5	Conditional Compilation	approved
REQ_NETIF_TUNNEL_DOC_1	Emulation Setup Documentation	approved
REQ_NETIF_TUNNEL_NF_1	Tunnel Throughput	approved
REQ_NETIF_TUNNEL_NF_2	Packet Loss Handling	approved
REQ_SNS_1	Component Initialization	approved
REQ_SNS_10	Timing and Performance	approved
REQ_SNS_11	Accuracy and Calibration	approved
REQ_SNS_12	Timeout Error Handling	approved
REQ_SNS_13	Range Validation	approved
REQ_SNS_14	Queue Overflow Management	approved
REQ_SNS_2	Trigger Pulse Generation	approved
REQ_SNS_3	Real-Time Timestamp Capture	approved
REQ_SNS_4	Measurement Processing	approved
REQ_SNS_5	Blocking API Access	approved
REQ_SNS_6	Task Lifecycle Management	approved
REQ_SNS_7	Health Monitoring	approved
REQ_SNS_8	Real-Time ISR Constraints	approved
REQ_SNS_9	Memory Resource Limits	approved
REQ_STARTUP_1	LED Controller Initialization	approved
REQ_STARTUP_2	Visual Boot Sequence	approved
REQ_STARTUP_3	Timing Performance	approved
REQ_SYS_1	Garage Parking Assistance System	approved
REQ_SYS_ARCH_1	Component-based Architecture	approved
REQ_SYS_CFG_1	Non-volatile Configuration Storage	approved
REQ_SYS_HW_1	ESP32 Hardware Platform	approved
REQ_SYS_NET_1	WiFi Connectivity	approved
REQ_SYS_PERF_1	Memory Management	approved
REQ_SYS_REL_1	Error Handling and Recovery	approved
REQ_SYS_SEC_1	HTTPS Support	open
REQ_SYS_SIM_1	Emulator Support	approved
REQ_SYS_SIM_2	Emulator Network Connectivity	approved
REQ_SYS_TIME_1	System Time and NTP Support	open
REQ_SYS_WEB_1	Web-based Configuration	approved
REQ_WEB_1	Real-time Status Display	approved
REQ_WEB_2	Configuration Interface	approved
REQ_WEB_3	WiFi Setup Interface	approved
REQ_WEB_4	Web Interface Navigation	approved
REQ_WEB_5	HTTP Server Concurrency	approved
REQ_WEB_CONF_1	Configuration REST API	approved
REQ_WEB_LED_1	LED State API Endpoint	approved
REQ_WEB_NF_1	Web UI Responsiveness	approved
REQ_WEB_NF_2	Mobile-First Design	approved
REQ_WEB_SCHEMA_1	Schema-Driven Configuration Form	approved
SPEC_ARCH_BUILD_1	ESP-IDF CMake Integration	approved
SPEC_ARCH_CERT_1	Certificate Handler Component Design	draft
SPEC_ARCH_CODESPACES_1	GitHub Codespaces Integration	approved
SPEC_ARCH_COMM_1	Component Communication Pattern	approved
SPEC_ARCH_CONFIG_1	Configuration Manager Component Design	approved
SPEC_ARCH_CONFIG_FLOW_1	Configuration Data Flow	approved
SPEC_ARCH_ERROR_RECOVERY_1	Error Recovery and Reset Strategy	approved
SPEC_ARCH_FLASH_1	Flash Memory Configuration	approved
SPEC_ARCH_HTTP_1	HTTP Server Architecture Details	approved
SPEC_ARCH_LAYERS_1	ESP32 Distance Sensor Layered Architecture	approved
SPEC_ARCH_LOGGING_1	Logging and Diagnostics Strategy	approved
SPEC_ARCH_MEMORY_1	Memory Management Strategy	approved
SPEC_ARCH_NETIF_1	Network Tunnel Component Design	approved
SPEC_ARCH_PERF_1	System Performance Requirements	approved
SPEC_ARCH_QEMU_1	QEMU Hardware Abstraction	approved
SPEC_ARCH_QEMU_BUILD_1	QEMU Component Selection	approved
SPEC_ARCH_TASKS_1	FreeRTOS Task Organization	approved
SPEC_ARCH_WEB_1	Web Server Component Design	approved
SPEC_ARCH_WIFI_1	WiFi Manager Design Details	approved
SPEC_CFG_JSON_API_1	Type-Safe Configuration API	approved
SPEC_CFG_JSON_ARCH_1	JSON Schema-Driven Architecture	draft
SPEC_CFG_JSON_BULK_1	Bulk JSON Configuration API	approved
SPEC_CFG_JSON_CODEGEN_1	Factory Reset via Bulk JSON Update	approved
SPEC_CFG_JSON_EXTEND_1	Adding New Configuration Fields	approved
SPEC_CFG_JSON_SCHEMA_1	Configuration Schema Structure	approved
SPEC_CFG_JSON_SOURCE_1	JSON Schema as Single Source of Truth	approved
SPEC_CFG_JSON_STORAGE_1	NVS Storage Format	approved
SPEC_CFG_JSON_TYPESAFETY_1	Type Safety Without Code Generation	approved
SPEC_CFG_JSON_UI_1	JSON Schema for UI Generation	approved
SPEC_CFG_WEB_ARCH_1	Configuration Webpage Architecture	implemented
SPEC_CFG_WEB_COUNTDOWN_1	Device Reset Countdown Interface	implemented
SPEC_CFG_WEB_ERROR_1	Error Handling and User Feedback	implemented
SPEC_CFG_WEB_FLOW_1	Configuration Data Flow	implemented
SPEC_CFG_WEB_FORM_1	Dynamic Form Generation from Schema	implemented
SPEC_CFG_WEB_INIT_1	Complete Page Initialization Flow	implemented
SPEC_CFG_WEB_MAPPING_1	JSON Array to Form Field Mapping	implemented
SPEC_CFG_WEB_STATE_1	UI State Management	implemented
SPEC_DEV_ENV_OPTIONS	Supported Development Environments — Options	implemented
SPEC_DEV_ENV_USAGE	Supported Development Environments — Setup Steps	implemented
SPEC_DEV_GUIDE_DEBUG_FEATURES	Debugging Guide — Debugging Features	implemented
SPEC_DEV_GUIDE_DEBUG_START	Debugging Guide — Quick Start in QEMU	implemented
SPEC_DEV_GUIDE_FLASH_OVERVIEW	Web Flasher Guide — Overview and Browser Requirements	implemented
SPEC_DEV_GUIDE_FLASH_STEPS	Web Flasher Guide — Flash Procedure	implemented
SPEC_DEV_GUIDE_MODES_DIFF	Dev Modes Guide — What Changes Between Modes	implemented
SPEC_DEV_GUIDE_MODES_HOW	Dev Modes Guide — How to Switch	implemented
SPEC_DEV_GUIDE_QEMU_START	QEMU Guide — Starting QEMU	implemented
SPEC_DEV_GUIDE_QEMU_STOP	QEMU Guide — Stopping QEMU	implemented
SPEC_DEV_GUIDE_QEMU_WEB	QEMU Guide — Accessing the Web Interface	implemented
SPEC_DEV_LIMITS_STRUCTURE	Known Limitations File Structure and Process	implemented
SPEC_DEV_OV_HW_COMPONENTS	Hardware Components Listing	implemented
SPEC_DEV_OV_HW_PINS	Hardware Pin Assignment Table	implemented
SPEC_DEV_OV_INDEX_NAV	Overview Index — Navigation Section	implemented
SPEC_DEV_OV_INDEX_WHAT	Overview Index — Project Description	implemented
SPEC_DEV_OV_INDEX_WHO	Overview Index — Audience Section	implemented
SPEC_DEV_OV_QS_HW	Quick Start — Hardware Path	implemented
SPEC_DEV_OV_QS_QEMU	Quick Start — QEMU Path	implemented
SPEC_DEV_README_INTRO	README Introduction and Project Link	implemented
SPEC_DEV_README_META	README Metadata Section	implemented
SPEC_DSP_ALGO_1	Distance-to-Visual Mapping Algorithm	approved
SPEC_DSP_ALGO_3	Embedded Arithmetic Architecture	approved
SPEC_DSP_API_1	Public Display API	approved
SPEC_DSP_ARCH_1	Task-Based Architecture	approved
SPEC_DSP_ARCH_2	Configuration Integration	approved
SPEC_DSP_OVERVIEW_1	WS2812 Hardware Integration	approved
SPEC_LED_API_1	Pixel-Level Control API	approved
SPEC_LED_API_2	Batch Operations API	approved
SPEC_LED_API_3	LED State Read API	approved
SPEC_LED_ARCH_1	RMT Peripheral Hardware Abstraction	approved
SPEC_LED_ARCH_2	RAM Buffer Architecture	approved
SPEC_LED_DATA_1	Color Representation and Conversion	approved
SPEC_LED_ERR_1	Error Handling and Validation	approved
SPEC_LED_MEM_1	Dynamic Memory Management	approved
SPEC_LED_SIM_1	LED Controller Simulator	approved
SPEC_LED_TIMING_1	WS2812 Timing Specification	approved
SPEC_NETIF_UART_ARCH_1	UART Tunnel Component Architecture	implemented
SPEC_NETIF_UART_BRIDGE_1	Host-Side Serial-TUN Bridge Script	implemented
SPEC_NETIF_UART_COND_1	Conditional Compilation — QEMU-Only Build Guard	implemented
SPEC_NETIF_UART_DHCP_1	IP Configuration and DHCP Client Integration	implemented
SPEC_NETIF_UART_DOC_1	Emulation Setup Documentation	implemented
SPEC_NETIF_UART_PERF_1	Performance Characteristics and Known Limitations	implemented
SPEC_NETIF_UART_PROTO_1	UART Wire Protocol — Length-Prefix Framing	implemented
SPEC_SNS_ALGO_1	Distance Calculation Algorithm	approved
SPEC_SNS_ALGO_2	EMA Smoothing Filter Design	approved
SPEC_SNS_API_1	Public API Design	approved
SPEC_SNS_ARCH_1	Dual-Queue Real-Time Architecture	approved
SPEC_SNS_ARCH_2	GPIO Interface Design	approved
SPEC_SNS_ERR_1	Error Handling Design	approved
SPEC_SNS_ISR_1	Interrupt Service Routine Design	approved
SPEC_SNS_SIM_1	Distance Sensor Simulator Design	approved
SPEC_SNS_TASK_1	Sensor Task Design	approved
SPEC_STARTUP_1	LED Controller Dependency Design	approved
SPEC_STARTUP_2	Sequential LED Pattern Algorithm	approved
SPEC_STARTUP_3	Startup Integration and Cleanup	approved
SPEC_STARTUP_4	Component Architecture	approved
SPEC_WEB_ARCH_1	Web Server Architecture	approved
SPEC_WEB_CAPTIVE_1	Captive Portal Design	approved
SPEC_WEB_CONFIG_1	HTTP Server Configuration	approved
SPEC_WEB_EXTEND_1	Extension Guide for Web Pages	approved
SPEC_WEB_INTEGRATION_CFG_1	Config Manager Integration Pattern	approved
SPEC_WEB_INTEGRATION_WIFI_1	WiFi Manager Integration Pattern	approved
SPEC_WEB_NF_1	Mobile-First Responsive Design	approved
SPEC_WEB_REST_CFG_1	Configuration API Endpoints	approved
SPEC_WEB_REST_HEALTH_1	System Health API Endpoint	approved
SPEC_WEB_REST_LED_1	LED State API Endpoint	approved
SPEC_WEB_REST_WIFI_1	WiFi Management REST API Endpoints	approved
SPEC_WEB_ROUTES_1	URI Routing Table	approved
SPEC_WEB_SECURITY_1	CORS Configuration	approved
SPEC_WEB_STATIC_1	Static File Embedding Strategy	approved
SPEC_WEB_TEST_1	Web Server Testing Strategy	approved
US_DEV_1	Modular Firmware Extensibility	implemented
US_DEV_2	Traceable Supporting Documentation	implemented
US_DISPLAY_1	Visual Distance Feedback for Parking	approved
US_RELIABLE_1	Appliance Reliability - Just Works on Power	approved
US_SETUP_1	Device Setup via Web Interface	approved