什么是 ESP Component Registry 和 IDF Component Manager？

ESP Component Registry（components.espressif.com）是乐鑫模块化软件包的官方中央仓库。IDF Component Manager 集成在 ESP-IDF 中（v4.4+，v5.x+ 起默认启用），可根据 idf_component.yml 清单自动下载、编译并解析依赖版本。

如何向 ESP-IDF 项目中添加组件？

可以在项目终端运行 'idf.py add-dependency "namespace/component^version"'（例如：idf.py add-dependency "espressif/esp_lvgl_port^2.4.0"），也可以直接编辑 main/idf_component.yml。

使用 Component Registry 与 git 子模块有什么区别？

Component Registry 省去了管理笨重 Git 子模块和手动跟踪的麻烦。它提供语义化版本（^ 和 ~）、自动解析传递依赖，以及按需的模块化编译。

我可以创建并发布自己的组件吗？

可以，任何开发者或公司都可以使用官方的 Compote CLI 工具（pip install idf-component-manager）向 ESP Component Registry 发布公开或私有组件。

ESP-IDF Component Manager

ESP Component Registry

乐鑫面向 ESP-IDF 的官方可复用软件包目录。选择驱动、语音和工业协议栈，复制命令并生成项目清单。

打开官方注册中心生成 idf_component.yml

类别

兼容芯片

42 个组件

清单： 2 个组件

espressif/官方

esp_lvgl_port

ESP LVGL Port

^2.4.0

官方的线程安全 LVGL（Light and Versatile Graphics Library）移植，面向 ESP-IDF，支持硬件加速和多显示屏。

LVGL
GUI
显示屏
触摸
人机界面

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-P4, ESP32-C3, ESP32-C6

lvgl/

lvgl

LVGL Graphics Library Core

^9.1.0

嵌入式系统中最流行的 C 语言开源图形库。提供丰富的控件、流畅的动画和现代化的布局支持。

LVGL 9
Graphics
Widgets
GUI
Embedded UI

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-P4, ESP32-C3, ESP32-C6

espressif/官方

esp32_display_panel

ESP32 Display Panel Driver

^0.2.0

统一的 LCD 控制器（RGB、SPI、QSPI、MIPI-DSI）与电容触摸驱动，专为 ESP32-S3 和 ESP32-P4 设计。

LCD
MIPI-DSI
QSPI
Touch
ST7789
ILI9341

Chips: ESP32-S3, ESP32-P4, ESP32-S2, ESP32

espressif/官方

esp_lcd_touch

ESP LCD Touch Framework

^1.1.2

触摸屏 LCD 触摸面板的核心抽象组件。支持坐标校准、多点触控读取，并可直接与 LVGL 集成。

触摸屏
电容式
电阻式
I2C 触摸
坐标

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-P4, ESP32-C3, ESP32-C6

espressif/官方

esp_lcd_touch_gt911

GT911 电容触摸驱动

^1.1.2

专用于 Goodix GT911 电容触摸控制器的 I2C 驱动，广泛用于 ESP32-S3 和 P4 的 4.3"、5" 和 7" 显示屏。

GT911
Goodix
电容触摸
多点触控
I2C

Chips: ESP32, ESP32-S3, ESP32-P4, ESP32-S2

espressif/官方

esp_lcd_touch_ft5x06

FocalTech FT5x06 / FT6x36 触摸驱动

^1.1.0

面向 FocalTech 控制器（FT5206、FT5316、FT5436、FT6236、FT6336）的电容触摸面板驱动，支持手势和中断。

FT6236
FT5x06
FocalTech
触摸
I2C

Chips: ESP32, ESP32-S3, ESP32-P4, ESP32-S2, ESP32-C3

espressif/官方

esp_jpeg

ESP JPEG Decoder (TJpgDec)

^1.3.0

高速 JPEG 编解码器，带有汇编 SIMD 优化，可在显示屏上无延迟地显示图像和摄像头视频流。

JPEG
TJpgDec
摄像头
图像
SIMD

Chips: ESP32, ESP32-S3, ESP32-P4, ESP32-C3

espressif/官方

esp_rainmaker

ESP RainMaker Agent

^1.4.0

乐鑫 ESP RainMaker AIoT 云平台的官方固件代理。支持手机 App、Alexa、Google Home 控制以及 OTA。

RainMaker
AWS Cloud
iOS/Android App
Alexa
Google Home
OTA

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6

espressif/官方

mesh_lite

ESP Mesh-Lite Network Stack

^1.2.0

轻量级 Wi-Fi Mesh 网络，每个节点都有独立的 IP 连接，可在局域网内直接通信，并通过多跳访问云端。

Mesh
Wi-Fi Mesh
Mesh 网络
分布式 IoT
IP Layer

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6

espressif/官方

esp_modbus

ESP-Modbus Industrial Stack

^1.0.15

完整的工业 Modbus 协议栈（主站/从站），支持 RS-485（RTU/ASCII）以及以太网/Wi-Fi（Modbus TCP）接口。

Modbus
RS-485
Modbus TCP
工业自动化
PLC

Chips: ESP32, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

espressif/官方

net_connect

Unified Network Connect

^1.0.0

统一的网络连接管理组件，可透明地切换并初始化 Wi-Fi、以太网、Thread 或移动 PPP。

Network
Wi-Fi
Ethernet
故障切换
自动连接

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

espressif/官方

esp_hosted

ESP-Hosted Coprocessor

^0.0.10

把 ESP32 变成无线通信协处理器（Wi-Fi + BLE），供 Linux 主机（Raspberry Pi、i.MX）或通过 SPI/SDIO/UART 连接的微控制器使用。

协处理器
SDIO
SPI
Linux Wi-Fi
Raspberry Pi

Chips: ESP32, ESP32-S3, ESP32-C3, ESP32-C6

espressif/官方

esp-now

ESP-NOW 增强版与配网

^2.5.0

ESP-NOW 协议的扩展，提供遥控配对、AES-128 安全以及多设备控制等高级功能。

ESP-NOW
无线
低延迟
广播
遥控

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6

espressif/官方

esp-sr

ESP-SR Speech Recognition

^1.5.0

100% 离线的语音识别框架，包含 WakeNet（唤醒词）、MultiNet（本地命令）和 AFE 声学算法。

语音
WakeNet
MultiNet
语音识别
离线
AEC

Chips: ESP32-S3, ESP32-P4, ESP32

espressif/官方

esp_codec_dev

ESP Audio Codec Device HAL

^1.3.0

统一的 I2S/I2C 音频编解码器抽象层（ES8311、ES8388、ES7210、ES7243、TAS5805M），用于立体声输入输出。

Audio Codec
I2S
ES8311
ES8388
麦克风 DAC

Chips: ESP32, ESP32-S3, ESP32-P4, ESP32-C3, ESP32-C6

espressif/官方

es8311

ES8311 音频编解码器驱动

^1.0.0

面向 Everest ES8311 编解码器（单声道 DAC + 麦克风 ADC）的专用低功耗驱动，见于 ESP32-S3-BOX 和 IoT 开发板。

ES8311
音频
DAC
麦克风
I2S

Chips: ESP32, ESP32-S3, ESP32-P4, ESP32-C3

espressif/官方

esp32-camera

ESP32 Camera Driver

^2.0.12

官方 CMOS 摄像头驱动（OV2640、OV3660、OV5640、OV7670、GC0308），支持 DMA、DMA-2D、JPEG 捕获，以及通过 HTTP/RTSP 的 MJPEG 流。

摄像头
OV2640
OV5640
DVP
MIPI-CSI
视频

Chips: ESP32, ESP32-S3, ESP32-P4, ESP32-S2

espressif/官方

esp-dsp

ESP-DSP Signal Processing

^1.5.1

面向 ESP32 SoC 的官方数字信号处理库（FFT、FIR/IIR 数字滤波器、矩阵与加速的线性代数）。

DSP
FFT
滤波器
数学
SIMD
汇编

Chips: ESP32, ESP32-S3, ESP32-P4, ESP32-C3, ESP32-C6

espressif/官方

esp-nn

ESP-NN Neural Network Kernels

^1.2.0

用向量汇编优化的内核，在 ESP32 芯片上加速神经网络和 TensorFlow Lite Micro 模型。

TinyML
TensorFlow Lite
神经网络
推理
Edge AI

Chips: ESP32-S3, ESP32-P4, ESP32

espressif/官方

esp-matter

ESP Matter SDK

^1.3.0

官方 SDK，用于创建可在 Wi-Fi 和 Thread 上与 Apple Home、Google Home、Alexa 和 Home Assistant 互操作的设备。

Matter
智能家居
Apple HomeKit
Google Home
Thread
CHIP

Chips: ESP32, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2

espressif/官方

esp-zigbee-lib

ESP Zigbee 3.0 Library

^1.6.0

经过认证的 Zigbee 3.0 协议栈（ZBOSS），用于在 802.15.4 芯片上创建低功耗的协调器、路由器和终端设备节点。

Zigbee 3.0
ZBOSS
802.15.4
Home Automation
电池供电

Chips: ESP32-H2, ESP32-C6

espressif/官方

esp_rcp_update

ESP RCP Thread/Zigbee Gateway

^1.0.0

用于更新 802.15.4 射频协处理器（RCP）的组件，用来构建 Thread 边界路由器和多协议 Zigbee 网关。

Thread Border Router
OpenThread
RCP
Zigbee Gateway

Chips: ESP32-H2, ESP32-C6, ESP32-S3

espressif/官方

led_indicator

LED Indicator Driver

^1.2.0

智能的 LED 灯效控制驱动（快闪、呼吸/渐变、错误码和 RGB），不会阻塞主循环。

LED
PWM
RGB
闪烁
视觉反馈

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4

espressif/官方

button

IoT Button Handler (iot_button)

^3.4.0

完整的按键管理器，支持消抖、单击、双击、多击、长按事件以及矩阵键盘。

按键
消抖
Long Press
Double Click
GPIO

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4

espressif/官方

led_strip

可寻址 LED 灯带（WS2812/SK6812）

^2.5.4

高性能驱动，使用 RMT 或 SPI 外设控制 WS2812、WS2813 和 SK6812 可寻址 LED 灯带与灯阵。

WS2812B
Neopixel
SK6812
RMT
LED 灯带
RGB

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

espressif/官方

esp_tinyusb

ESP Native USB Device (TinyUSB)

^1.5.0

乐鑫为 ESP32-S2、ESP32-S3 和 ESP32-P4 提供的官方 TinyUSB 扩展，可模拟 USB CDC 串口、HID 键盘/鼠标、MSC 优盘、DFU 和 WebUSB。

原生 USB
TinyUSB
USB CDC
USB HID
WebUSB
MSC

Chips: ESP32-S2, ESP32-S3, ESP32-P4

espressif/官方

w5500

WIZnet W5500 SPI Ethernet Driver

^1.2.0

通过 SPI 总线驱动 WIZnet W5500 以太网芯片的官方驱动，把物理接口无缝接入 ESP-IDF 原生 TCP/IP 协议栈（lwIP）。

W5500
Ethernet
SPI Ethernet
RJ45
lwIP
有线网络

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

espressif/官方

ch390

CH390 SPI Ethernet Driver

^1.0.0

面向 WCH CH390 控制器的 SPI 10/100M 以太网驱动，适合在 ESP32-C3、S3 或 P4 开发板上低成本添加 RJ45 网口。

CH390
Ethernet
WCH
SPI Ethernet
RJ45

Chips: ESP32, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

espressif/官方

usb_host_uvc

USB Host UVC (Webcam Driver)

^1.0.4

USB Host 驱动，可把标准 USB UVC 网络摄像头直接接到 ESP32-S2、ESP32-S3 或 ESP32-P4 的原生 USB 口。

USB Host
UVC
Webcam
USB 摄像头
视频

Chips: ESP32-S2, ESP32-S3, ESP32-P4

espressif/官方

sensor_hub

ESP Sensor Hub Manager

^1.0.0

统一的框架，用于管理异构传感器（I2C/SPI），支持周期采样、数据融合以及由事件/中断触发。

传感器
Sensor Hub
I2C
事件
周期采集

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

espressif/官方

bmi270_sensor

Bosch BMI270 IMU 传感器驱动

^1.0.1

面向 Bosch BMI270 六轴惯性 IMU 传感器（加速度计 + 陀螺仪）的官方驱动，支持运动手势和计步检测。

BMI270
IMU
加速度计
陀螺仪
Bosch
手势

Chips: ESP32, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

espressif/官方

ds18b20

DS18B20 温度传感器驱动

^1.0.0

面向 Dallas/Maxim DS18B20 单总线（1-Wire）温度传感器的数字驱动，通过 RMT 总线支持在同一个 GPIO 引脚上挂接多个传感器。

DS18B20
1-Wire
温度
传感器
Dallas

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

esp-idf-lib/

scd4x

Sensirion SCD40/SCD41 CO2 传感器驱动

^1.0.0

面向 Sensirion SCD40 和 SCD41 光声式 CO2、温度和相对湿度传感器的高精度 I2C 驱动，带自动校准。

SCD40
SCD41
Sensirion
CO2
空气质量
I2C

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4

espressif/官方

esp-box-3

BSP ESP32-S3-BOX-3

^1.2.0

面向 ESP32-S3-BOX-3 AI 开发板的完整支持包，只需一个函数即可初始化触摸屏、音频编解码器、双麦克风、运动传感器和 LED。

BSP
ESP-BOX-3
触摸显示屏
麦克风
音频 ES8311
I2C/SPI

Chips: ESP32-S3

espressif/官方

esp32_s3_korvo_2

BSP ESP32-S3-Korvo-2

^1.1.0

面向 ESP32-S3-Korvo-2 音频与语音识别开发套件的板级支持包（Board Support Package），支持 I2S 麦克风和触摸按键。

BSP
Korvo
音频
麦克风阵列
ESP-SR

Chips: ESP32-S3

espressif/官方

esp32_s3_eye

BSP ESP32-S3-EYE

^1.1.0

面向官方计算机视觉开发板 ESP32-S3-EYE 的板级支持包，配置 OV2640 摄像头、圆形 SPI LCD 显示屏和数字麦克风。

BSP
ESP32-S3-EYE
摄像头
计算机视觉
显示屏

Chips: ESP32-S3

espressif/官方

m5stack_core_s3

BSP M5Stack CoreS3

^1.0.0

面向 M5Stack CoreS3 设备的官方板级支持包，初始化触摸屏、AXP2101 电源管理芯片、GC0308 摄像头和 I2S 扬声器。

BSP
M5Stack
CoreS3
Display ILI9342C
AXP2101
摄像头

Chips: ESP32-S3

waveshare/

esp32_p4_wifi6_touch_lcd_7b

BSP Waveshare ESP32-P4 7" 触摸 LCD

^1.0.0

面向高性能 Waveshare ESP32-P4 开发板的支持包，配备 7 英寸电容触摸屏（MIPI-DSI 1024x600）和 Wi-Fi 6 协处理器。

BSP
ESP32-P4
MIPI-DSI
Waveshare
7 英寸屏
触摸

Chips: ESP32-P4

joltwallet/

littlefs

LittleFS Filesystem for ESP-IDF

^1.14.8

面向 SPI 闪存的 LittleFS 文件系统的稳健移植，带动态磨损均衡和防断电损坏保护。

LittleFS
Flash
Filesystem
Wear Leveling
NVS

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4

espressif/官方

esp-idf-cxx

ESP-IDF C++ 现代封装

^1.2.0

现代 C++（C++17/C++20/C++23）类与封装集合，采用 RAII 语义，覆盖 GPIO、Wi-Fi、定时器、FreeRTOS 队列和信号量。

C++
C++20
RAII
Modern C++
面向对象
FreeRTOS

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4

espressif/官方

cbor

TinyCBOR Serialization

^0.6.0

超轻量级库，用于 CBOR（Concise Binary Object Representation）二进制格式的数据序列化与反序列化。

CBOR
序列化
二进制
IoT Protocol
紧凑 JSON

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2, ESP32-P4

espressif/官方

esp_websocket_client

ESP WebSocket Client

^1.2.4

支持 TLS/SSL（WSS）、自动重连、子协议和 ping/pong 心跳的实时双向 WebSocket 客户端。

WebSocket
WSS
TLS
实时
Sockets
JSON

Chips: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-P4

清单生成器

你的 idf_component.yml

将文件保存到项目的 main/ 文件夹中，ESP-IDF 会在编译时下载所有库。

# main/idf_component.yml
# 由 ESPDocs Component Hub 生成（https://espdocs.cienciaembarcada.com.br/zh-CN/components）

dependencies:
  espressif/esp_lvgl_port: "^2.4.0"
  espressif/led_indicator: "^1.2.0"

esp_lvgl_port
led_indicator

快速指南

如何在 ESP-IDF 中使用 ESP Component Registry

从 ESP-IDF v4.4 开始，并在 v5.x 及以后版本中趋于成熟，乐鑫采用了由 IDF Component Manager 管理的模块化包架构。不用再处理复杂的 git 子模块：现在只需在项目的 idf_component.yml 清单文件中声明所需的库。

自动安装，彼此解耦
在执行 'idf.py build' 或 'idf.py reconfigure' 时，编译系统会自动下载、编译并管理库的版本。
严格的语义化版本
通过版本运算符精确控制何时更新（^ 表示兼容次版本，~ 表示补丁版本，也可以固定为精确版本）。
项目更轻量、更整洁
项目仓库保持干净，Git 历史中不会混入第三方代码。
面向企业或社区的共享
可以把你自己的组件发布到乐鑫的公共云，也可以发布到公司内部的私有注册中心。

基本命令

$ idf.py add-dependency "espressif/esp_lvgl_port^2.4.0"
自动创建或更新 'main/idf_component.yml' 文件，并加入指定的依赖。
$ idf.py reconfigure
强制 CMake 和 Component Manager 重新解析依赖树，并下载尚未获取的包。
$ compote component upload --name meu_driver_sensor --namespace minhadiv
使用官方的 Compote CLI 工具，把你的开源或专有组件发布到 ESP Component Registry。

ESP-IDF 中的语义化版本

^1.2.0：接受次版本更新和修复（1.2.1、1.3.0），但会阻止重大 API 变更（2.0.0）。推荐。
~1.2.0：只接受缺陷修复（1.2.1、1.2.5）。
1.2.0：锁定到精确版本。
*：接受任意版本。生产环境请避免。

ESP Component Registry

类别

兼容芯片

42 个组件

esp_lvgl_port

lvgl

esp32_display_panel

esp_lcd_touch

esp_lcd_touch_gt911

esp_lcd_touch_ft5x06

esp_jpeg

esp_rainmaker

mesh_lite

esp_modbus

net_connect

esp_hosted

esp-now

esp-sr

esp_codec_dev

es8311

esp32-camera

esp-dsp

esp-nn

esp-matter

esp-zigbee-lib

esp_rcp_update

led_indicator

button

led_strip

esp_tinyusb

w5500

ch390

usb_host_uvc

sensor_hub

bmi270_sensor

ds18b20

scd4x

esp-box-3

esp32_s3_korvo_2

esp32_s3_eye

m5stack_core_s3

esp32_p4_wifi6_touch_lcd_7b

littlefs

esp-idf-cxx

cbor

esp_websocket_client

你的 idf_component.yml

如何在 ESP-IDF 中使用 ESP Component Registry

自动安装，彼此解耦

严格的语义化版本

项目更轻量、更整洁

面向企业或社区的共享

基本命令

ESP-IDF 中的语义化版本