System Requirements

This document contains high-level system requirements for the ESP32 Template project.

Requirement: ESP32 Hardware Platform REQ_SYS_HW_1

status: approved tags: hardware, platform priority: mandatory links incoming: SPEC_ARCH_MEMORY_1, SPEC_ARCH_BUILD_1, SPEC_ARCH_FLASH_1

Description: The system SHALL operate on ESP32 microcontroller with 4MB flash memory. Rationale: ESP32 provides WiFi connectivity, sufficient processing power, and adequate flash memory for IoT applications. Acceptance Criteria: AC-1: System boots successfully on ESP32 WROOM-32 or compatible modules AC-2: Flash usage does not exceed 90% of available 4MB AC-3: System operates within ESP32 memory constraints (DRAM/IRAM)

Requirement: WiFi Connectivity REQ_SYS_NET_1

status: approved tags: network, wifi priority: mandatory links incoming: REQ_NETIF_TUNNEL_4, REQ_SYS_WEB_1, REQ_SYS_SIM_2, REQ_WEB_3

Description: The system SHALL provide WiFi connectivity in both Access Point (AP) and Station (STA) modes. Rationale: Enables web interface access and network configuration flexibility. Acceptance Criteria: AC-1: System creates WiFi Access Point for initial configuration AC-2: System connects to existing WiFi networks as station AC-3: Automatic fallback to AP mode if STA connection fails

Requirement: Web-based Configuration REQ_SYS_WEB_1

status: approved tags: web, configuration priority: mandatory links outgoing: REQ_SYS_NET_1 links incoming: REQ_CFG_JSON_10, REQ_WEB_1, REQ_WEB_2, REQ_WEB_CONF_1, REQ_WEB_SCHEMA_1, REQ_WEB_4, REQ_WEB_5, SPEC_ARCH_WEB_1, SPEC_ARCH_CERT_1, SPEC_ARCH_WIFI_1, SPEC_ARCH_HTTP_1

Description: The system SHALL provide web interface for configuration and monitoring. Rationale: User-friendly interface for system setup and operation without firmware recompilation. Acceptance Criteria: AC-1: Web interface accessible via HTTP AC-2: Configuration changes applied without firmware recompilation AC-3: Real-time monitoring of system status

Requirement: Non-volatile Configuration Storage REQ_SYS_CFG_1

status: approved tags: storage, nvs, configuration priority: mandatory links incoming: REQ_CFG_JSON_1, REQ_CFG_JSON_4, REQ_CFG_JSON_6, REQ_CFG_JSON_9, REQ_WEB_CONF_1, SPEC_ARCH_CONFIG_1, SPEC_ARCH_CONFIG_FLOW_1

Description: The system SHALL persist configuration settings across power cycles using ESP32 NVS (Non-Volatile Storage). Rationale: Maintains user settings and system configuration permanently. Acceptance Criteria: AC-1: Configuration survives device reset and power loss AC-2: Factory reset capability restores default settings AC-3: Configuration corruption detection and recovery

Requirement: Component-based Architecture REQ_SYS_ARCH_1

status: approved tags: architecture, modularity priority: mandatory links incoming: SPEC_ARCH_LAYERS_1, SPEC_ARCH_COMM_1, SPEC_ARCH_TASKS_1

Description: The system SHALL implement modular component-based architecture following ESP-IDF conventions. Rationale: Enables maintainability, testability, and reusability. Acceptance Criteria: AC-1: Components provide well-defined APIs AC-2: Components are independently testable AC-3: Main application coordinates components without tight coupling

Requirement: Error Handling and Recovery REQ_SYS_REL_1

status: approved tags: reliability, error-handling priority: mandatory links incoming: REQ_CFG_JSON_11, SPEC_ARCH_LOGGING_1, SPEC_ARCH_ERROR_RECOVERY_1

Description: The system SHALL handle errors gracefully and attempt recovery where possible. Rationale: Ensures system reliability and user experience. Acceptance Criteria: AC-1: Component timeouts handled without system crash AC-2: Network connection failures trigger automatic retry AC-3: System logs errors for diagnostics AC-4: Watchdog timer prevents system hang

Requirement: Memory Management REQ_SYS_PERF_1

status: approved tags: performance, memory priority: mandatory links incoming: SPEC_ARCH_PERF_1

Description: The system SHALL manage memory efficiently within ESP32 constraints. Rationale: Prevents memory leaks and ensures stable operation. Acceptance Criteria: AC-1: Heap usage monitored and bounded AC-2: No memory leaks during normal operation AC-3: Stack overflow protection for all tasks AC-4: Dynamic allocation minimized in time-critical paths

Requirement: Emulator Support REQ_SYS_SIM_1

status: approved tags: emulator, qemu, testing priority: mandatory links incoming: REQ_NETIF_TUNNEL_1, REQ_NETIF_TUNNEL_DOC_1, REQ_SYS_SIM_2, SPEC_ARCH_NETIF_1, SPEC_ARCH_QEMU_1, SPEC_ARCH_QEMU_BUILD_1, SPEC_ARCH_CODESPACES_1

Description: The system SHALL support build-time selectable emulator mode (QEMU) that replaces hardware-specific modules with simulator implementations while preserving public APIs. Rationale: Enables development and testing without physical hardware, improves reproducibility and CI test coverage. Acceptance Criteria: AC-1: Kconfig option CONFIG_TARGET_EMULATOR enables emulator builds AC-2: Simulator implementations selected by CMake without requiring code changes AC-3: Simulator components implement complete public API of hardware counterparts AC-4: Emulator build runnable under QEMU with console output AC-5: Documentation provides build/run verification steps

Requirement: Emulator Network Connectivity REQ_SYS_SIM_2

status: approved tags: emulator, qemu, network, development priority: optional links outgoing: REQ_SYS_SIM_1, REQ_SYS_NET_1

Description: The system SHOULD provide network connectivity when running in QEMU emulation to enable testing of network-dependent features. Rationale: Enables development and testing of web interfaces, WiFi configuration, and network protocols without physical ESP32 hardware. Acceptance Criteria: AC-1: UART-based network tunnel bridges QEMU to host network stack AC-2: Web interface accessible from host machine during emulation AC-3: DHCP client obtains IP address in emulation mode AC-4: Network features testable without hardware WiFi module AC-5: Documentation describes emulation network setup and limitations

Future Enhancements

Requirement: HTTPS Support REQ_SYS_SEC_1

status: open tags: security, https, future priority: optional links incoming: API_COMP_CERT_HANDLER, API_FUNC_CERT_HANDLER_INIT, API_FUNC_CERT_HANDLER_GET_SERVER_CERT, API_FUNC_CERT_HANDLER_GET_SERVER_KEY, API_FUNC_CERT_HANDLER_GET_CA_CERT, API_FUNC_CERT_HANDLER_GET_INFO

Description: The system MAY support HTTPS for encrypted web interface communication. Rationale: Encrypted communication protects sensitive data (WiFi passwords, configuration) from network eavesdropping. However, embedded certificate management is complex. Known Challenges: ESP32 flash constraints for certificate storage Self-signed certificates trigger browser warnings OTA updates complicate certificate lifecycle QEMU emulation does not support HTTPS testing Previous implementation attempts encountered stability issues Acceptance Criteria (if implemented): AC-1: Web server supports both HTTP and HTTPS ports AC-2: Self-signed certificate generated at build time or first boot AC-3: Certificate embedded in flash or stored in NVS AC-4: Browser security warnings documented for users AC-5: Certificate renewal process defined for production deployments Note: This requirement is intentionally marked “open” due to complexity. For many embedded use cases, physical access security and network isolation provide sufficient protection. Production deployments requiring HTTPS should evaluate alternatives (VPN, mTLS, secure network).

Requirement: System Time and NTP Support REQ_SYS_TIME_1

status: open tags: time, ntp, future priority: optional

Description: The system MAY support network time synchronization via NTP for accurate timestamps. Rationale: Accurate system time enables timestamped logs, scheduled tasks, and time-based security features. Many IoT applications require synchronized time. Acceptance Criteria (if implemented): AC-1: NTP client synchronizes with configurable NTP server AC-2: Timezone configuration via web interface AC-3: System time persists across reboots (RTC or NVS) AC-4: Time synchronization status visible in web interface AC-5: Fallback behavior defined if NTP unavailable Note: This requirement is marked “open” as template focuses on core functionality. Time synchronization can be added when application requires timestamped events or scheduling.

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_NETIF_TUNNEL	Network Tunnel	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_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_STRUCT_NETIF_TUNNEL_CONFIG	netif_uart_tunnel_config_t	implemented
REQ_CFG_JSON_1	JSON Schema as Configuration Source of Truth	draft	config; schema; architecture
REQ_CFG_JSON_10	Web Interface Integration Support	approved	config; integration
REQ_CFG_JSON_11	NVS Error Graceful Handling	draft	config; error-handling; reliability
REQ_CFG_JSON_12	Configuration Initialization on Boot	draft	config; boot
REQ_CFG_JSON_13	Simple Process to Add Configuration Fields	draft	config; extensibility; developer-experience
REQ_CFG_JSON_14	Type Safety via Optional Static Validation	draft	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	draft	config; ui; schema
REQ_CFG_JSON_3	Parameter Type System	draft	config; types
REQ_CFG_JSON_4	Build-Time Factory Defaults Generation	draft	config; build; code-generation
REQ_CFG_JSON_5	No Runtime JSON Parsing in C Code	draft	config; performance; memory
REQ_CFG_JSON_6	Key-Based NVS Storage	draft	config; storage; nvs
REQ_CFG_JSON_7	Type-Safe Configuration API	draft	config; api; type-safety
REQ_CFG_JSON_8	Persistent Configuration Storage	draft	config; storage; nvs
REQ_CFG_JSON_9	Factory Reset Capability	draft	config; reset
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_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_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 Template 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	open	frontend; javascript; ui
SPEC_CFG_WEB_COUNTDOWN_1	Device Reset Countdown Interface	open	ui; countdown; reset
SPEC_CFG_WEB_ERROR_1	Error Handling and User Feedback	open	error-handling; feedback
SPEC_CFG_WEB_FLOW_1	Configuration Data Flow	open	data-flow; json; api
SPEC_CFG_WEB_FORM_1	Dynamic Form Generation from Schema	open	form-generation; schema; javascript
SPEC_CFG_WEB_INIT_1	Complete Page Initialization Flow	open	initialization; lifecycle
SPEC_CFG_WEB_MAPPING_1	JSON Array to Form Field Mapping	open	data-mapping; json; form
SPEC_CFG_WEB_STATE_1	UI State Management	open	ui-state; javascript
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_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_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

REQ_SYS_HW_1