Network Interface Tunnel Requirements¶
This document specifies component-level requirements for the UART-based network tunnel driver, enabling QEMU emulation with external network connectivity.
Component Overview¶
The network interface tunnel component provides a bridge between QEMU’s simulated UART and the host’s network stack, enabling network-dependent features to be tested in emulation. These requirements refine the high-level system requirement Emulator Support (REQ_SYS_SIM_1).
Functional Requirements¶
Description: The system SHALL provide a custom network interface driver that bridges ESP32’s UART to the host network stack when running in QEMU emulation. Rationale: QEMU does not natively support ESP32 WiFi emulation. A UART tunnel enables network connectivity for testing web server and WiFi-dependent features. Acceptance Criteria:
|
Description: The tunnel driver SHALL encapsulate Ethernet frames for transmission over UART with appropriate framing and error detection. Rationale: UART is a byte-stream transport; Ethernet frame boundaries must be preserved. Acceptance Criteria:
|
Description: The project SHALL provide a Python script that bridges QEMU’s UART to the host’s TAP network interface. Rationale: QEMU UART output must be forwarded to host network stack for external connectivity. Acceptance Criteria:
|
Description: The tunnel network interface SHALL support DHCP client operation to obtain IP address from host network. Rationale: Automatic IP configuration simplifies emulation setup and mirrors real WiFi behavior. Acceptance Criteria:
|
Description: The tunnel driver SHALL be conditionally compiled only when building for QEMU target, with zero overhead on real hardware builds. Rationale: Real hardware uses WiFi driver; tunnel driver is emulation-specific. Acceptance Criteria:
|
Performance Requirements¶
Description: The UART tunnel SHOULD support sufficient throughput for web interface testing (minimum 100 KB/s). Rationale: Web page loads and AJAX updates require reasonable bandwidth. Acceptance Criteria:
|
Description: The tunnel driver SHOULD handle UART packet loss gracefully without crashing. Rationale: QEMU’s UART emulation may occasionally drop bytes under high load. Acceptance Criteria:
|
Documentation Requirements¶
Description: The project SHALL provide clear documentation for setting up and using QEMU emulation with network tunnel. Rationale: Developers need step-by-step instructions to use emulation features. Acceptance Criteria:
|
Traceability¶
All traceability is automatically generated by Sphinx-Needs based on the :links: attributes in each requirement.
ID |
Title |
Status |
Tags |
|---|---|---|---|
Certificate Handler |
implemented |
||
Config Manager |
implemented |
||
Network Tunnel |
implemented |
||
cert_handler_get_ca_cert |
implemented |
||
cert_handler_get_info |
implemented |
||
cert_handler_get_server_cert |
implemented |
||
cert_handler_get_server_key |
implemented |
||
cert_handler_init |
implemented |
||
config_commit |
implemented |
||
config_factory_reset |
implemented |
||
config_get_all_as_json |
implemented |
||
config_get_bool |
implemented |
||
config_get_int16 |
implemented |
||
config_get_int32 |
implemented |
||
config_get_schema_json |
implemented |
||
config_get_string |
implemented |
||
config_init |
implemented |
||
config_set_all_from_json |
implemented |
||
config_set_bool |
implemented |
||
config_set_bool_no_commit |
implemented |
||
config_set_int16 |
implemented |
||
config_set_int16_no_commit |
implemented |
||
config_set_int32 |
implemented |
||
config_set_string |
implemented |
||
config_set_string_no_commit |
implemented |
||
config_write_factory_defaults |
implemented |
||
netif_uart_tunnel_deinit |
implemented |
||
netif_uart_tunnel_get_handle |
implemented |
||
netif_uart_tunnel_init |
implemented |
||
netif_uart_tunnel_config_t |
implemented |
||
JSON Schema as Configuration Source of Truth |
draft |
config; schema; architecture |
|
Web Interface Integration Support |
approved |
config; integration |
|
NVS Error Graceful Handling |
draft |
config; error-handling; reliability |
|
Configuration Initialization on Boot |
draft |
config; boot |
|
Simple Process to Add Configuration Fields |
draft |
config; extensibility; developer-experience |
|
Type Safety via Optional Static Validation |
draft |
config; validation; developer-experience |
|
Configuration Schema Versioning and Migration |
open |
config; versioning; migration; future |
|
Parameter Grouping for UI Organization |
draft |
config; ui; schema |
|
Parameter Type System |
draft |
config; types |
|
Build-Time Factory Defaults Generation |
draft |
config; build; code-generation |
|
No Runtime JSON Parsing in C Code |
draft |
config; performance; memory |
|
Key-Based NVS Storage |
draft |
config; storage; nvs |
|
Type-Safe Configuration API |
draft |
config; api; type-safety |
|
Persistent Configuration Storage |
draft |
config; storage; nvs |
|
Factory Reset Capability |
draft |
config; reset |
|
QEMU UART Network Bridge |
approved |
emulation; network; qemu; uart |
|
Packet Encapsulation |
approved |
emulation; protocol |
|
Host-Side Bridge Script |
approved |
emulation; tooling; host |
|
DHCP Client Support |
approved |
emulation; network; dhcp |
|
Conditional Compilation |
approved |
emulation; build |
|
Emulation Setup Documentation |
approved |
emulation; documentation |
|
Tunnel Throughput |
approved |
emulation; performance |
|
Packet Loss Handling |
approved |
emulation; reliability |
|
Component-based Architecture |
approved |
architecture; modularity |
|
Non-volatile Configuration Storage |
approved |
storage; nvs; configuration |
|
ESP32 Hardware Platform |
approved |
hardware; platform |
|
WiFi Connectivity |
approved |
network; wifi |
|
Memory Management |
approved |
performance; memory |
|
Error Handling and Recovery |
approved |
reliability; error-handling |
|
HTTPS Support |
open |
security; https; future |
|
Emulator Support |
approved |
emulator; qemu; testing |
|
Emulator Network Connectivity |
approved |
emulator; qemu; network; development |
|
System Time and NTP Support |
open |
time; ntp; future |
|
Web-based Configuration |
approved |
web; configuration |
|
Real-time Status Display |
approved |
web; ui; monitoring |
|
Configuration Interface |
approved |
web; ui; configuration |
|
WiFi Setup Interface |
approved |
web; wifi; network |
|
Web Interface Navigation |
approved |
web; ui; navigation |
|
HTTP Server Concurrency |
approved |
web; performance |
|
Configuration REST API |
approved |
web; api; config |
|
Web UI Responsiveness |
approved |
web; performance; ux |
|
Mobile-First Design |
approved |
web; ui; mobile |
|
Schema-Driven Configuration Form |
approved |
web; ui; config |
|
ESP-IDF CMake Integration |
approved |
build; cmake |
|
Certificate Handler Component Design |
draft |
component; security |
|
GitHub Codespaces Integration |
approved |
development; devcontainer |
|
Component Communication Pattern |
approved |
dataflow; communication |
|
Configuration Manager Component Design |
approved |
component; config |
|
Configuration Data Flow |
approved |
dataflow; config |
|
Error Recovery and Reset Strategy |
approved |
error-handling; reliability; reset |
|
Flash Memory Configuration |
approved |
flash; memory |
|
HTTP Server Architecture Details |
approved |
network; http; web |
|
ESP32 Template Layered Architecture |
approved |
architecture; layering |
|
Logging and Diagnostics Strategy |
approved |
logging; diagnostics; debugging |
|
Memory Management Strategy |
approved |
memory; performance |
|
Network Tunnel Component Design |
approved |
component; qemu; network |
|
System Performance Requirements |
approved |
performance; requirements |
|
QEMU Hardware Abstraction |
approved |
qemu; emulation |
|
QEMU Component Selection |
approved |
qemu; build |
|
FreeRTOS Task Organization |
approved |
threading; rtos |
|
Web Server Component Design |
approved |
component; web; network |
|
WiFi Manager Design Details |
approved |
network; wifi |
|
Type-Safe Configuration API |
approved |
api; interface; c-api |
|
JSON Schema-Driven Architecture |
draft |
architecture; config; json-schema |
|
Bulk JSON Configuration API |
approved |
api; json; bulk-operations |
|
Factory Reset via Bulk JSON Update |
approved |
build-process; code-generation; factory-reset |
|
Adding New Configuration Fields |
approved |
development; guide; extensibility |
|
Configuration Schema Structure |
approved |
data-structure; schema |
|
JSON Schema as Single Source of Truth |
approved |
architecture; schema; design-pattern |
|
NVS Storage Format |
approved |
storage; nvs |
|
Type Safety Without Code Generation |
approved |
type-safety; best-practices |
|
JSON Schema for UI Generation |
approved |
web; ui; javascript |
|
Configuration Webpage Architecture |
open |
frontend; javascript; ui |
|
Device Reset Countdown Interface |
open |
ui; countdown; reset |
|
Error Handling and User Feedback |
open |
error-handling; feedback |
|
Configuration Data Flow |
open |
data-flow; json; api |
|
Dynamic Form Generation from Schema |
open |
form-generation; schema; javascript |
|
Complete Page Initialization Flow |
open |
initialization; lifecycle |
|
JSON Array to Form Field Mapping |
open |
data-mapping; json; form |
|
UI State Management |
open |
ui-state; javascript |
|
Web Server Architecture |
approved |
web; architecture |
|
Captive Portal Design |
approved |
web; captive-portal; wifi |
|
HTTP Server Configuration |
approved |
web; config; performance |
|
Extension Guide for Web Pages |
approved |
web; extensibility; guide |
|
Config Manager Integration Pattern |
approved |
web; integration; config |
|
WiFi Manager Integration Pattern |
approved |
web; integration; wifi |
|
Configuration API Endpoints |
approved |
web; api; config; schema |
|
System Health API Endpoint |
approved |
web; api; diagnostics |
|
WiFi Management REST API Endpoints |
approved |
web; api; wifi |
|
URI Routing Table |
approved |
web; routing |
|
CORS Configuration |
approved |
web; security; cors |
|
Static File Embedding Strategy |
approved |
web; build; embedding |
|
Web Server Testing Strategy |
approved |
web; testing |
REQ_NETIF_TUNNEL_1¶