Web Server Requirements

This document specifies component-level requirements for the web server functionality, enabling user interface, configuration, and WiFi setup capabilities.

Component Overview

The web server component provides HTTP-based user interface and configuration capabilities. These requirements refine the high-level system requirement Web-based Configuration (REQ_SYS_WEB_1).

Functional Requirements

Requirement: Real-time Status Display REQ_WEB_1

status: approved tags: web, ui, monitoring priority: mandatory links outgoing: REQ_SYS_WEB_1 links incoming: REQ_WEB_NF_1, REQ_WEB_NF_2, SPEC_WEB_ARCH_1, SPEC_WEB_STATIC_1, SPEC_WEB_REST_HEALTH_1

Description: The system SHALL provide a web page that displays current system status with real-time updates for user monitoring. Rationale: Users need to monitor the device’s operation remotely via web interface without requiring physical access. Acceptance Criteria: AC-1: Main page SHALL display current system status AC-2: Status values SHALL update with reasonable responsiveness AC-3: Page SHALL indicate system state (normal, error, warning) AC-4: Page SHALL be accessible via web browser on mobile and desktop devices

Requirement: Configuration Interface REQ_WEB_2

status: approved tags: web, ui, configuration priority: mandatory links outgoing: REQ_SYS_WEB_1, REQ_CFG_JSON_7 links incoming: REQ_WEB_NF_1, REQ_WEB_NF_2, SPEC_WEB_ARCH_1, SPEC_WEB_STATIC_1

Description: The system SHALL provide a web page for configuring device parameters as defined in the configuration management requirements. Rationale: Users need to adjust device settings remotely without firmware recompilation or physical access. Acceptance Criteria: AC-1: Settings page SHALL display all user-configurable parameters AC-2: Settings page SHALL validate user input ranges before submission AC-3: Settings page SHALL provide immediate feedback on invalid inputs AC-4: Settings page SHALL confirm successful parameter updates AC-5: Settings page SHALL handle configuration save errors gracefully

Requirement: WiFi Setup Interface REQ_WEB_3

status: approved tags: web, wifi, network priority: mandatory links outgoing: REQ_SYS_NET_1 links incoming: REQ_WEB_NF_2, SPEC_WEB_ARCH_1, SPEC_WEB_STATIC_1, SPEC_WEB_REST_WIFI_1, SPEC_WEB_INTEGRATION_WIFI_1, SPEC_WEB_CAPTIVE_1

Description: The system SHALL provide a captive portal WiFi setup page for initial network configuration. Rationale: Users need an intuitive method to configure WiFi credentials without serial console access or hardcoded credentials. Acceptance Criteria: AC-1: Device SHALL start in AP mode when WiFi credentials are not configured AC-2: WiFi setup page SHALL display available WiFi networks (SSID scan) AC-3: WiFi setup page SHALL accept SSID and password input AC-4: WiFi credentials SHALL be saved to NVS and validated on next boot AC-5: WiFi setup page SHALL provide feedback on save success/failure AC-6: Device SHALL switch to STA mode after successful WiFi configuration on next boot

Requirement: Configuration REST API REQ_WEB_CONF_1

status: approved tags: web, api, config priority: mandatory links outgoing: REQ_SYS_WEB_1, REQ_SYS_CFG_1 links incoming: REQ_WEB_SCHEMA_1, SPEC_CFG_WEB_ARCH_1, SPEC_WEB_ARCH_1, SPEC_WEB_REST_CFG_1, SPEC_WEB_INTEGRATION_CFG_1

Description: The web server SHALL provide REST API endpoints for device configuration management. Rationale: Web interface needs standardized API to read and modify device configuration values stored in NVS. Acceptance Criteria: AC-1: GET /api/config SHALL return all current configuration values as JSON AC-2: POST /api/config SHALL accept configuration updates as JSON payload AC-3: POST /api/config/reset SHALL trigger factory reset of configuration AC-4: API SHALL integrate with configuration manager component AC-5: API SHALL return appropriate HTTP status codes (200 OK, 400 Bad Request, 500 Internal Server Error) AC-6: Configuration changes SHALL be persisted to NVS immediately AC-7: Device SHALL restart after configuration changes for consistency

Requirement: Schema-Driven Configuration Form REQ_WEB_SCHEMA_1

status: approved tags: web, ui, config priority: optional links outgoing: REQ_WEB_CONF_1, REQ_SYS_WEB_1 links incoming: SPEC_WEB_REST_CFG_1

Description: The web interface SHOULD dynamically generate configuration forms from schema definition. Rationale: Dynamic generation eliminates manual HTML maintenance and ensures UI stays in sync with configuration structure. Acceptance Criteria: AC-1: Web server SHALL serve configuration schema as static file (e.g., /config_schema.json) AC-2: Browser JavaScript SHALL fetch schema and generate form fields dynamically AC-3: Form fields SHALL match parameter types from schema (text, password, number, checkbox) AC-4: Browser SHALL validate inputs based on schema constraints before submission AC-5: Invalid inputs SHALL display clear error messages to user

Requirement: Web Interface Navigation REQ_WEB_4

status: approved tags: web, ui, navigation priority: mandatory links outgoing: REQ_SYS_WEB_1 links incoming: SPEC_WEB_ROUTES_1, SPEC_WEB_EXTEND_1

Description: The system SHALL provide navigation between multiple web pages (status, settings, WiFi setup). Rationale: Users need to access different functionality areas without memorizing URLs. Acceptance Criteria: AC-1: All pages SHALL include navigation menu or links AC-2: Navigation SHALL clearly indicate current page AC-3: Navigation SHALL be accessible on mobile devices AC-4: Page URLs SHALL be intuitive and RESTful (e.g., /, /settings, /wifi)

Requirement: HTTP Server Concurrency REQ_WEB_5

status: approved tags: web, performance priority: mandatory links outgoing: REQ_SYS_WEB_1 links incoming: SPEC_WEB_ROUTES_1, SPEC_WEB_CONFIG_1, SPEC_WEB_SECURITY_1, SPEC_WEB_TEST_1

Description: The web server SHALL handle multiple simultaneous HTTP connections without blocking. Rationale: Multiple users or browser tabs may access the device simultaneously. Acceptance Criteria: AC-1: Web server SHALL support at least 4 concurrent connections AC-2: Server SHALL respond to new connections within 2 seconds under load AC-3: Server SHALL not crash or hang under concurrent access AC-4: Connection handling SHALL not interfere with real-time system operation

Non-Functional Requirements

Requirement: Web UI Responsiveness REQ_WEB_NF_1

status: approved tags: web, performance, ux priority: optional links outgoing: REQ_WEB_1, REQ_WEB_2 links incoming: SPEC_WEB_STATIC_1

Description: Web pages SHOULD load and render within 3 seconds on typical mobile/desktop browsers. Rationale: Responsive UI improves user experience and reduces perceived latency. Acceptance Criteria: AC-1: Initial page load SHALL complete within 3 seconds (excluding network latency) AC-2: Navigation between pages SHALL feel instantaneous (<500ms) AC-3: AJAX updates SHALL not cause page flickering or layout shifts

Requirement: Mobile-First Design REQ_WEB_NF_2

status: approved tags: web, ui, mobile priority: optional links outgoing: REQ_WEB_1, REQ_WEB_2, REQ_WEB_3

Description: Web interface SHOULD be optimized for mobile devices with responsive design. Rationale: Many users will access the device from smartphones in the field. Acceptance Criteria: AC-1: UI SHALL be usable on screens as small as 320px width AC-2: Touch targets SHALL be at least 44x44px for mobile usability AC-3: Text SHALL be readable without zooming on mobile devices

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_WEB_1