ESP-IDF 编程指南 Choose target... Choose version... 快速入门 API 参考 H/W 硬件参考 API 指南 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 ESP-IDF 编程指南 在 GitHub 上编辑 ESP-IDF 编程指南 [English] 这里是乐鑫 IoT 开发框架 (esp-idf) 的文档中心。ESP-IDF 是 ESP32、ESP32-S、ESP32-C、ESP32-H 和 ESP32-P 系列芯片的官方开发框架。 本文档仅包含针对 ESP32-C5 芯片的 ESP-IDF 使用。如需了解其他芯片，请在页面左上方的下拉菜单中选择你的目标芯片。 快速入门 API 参考 API 指南 此文档对您有帮助吗？ 反馈已收到，谢谢！ 如果您有其他意见，欢迎填写乐鑫文档反馈表。 我们重视您的反馈。 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download HTML ESP-IDF 编程指南 Choose target... Choose version... 快速入门 API 参考 H/W 硬件参考 API 指南 迁移指南 迁移到 ESP-IDF 5.x 从 4.4 迁移到 5.0 低功耗蓝牙 构建系统 GCC 网络 外设 协议 配置 从 ESP-IDF 中移出或弃用的组件 存储 系统 工具 从 5.0 迁移到 5.1 从 5.1 迁移到 5.2 从 5.2 迁移到 5.3 从 5.3 迁移到 5.4 从 5.4 迁移到 5.5 迁移到 ESP-IDF 6.x 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 迁移指南 从 4.4 迁移到 5.0 协议 在 GitHub 上编辑 协议 [English] Mbed TLS 在 ESP-IDF v5.0 版本中，Mbed TLS 已从 v2.x 版本更新到 v3.1.0 版本。 更多有关 Mbed TLS 从 v2.x 版本迁移到 v3.0 或更高版本的详细信息，请参考 官方指南。 重大更新（概述） 增加私有结构体字段数量 不再支持直接访问公共头文件中声明的结构体（ struct 类型）字段。 当前版本下，访问公共头文件中声明的结构体字段需要使用特定的访问函数 (getter/setter)。另外，也可以用 MBEDTLS_PRIVATE 宏暂时代替，但不建议使用此种方法。 更多详细信息，请参考 官方指南。 SSL 不再支持 TLS 1.0、TLS 1.1 和 DTLS 1.0 不再支持 SSL 3.0 移除密码模块中的废弃函数 更新了与 MD、SHA、RIPEMD、RNG、HMAC 模块相关的函数 mbedtls_*_ret() 的返回值，并将其重新命名，以取代未附加 _ret 的相应函数。 更多详细信息，请参考 官方指南。 废弃配置选项 下列为在此次更新中废弃的重要配置选项。与以下配置有关或是依赖于下列配置的相关配置也已相应废弃。 MBEDTLS_SSL_PROTO_SSL3：原用于支持 SSL 3.0 MBEDTLS_SSL_PROTO_TLS1：原用于支持 TLS 1.0 MBEDTLS_SSL_PROTO_TLS1_1：原用于支持 TLS 1.1 MBEDTLS_SSL_PROTO_DTLS：原用于支持 DTLS 1.1（当前版本仅支持 DTLS 1.2） MBEDTLS_DES_C：原用于支持 3DES 密码套件 MBEDTLS_RC4_MODE：原用于支持基于 RC4 的密码套件 备注 上述仅列出了可通过 idf.py menuconfig 配置的主要选项。更多有关废弃选项的信息，请参考 官方指南。 其他更新 禁用 Diffie-Hellman 密码交换模式 为避免 安全风险，当前版本已默认禁用 Diffie-Hellman 密码交换模式。以下为相应的禁用配置项： MBEDTLS_DHM_C：原用于支持 Diffie-Hellman-Merkle 模块 MBEDTLS_KEY_EXCHANGE_DHE_PSK：原用于支持 Diffie-Hellman 预共享密钥 (PSK) TLS 认证模式 MBEDTLS_KEY_EXCHANGE_DHE_RSA：原用于支持带有前缀的密码套件 TLS-DHE-RSA-WITH- 备注 在信号交换的初始步骤（即 client_hello）中，服务器会在客户端提供的列表中选择一个密码。由于 DHE_PSK/DHE_RSA 密码已在本次更新中禁用，服务器将退回到一个替代密码。在极个别情况中，服务器不支持任何其他的代码，此时，初始步骤将失败。若要检索服务器所支持的密码列表，需要首先在客户端使用特定的密码连接服务器，可以使用 sslscan 等工具完成连接。 从 X509 库中移除 certs 模块 mbedtls 3.1 不再支持 mbedtls/certs.h 头文件。大多数应用程序支持从包含列表中安全删除该头文件。 对 esp_crt_bundle_set API 的重大更新 更新后，调用 esp_crt_bundle_set() API 需要一个额外的参数 bundle_size。该 API 的返回类型也从 void 变为了 esp_err_t。 对 esp_ds_rsa_sign API 的重大更新 更新后，调用 esp_ds_rsa_sign() API 无需再使用参数 mode。 HTTPS 服务器 重大更新（概述） 更新 httpd_ssl_config_t 结构体中持有不同证书的变量名。 httpd_ssl_config::servercert：原 cacert_pem httpd_ssl_config::servercert_len：原 cacert_len httpd_ssl_config::cacert_pem：原 client_verify_cert_pem httpd_ssl_config::cacert_len：原 client_verify_cert_len httpd_ssl_stop() API 的返回类型从 void 变为了 esp_err_t。 ESP HTTPS OTA 重大更新（概述） 函数 esp_https_ota() 现需以指向 esp_https_ota_config_t 的指针作为参数，而非之前的指向 esp_http_client_config_t 的指针。 ESP-TLS 重大更新（概述） 私有化 esp_tls_t 结构体 更新后，esp_tls_t 已完全私有化，用户无法直接访问其内部结构。之前需要通过 ESP-TLS 句柄获得的必要数据，现在可由对应的 getter/setter 函数获取。如需特定功能的 getter/setter 函数，请在 ESP-IDF 的 Issue 板块 提出。 下列为新增的 getter/setter 函数： esp_tls_get_ssl_context()：从 ESP-TLS 句柄获取底层 ssl 栈的 ssl 上下文。 废弃函数及推荐的替代函数 下表总结了在 ESP-IDF v5.0 中废弃的函数以及相应的替代函数。 废弃函数 替代函数 esp_tls_conn_new() esp_tls_conn_new_sync() esp_tls_conn_delete() esp_tls_conn_destroy() 函数 esp_tls_conn_http_new() 现已废弃。请使用替代函数 esp_tls_conn_http_new_sync() （或其异步函数 esp_tls_conn_http_new_async() ）。请注意，使用替代函数时，需要额外的参数 esp_tls_t，此参数必须首先通过 esp_tls_init() 函数进行初始化。 HTTP 服务器 重大更新（概述） esp_http_server 现不再支持 http_server.h 头文件。请使用 esp_http_server.h。 ESP HTTP 客户端 重大更新（概述） 函数 esp_http_client_read() 和 esp_http_client_fetch_headers() 现在会返回额外的返回值 -ESP_ERR_HTTP_EAGAIN 用于处理超时错误，即数据准备好前就已调用超时的情况。 TCP 传输 重大更新（概述） 更新后，出现连接超时的情况时，函数 esp_transport_read() 将返回 0，对其他错误则返回 < 0。请参考 esp_tcp_transport_err_t，查看所有可能的返回值。 MQTT 客户端 重大更新（概述） esp_mqtt_client_config_t 的所有字段都分组存放在子结构体中。 以下为较为常用的配置选项： 通过 esp_mqtt_client_config_t::broker::address::uri 配置 MQTT Broker 通过 esp_mqtt_client_config_t::broker::verification 配置 MQTT Broker 身份验证的相关安全问题 通过 esp_mqtt_client_config_t::credentials::username 配置客户端用户名 esp_mqtt_client_config_t 不再支持 user_context 字段。之后注册事件处理程序，请使用 esp_mqtt_client_register_event()；最后一个参数 event_handler_arg 可用于将用户上下文传递给处理程序。 ESP-Modbus 重大更新（概述） 本次更新从 ESP-IDF 中移除了组件 freemodbus，该组件已作为一个独立组件受到支持。可前往如下的独立仓库，查看更多有关 ESP-Modbus 的信息： GitHub 中的 ESP-Modbus 组件 在新版应用程序中， main 组件文件夹应包括组件管理器清单文件 idf_component.yml，如下所示： dependencies: espressif/esp-modbus: version: "^1.0" 可以前往 乐鑫组件注册表 找到 ESP-Modbus 组件。更多有关如何设置组件管理器的信息，请参考 组件管理器文档。 对于使用 ESP-IDF v4.x 及以后版本的应用程序，需要通过添加组件管理器清单文件 idf_component.yml 拉取新版 ESP-Modbus 组件。同时，在编译时，应去掉已过时的 freemodbus 组件。此项操作可通过项目 CMakeLists.txt 中的以下语句实现： set(EXCLUDE_COMPONENTS freemodbus) 此文档对您有帮助吗？ 反馈已收到，谢谢！ 如果您有其他意见，欢迎填写乐鑫文档反馈表。 我们重视您的反馈。 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。 上一页 下一页 © 版权所有 2016 - 2026 乐鑫信息科技（上海）股份有限公司。 利用 Sphinx 构建，使用的 主题 based on Read the Docs Sphinx Theme. Download HTML ESP-IDF 编程指南 Choose target... Choose version... 快速入门 API 参考 API 约定 应用层协议 蓝牙® API 错误代码参考 连网 API 外设 API 配网 API 存储 API FAT 文件系统 在主机上生成和解析 FATFS 量产程序 非易失性存储库 在引导程序中使用 NVS 概述 应用示例 API 参考 NVS 加密 NVS 分区生成程序 NVS 分区解析程序 SD/SDIO/MMC 驱动程序 分区 API 块设备层 SPIFFS 文件系统 虚拟文件系统组件 磨损均衡 API Storage Security 示例 系统 API Configuration Options Reference H/W 硬件参考 API 指南 迁移指南 安全指南 库与框架 贡献指南 ESP-IDF 版本简介 资源 版权和许可证 关于本指南 切换语言 ESP-IDF 编程指南 API 参考 存储 API 在引导程序中使用 NVS 在 GitHub 上编辑 在引导程序中使用 NVS [English] 概述 本指南概述了可用于自定义引导加载程序代码的 NVS（非易失性存储）功能及其限制。 由于引导加载程序运行环境的限制，自定义引导加载程序代码无法直接使用完整的 NVS API。为此，NVS 提供了一个简化 API，仅支持只读访问 NVS 数据。 该 API 支持读取除 blob 之外的所有 NVS 数据类型。一次 API 调用可以同时读取多个 NVS 条目。可以从同一 NVS 分区的不同命名空间读取值，读取结果存储在输入/输出结构数组中，每个数据项的固定大小最多为 8 字节。 由于引导加载程序中的堆内存分配限制，读取字符串条目时，API 要求调用者提供缓冲区及其大小。 读取加密的 NVS 分区 如果 NVS 分区使用 NVS 加密 指南中的加密方案，该 API 还支持解密 NVS 数据。 应用程序应按照以下步骤使用 nvs_bootloader_read() API 读取加密 NVS 分区数据： 根据所选的 NVS 加密方案填充 NVS 安全配置结构 nvs_sec_cfg_t （详情请参阅 NVS 加密）。 使用 nvs_bootloader_read_security_cfg() API 从指定的安全方案中读取 NVS 安全配置。 获取安全配置后，使用 nvs_bootloader_secure_init() API 初始化 NVS flash 分区。 使用 nvs_bootloader_read() API 执行 NVS 读取操作。 使用 nvs_bootloader_secure_deinit() API 反初始化 NVS flash 分区，并清除安全配置。 备注 在使用基于 HMAC 的方案进行上述流程时，可以直接调用 nvs_flash_secure_init() API 对默认和自定义 NVS 分区进行加密，而无需启用 NVS 加密相关配置选项（如 CONFIG_NVS_ENCRYPTION， CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME -> CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC， CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID）。 应用示例 代码示例请参阅 ESP-IDF 示例 storage/nvs 目录下的 storage/nvs/nvs_bootloader。 本节演示了如何在输入/输出结构中准备数据，以支持不同的数据类型、命名空间和键。此外，还包含从 NVS 读取字符串数据的示例。 示例还演示了如何检查读取操作是否成功，数据是否存在不一致，或是否在 NVS 中找不到某些值的情形。该示例能够将 API 返回的值（或错误码）打印到控制台。 API 参考 Header File components/nvs_flash/include/nvs_bootloader.h This header file can be included with: #include "nvs_bootloader.h" This header file is a part of the API provided by the nvs_flash component. To declare that your component depends on nvs_flash, add the following to your CMakeLists.txt: REQUIRES nvs_flash or PRIV_REQUIRES nvs_flash Functions esp_err_t nvs_bootloader_read(const char *partition_name, const size_t read_list_count, nvs_bootloader_read_list_t read_list[]) Reads data specified from the specified NVS partition. This function reads data from the NVS partition specified by partition_name. Multiple NVS entries can be read in a single call. The list of entries to read is specified in the read_list array. Function indicates overall success or failure by its return value. In case it is ESP_OK or ESP_ERR_INVALID_ARG, result of validation / reading of individual entry is returned in the result_code member of each element of the read_list array. 参数: partition_name -- The name of the NVS partition to read from. read_list_count -- The number of elements in the read_list array. read_list -- An array of nvs_bootloader_read_list_t structures specifying the keys and buffers for reading data. 返回: The return value of the function in this file can be one of the following: ESP_OK: The function successfully checked all input parameters and executed successfully. The individual result_code in read_list indicates the result of the lookup for a particular requested key. ESP_ERR_INVALID_ARG: The validity of all read_list input parameters was checked and failed for at least one of the parameters. The individual result_code in read_list provides the detailed reason. This error code is also returned when read_list is null or read_list_count is 0. ESP_ERR_NVS_INVALID_NAME: The partition name specified is too long or is null. ESP_ERR_NVS_PART_NOT_FOUND: The partition was not found in the partition table. ESP_ERR_NVS_CORRUPT_KEY_PART: Encryption-related problems. ESP_ERR_NVS_WRONG_ENCRYPTION: Encryption-related problems. ESP_ERR_INVALID_STATE: NVS partition or pages related errors - wrong size of partition, header inconsistent / entries inconsistencies, multiple active pages, page in state INVALID. ESP_ERR_NO_MEM: Cannot allocate memory required to perform the function. Technical errors in underlying storage. esp_err_t nvs_bootloader_secure_init(const nvs_sec_cfg_t *sec_cfg) Initialize internal NVS security context, thus, enabling the NVS bootloader read API to decrypt encrypted NVS partitions. 备注 Once nvs_bootloader_secure_init() is performed, nvs_bootloader_read() can correctly read only those NVS partitions that are encrypted using the given nvs_sec_cfg_t security config, until nvs_bootloader_secure_deinit() clears the internal NVS security context. 参数: sec_cfg -- NVS security key that would be used for decrypting the NVS partition 返回: ESP_OK if security initialization is successful void nvs_bootloader_secure_deinit(void) Clear the internal NVS security context. esp_err_t nvs_bootloader_read_security_cfg(nvs_sec_scheme_t *scheme_cfg, nvs_sec_cfg_t *cfg) Reads NVS bootloader security configuration set by the specified security scheme. 参数: scheme_cfg -- [in] Security scheme specific configuration cfg -- [out] Security configuration (encryption keys) 返回: ESP_OK, if cfg was read successfully; ESP_ERR_INVALID_ARG, if scheme_cfg or cfg is NULL; ESP_FAIL, if the key reading process fails Unions union nvs_bootloader_value_placeholder_t #include