Node: Device

Modules
	Device
	Public API for application development. Provides framework initialization, Wi-Fi configuration, network profile management, and system lifecycle hooks.
	REST API
	Device REST API documentation.

Detailed Description

esp_iot_framework_device v0.2.1

A framework for creating reliable IoT devices based on the Espressif Systems chips

esp32 • esp32s2 • esp32s3 • esp32c2 • esp32c3 • esp32c6

esp_iot_framework_device is a foundational network node based on Espressif chips, designed for building fully manageable end IoT products. Operating on top of esp_iot_framework_core, it provides an out-of-the-box HTTP/HTTPS web server with a comprehensive REST API for remote administration alongside an optional Web Admin GUI. 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.

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.

Usage for creating end devices

To start using this framework, you must apply the settings from sdkconfig.defaults 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_device/sdkconfig.defaults")
# 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>)