ESP-IDF User Guide for ESP32, SDK latest

ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide ESP-IDF Programming Guide Edit on GitHub ESP-IDF Programming Guide [中文] This is the documentation for Espressif IoT Development Framework (esp-idf). ESP-IDF is the official development framework for the ESP32, ESP32-S, ESP32-C, ESP32-H and ESP32-P Series SoCs. This document describes using ESP-IDF with the ESP32 SoC. To switch to a different SoC target, choose target from the dropdown in the upper left. Get Started API Reference API Guides Was this page helpful? Thank you! We received your feedback. If you have any comments, fill in Espressif Documentation Feedback Form. We value your feedback. Let us know how we can improve this page by filling in Espressif Documentation Feedback Form. Next © Copyright 2016 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download HTML ESP-IDF Programming Guide Choose target... Choose version... Get Started API Reference Hardware Reference API Guides Application Level Tracing Library Application Startup Flow Bluetooth® Architecture Bluetooth® Classic Bluetooth® Low Energy ESP-BLE-MESH Bootloader Build System Build System v2 RF Coexistence C Support C++ Support Code Quality Core Dump Current Consumption Measurement of Modules Deep-sleep Wake Stubs Error Handling ESP-WIFI-MESH Support for External RAM Fatal Errors File System Considerations Hardware Abstraction High Priority Interrupts JTAG Debugging Project Configuration Linker Script Generation Low Power Modes lwIP Memory Types OpenThread Partition Tables Performance Reproducible Builds RF Calibration Standard I/O and Console Output Thread Local Storage Tools IDF Frontend - idf.py IDF Monitor IDF Docker Image IDF Component Manager IDF Clang-Tidy Downloadable IDF Tools IDF Size IDF SBOM Generating SPDX SBOM File for ESP-IDF Project Checking SPDX SBOM File for Vulnerabilities Checking Components for Vulnerabilities IDF Diag QEMU Emulator Unit Testing in ESP32 Running ESP-IDF Applications on Host Wi-Fi Driver Wi-Fi Security Wi-Fi Expansion PHY Security Guides Migration Guides Libraries and Frameworks Contributions Guide ESP-IDF Versions Resources Copyrights and Licenses About Switch Between Languages ESP-IDF Programming Guide API Guides Tools IDF SBOM Edit on GitHub IDF SBOM A Software Bill of Materials (SBOM) is a comprehensive inventory that identifies all the components and libraries within a software application, along with their relationships. This is essential for the software supply chain, as it enables the tracking and management of components obtained from various vendors or open-source projects. The component in an SBOM is described with information such as its name and version, among other details that may include, for example, licenses. This helps in identifying potential vulnerabilities, ensuring compliance with licensing requirements, and managing risks associated with third-party components. The minimal data fields each component must contain, according to National Telecommunications and Information Administration (NTIA), is described by The Minimum Elements for a Software Bill of Materials (SBOM). Data Field Description Supplier Name The name of an entity that creates, defines, and identifies components. Component Name Designation assigned to a unit of software defined by the original supplier. Version of the Component Identifier used by the supplier to specify a change in software from a previously identified version. Other Unique Identifiers Other identifiers that are used to identify a component, or serve as a look-up key for relevant databases. Dependency Relationship Characterizing the relationship that an upstream component X is included in software Y. Author of SBOM Data The name of the entity that creates the SBOM data for this component. Timestamp Record of the date and time of the SBOM data assembly. To generate an NTIA‑compliant SBOM file for an ESP‑IDF project, use the idf.py sbom-create command. This command generates an SBOM file in Software Package Data Exchange (SPDX) format, version 2.2. The generated SBOM can then be scanned for known vulnerabilities in the National Vulnerability Database (NVD) using Common Platform Enumeration (CPE) identifiers with the idf.py sbom-check command. The idf.py sbom-create and idf.py sbom-check commands provide basic integration of the esp-idf-sbom tool into idf.py. For more detailed information, see the documentation in the esp-idf-sbom project. Generating SPDX SBOM File for ESP-IDF Project The generated SPDX SBOM file contains information derived from the project’s build artifacts. To ensure these artifacts are up-to-date, the idf.py sbom-create command depends on the idf.py build command. If the project has not yet been built, or if source files have changed, a build is automatically triggered before the SBOM is generated. This guarantees that the resulting SBOM always accurately reflects the current state of the project. To generate a default minimal SPDX SBOM file for your project, run the following command in your project directory. $ idf.py sbom-create By default, the SPDX SBOM file is created in the build directory and named after the project, with the .spdx extension. For example, for the hello_world example project, the file will be located at build/hello_world.spdx by default. The output location of the generated SPDX SBOM file can be changed using the --spdx-file option. For more information and additional options, see idf.py sbom-create --help. The idf.py sbom-create command generates the default SPDX SBOM file for a project. If more control is required over how the SPDX SBOM file is generated and what information it contains, refer to the esp-idf-sbom tool documentation. That documentation also provides detailed information about the component layout within SPDX SBOM files and the manifest files used to describe components. Checking SPDX SBOM File for Vulnerabilities The idf.py sbom-check command scans a project's SPDX SBOM file for known vulnerabilities. While this command is the primary method within ESP-IDF, you can also use any other third-party utility that supports the SPDX format, such as cve-bin-tool. To check an SPDX SBOM file for vulnerabilities, use the following syntax: $ idf.py sbom-check --spdx-file For example, to scan the SPDX SBOM file generated for the hello_world example, run: $ idf.py sbom-check --spdx-file build/hello_world.spdx By default, the idf.py sbom-check command uses a local mirror of the NVD database. You can choose between two modes of operation: Local Mirror (Default): This requires approximately 900 MB of disk space. While the initial population of the database may take some time, this method is convenient for frequent, fast, and offline scans. NVD REST API: Use the --nvd-api option to query the NVD database directly online. This is better suited for occasional or ad hoc scans where you want to avoid the disk space overhead of a local mirror. The command by default generates a report table summarizing any potential vulnerabilities found. Below is an example of a shortened report for a hypothetical project that intentionally uses an outdated version of the expat component to demonstrate the detection capabilities. For more information and additional options, see idf.py sbom-check --help. Report summary ┌───────────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────┐ │ Date: │ 2024-11-13T14:20:23Z │ │ Project name: │ project-expat_test │ │ Project version: │ 6c23b9cdb268 │ │ Vulnerability database: │ NATIONAL VULNERABILITY DATABASE REST API (https://nvd.nist.gov) │ │ Generated by tool: │ esp-idf-sbom (0.19.1) │ │ Generated with command: │ esp-idf-sbom check sbom.spdx │ │ Number of scanned packages: │ 32 │ ├───────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────┤ │ CRITICAL CVEs found: │ CVE-2024-45491, CVE-2024-45492 │ │ Packages affect by CRITICAL CVEs: │ libexpat │ │ Number of CRITICAL CVEs: │ 2 │ ├───────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────┤ │ HIGH CVEs found: │ CVE-2024-45490 │ │ Packages affect by HIGH CVEs: │ libexpat │ │ Number of HIGH CVEs: │ 1 │ ├───────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────┤ │ MEDIUM CVEs found: │ │ │ Packages affect by MEDIUM CVEs: