Web Server API

API Component: Web Server API_COMP_WEB_SERVER
status: implemented
header_file: main/components/web_server/web_server.h
links outgoing: REQ_SYS_WEB_1, REQ_WEB_1, REQ_WEB_2, REQ_WEB_3, REQ_WEB_CONF_1, REQ_WEB_SCHEMA_1, REQ_WEB_4, REQ_WEB_5, REQ_WEB_LED_1, REQ_SYS_NET_1, REQ_SYS_CFG_1, REQ_SYS_ARCH_1, SPEC_WEB_ARCH_1, SPEC_CFG_WEB_ARCH_1

HTTP server for WiFi captive portal and configuration interface.

Key features:

  • Multi-page responsive web interface with navbar navigation

  • Static file serving from embedded flash assets (HTML, CSS, JS)

  • WiFi configuration API endpoints (scan, connect, status, reset)

  • Integration with DNS server module for captive portal functionality

  • CORS-secured API endpoints with proper MIME type handling

Architecture: Implements HTTP server and DNS server for captive portal (AP mode). Serves static web assets from flash. Provides REST API endpoints for configuration, WiFi setup, and LED state. Integrates with config_manager and wifi_manager. Designed for modular, component-based ESP-IDF architecture.

Lifecycle Functions

API Function: web_server_init API_FUNC_WEB_INIT
status: implemented
api_signature: esp_err_t web_server_init(const web_server_config_t *config)
returns: ESP_OK on success, error code on failure
parameters: config (server configuration or NULL)
component: API_COMP_WEB_SERVER
links outgoing: REQ_SYS_WEB_1, REQ_WEB_1, REQ_WEB_2, REQ_WEB_3, REQ_WEB_CONF_1, REQ_WEB_4, REQ_WEB_5, SPEC_WEB_ARCH_1

Initialize web server with embedded static assets.

Signature:

esp_err_t web_server_init(const web_server_config_t *config);

Parameters:

  • config - Server configuration (NULL for default settings)

Returns:

  • ESP_OK - Initialization successful

  • ESP_ERR_NO_MEM - Out of memory

  • ESP_ERR_INVALID_ARG - Invalid configuration

  • ESP_FAIL - Other errors

Note

Sets up all URI handlers for static files and API endpoints.
API Function: web_server_start API_FUNC_WEB_START
status: implemented
api_signature: esp_err_t web_server_start(void)
returns: ESP_OK on success, error code on failure
parameters: None
component: API_COMP_WEB_SERVER
links outgoing: REQ_WEB_3, REQ_SYS_NET_1, SPEC_WEB_ARCH_1

Start web server and DNS server for captive portal.

Signature:

esp_err_t web_server_start(void);

Parameters:

  • None

Returns:

  • ESP_OK - Server started successfully

  • ESP_ERR_INVALID_STATE - Server already running

  • ESP_FAIL - Other errors

Note

Starts DNS server for captive portal in AP mode.
API Function: web_server_stop API_FUNC_WEB_STOP
status: implemented
api_signature: esp_err_t web_server_stop(void)
returns: ESP_OK on success, error code on failure
parameters: None
component: API_COMP_WEB_SERVER
links outgoing: REQ_WEB_5, SPEC_WEB_ARCH_1

Stop web server and DNS server.

Signature:

esp_err_t web_server_stop(void);

Parameters:

  • None

Returns:

  • ESP_OK - Server stopped successfully

  • ESP_ERR_INVALID_STATE - Server not running

  • ESP_FAIL - Other errors

Note

Safe to call multiple times or when servers are not running.
API Function: web_server_is_running API_FUNC_WEB_IS_RUNNING
status: implemented
api_signature: bool web_server_is_running(void)
returns: true if HTTP server is active, false otherwise
parameters: None
component: API_COMP_WEB_SERVER
links outgoing: REQ_WEB_5

Check if web server is currently running.

Signature:

bool web_server_is_running(void);

Parameters:

  • None

Returns:

  • true - HTTP server is active

  • false - HTTP server is not running
API Function: web_server_get_port API_FUNC_WEB_GET_PORT
status: implemented
api_signature: uint16_t web_server_get_port(void)
returns: Server port number
parameters: None
component: API_COMP_WEB_SERVER
links outgoing: REQ_WEB_5

Get the current HTTP server port number.

Signature:

uint16_t web_server_get_port(void);

Parameters:

  • None

Returns:

  • uint16_t - Server port number (typically 80)

Static File Handler

API Function: static_file_handler API_FUNC_WEB_STATIC_FILE
status: implemented
api_signature: esp_err_t static_file_handler(httpd_req_t *req)
returns: ESP_OK on success, ESP_FAIL on file not found or other errors
parameters: req (HTTP request object)
component: API_COMP_WEB_SERVER
links outgoing: REQ_WEB_1, REQ_WEB_2, REQ_WEB_4, REQ_WEB_SCHEMA_1, SPEC_CFG_WEB_ARCH_1

HTTP handler for serving embedded static files.

Signature:

esp_err_t static_file_handler(httpd_req_t *req);

Parameters:

  • req - HTTP request object

Returns:

  • ESP_OK - File served successfully

  • ESP_FAIL - File not found or other errors

Note

Serves HTML, CSS, and JS files from embedded flash. Sets MIME types and cache headers.

Data Types

API Data Structure: web_server_config_t API_STRUCT_WEB_CONFIG
status: implemented
component: API_COMP_WEB_SERVER
links outgoing: REQ_WEB_5

Web server configuration structure.

Definition:

typedef struct {
    uint16_t port;
    size_t max_open_sockets;
} web_server_config_t;

Fields:

  • port - HTTP server port (default: 80)

  • max_open_sockets - Maximum concurrent connections (default: 7)