Node: SERVER

Modules
	SERVER
	Public API for the HTTP(S) server node. Provides server initialization, HTTP/HTTPS server tuning, and registration of custom URI handlers for application endpoints.
	REST API
	SERVER REST API documentation.
	Kconfig
	Node SERVER Kconfig configuration options.

Detailed Description

esp_iot_framework_server v0.1.0

A framework node for deploying a standalone HTTP(S) server directly on the device to handle incoming requests

esp32 • esp32s2 • esp32s3 • esp32c2 • esp32c3 • esp32c6

esp_iot_framework_server is a framework node for deploying a standalone HTTP(S) server directly on the device to handle incoming requests. Following the project's core philosophy of absolute autonomy, it turns the microcontroller into a self-sufficient server, enabling direct control via standard web browsers, curl, or similar CLI tools without requiring external hubs or applications. For an in-depth look, check out the documentation.

Architecture and Under the Hood

The web server's lifecycle is tightly synchronized with network events: it spins up automatically as soon as the device acquires an IP address and gracefully stops, freeing up system resources, if the connection is lost.

The entire server infrastructure functions via a middleware layer that handles uniform request logging and restricts access to administrative endpoints using Basic Auth (when enabled in the project). The node supports both plain HTTP and secure HTTPS (TLS), utilizing certificates and configurations persisted in NVS.

REST API Features

The built-in API equips your end device with a scalable suite of management capabilities:

• Wi-Fi Management - Retrieve the list of saved Wi-Fi profiles, update or clear Wi-Fi profiles, and run background connectivity and health tests for a specific Wi-Fi profile.
• System Metrics - Access essential and expandable device telemetry, including heap statistics (free/minimum heap, largest free block), uptime, CPU frequency, core count, chip model and hardware revision, flash size, last reset reason, the device MAC address, and other system data.
• OTA Firmware Management - Read running software metadata (such as project name, version, compile date, and ESP-IDF version), upload new binaries, and handle update confirmations or automatic rollbacks.
• Security Control - Modify the administrator password on the fly and trigger on-device regeneration of cryptographic TLS keys and certificates.
• Remote log reading - View device logs directly in the browser without a UART connection. CORE captures all system and business logs into an internal ring buffer; the SERVER streams them live to the Logs page in the Web Admin GUI.

For an in-depth look, check out the API documentation.

Web Admin GUI

When the graphical interface is included in the build, its compressed static assets (HTML, CSS, JS) are embedded directly into the firmware binary. The interface is highly optimized for lightweight performance and maintains backward compatibility with legacy browsers (down to IE8 and below), except for the OTA update functionality, which requires browser support for JS file uploads.

Implementing Custom Device Logic

Transforming this foundational node into an end product is achieved by registering custom URI handlers for peripherals, sensors, or relays. By placing custom endpoints within the administrative URI space (using the /_/ prefix), the node automatically applies the administrator's Basic Auth. This allows you to focus on your product's core logic without getting bogged down by low-level web server boilerplate.

Example of use

More examples can be found in the examples folder with the suffix _server.

#include <esp_err.h>
#include <esp_http_server.h>
#include <esp_iot_framework_core.h>
#include <esp_iot_framework_server.h>
 
esp_err_t hello_world(httpd_req_t *req) {
    const char *resp = "Hello World, from esp_iot_framework!";
    httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN);
    return ESP_OK;
}
 
static const httpd_uri_t my_uris[] = {
    { .uri = "/hello", .method = HTTP_GET, .handler = hello_world }
};
 
void app_main(void) {
    ESP_ERROR_CHECK(eif_core_initialize());
    ESP_ERROR_CHECK(eif_server_initialize());
    ESP_ERROR_CHECK(eif_nvs_initialize());
    ESP_ERROR_CHECK(eif_server_set_uri_handlers(my_uris, 1));
    ESP_ERROR_CHECK(eif_wifi_initialize());
 
    while (1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

Usage for creating end devices

To start using this framework, you must apply the appropriate configuration files (from both the CORE and SERVER components) and connect it to your project. Configure your project's main CMakeLists.txt like this (replace <TEXT> with the desired values, without the <>s themselves):

cmake_minimum_required(VERSION 3.16)
 
list(APPEND SDKCONFIG_DEFAULTS 
    "<PATH_TO_FRAMEWORK>/components/esp_iot_framework_core/sdkconfig.defaults"
    "<PATH_TO_FRAMEWORK>/components/esp_iot_framework_server/sdkconfig.server"
)
# If you are using your own FILE, add this line:
# list(APPEND SDKCONFIG_DEFAULTS "sdkconfig.defaults")
list(APPEND EXTRA_COMPONENT_DIRS "<PATH_TO_FRAMEWORK>/components")
 
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(<NAME_PROJECT>)