ESP-IDF 开发
本章节包含以下内容，请按需阅读：
ESP-IDF 入门教程
初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。
- 第0节 认识 ESP32
- 第1节 搭建环境
- 第2节 运行实例
- 第3节 创建项目
- 第4节 使用组件
- 第5节 调试程序
- 第6节 FreeRTOS
- 第7节 驱动外设
- 第8节 Wi-Fi 编程
- 第9节 BLE 编程
请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。
配置开发环境
以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。
此部分图示以安装 ESP-IDF V5.5.2 为例示范，安装时请选用与您开发板示例匹配的 ESP-IDF 版本。
安装 ESP-IDF 开发环境
-
前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。
在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本（图示仅为参考，请以实际为准）。
确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 ESP-IDF 离线整合包(.zst)，另一个是 ESP-IDF 安装器(.exe)。
请耐心等待两个文件下载完成。
-
下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。
启动后，可在右上角将界面语言切换为中文。
安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。
接下来，选择安装路径。建议使用默认路径；若需自定义，请确保路径中不包含中文或空格。确认无误后，点击 开始安装。
-
当看到如下界面时，表示 ESP-IDF 已安装成功。
-
建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。
安装 Visual Studio Code 与 ESP-IDF 扩展
-
下载并安装 Visual Studio Code。
-
安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。
-
在 VS Code 中,点击侧边活动栏中的
扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。 -
在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。
-
当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。
ESP-IDF 示例程序
本目录包含 ESP32-C5-Pico 的 ESP-IDF 示例工程。工程当前配置的目标芯片为 esp32c5，Flash 容量为 4 MB。
使用前准备
- 安装并初始化支持 ESP32-C5 的 ESP-IDF。建议使用 ESP-IDF 6.0.2。
- 以 ESP-IDF 已初始化的终端打开任意示例目录。
- 将开发板通过 USB 连接电脑，确认其串口号，例如 Windows 下的
COM5。
每个示例均为独立工程。进入相应目录后执行：
idf.py set-target esp32c5
idf.py build
idf.py -p COM5 flash monitor
请将 COM5 替换为实际串口号。退出串口监视器请按 Ctrl-]。首次构建时，组件管理器会自动下载工程声明的依赖，因此需要网络连接。
示例程序
01_HelloWorld
本示例在串口打印 Hello world!、芯片特性、Flash 容量和最小可用堆内存；随后每秒输出一次重启倒计时，倒计时结束后自动重启。可用于确认 ESP-IDF 环境、烧录链路和串口监视器工作正常。
02_RGB
本示例驱动板载可寻址 RGB 灯珠。当前 sdkconfig 选择 RMT 驱动方式，数据引脚为 GPIO27，闪烁周期为 1000 ms。灯珠点亮时的 RGB 值为 (16, 16, 16)。
03_UART
本示例使用 UART1 进行异步收发。发送任务每隔 2 秒发送字符串 Hello waveshare；接收任务持续读取并把收到的数据输出到串口监视器。
硬件连接
将 GPIO4 与 GPIO5 短接，形成自发自收回环：
| ESP32-C5-Pico | ESP32-C5-Pico（同一块开发板） |
|---|---|
| GPIO4（UART1 TX） | GPIO5（UART1 RX） |
当前通信参数为 115200 bps、8 数据位、无校验、1 停止位、无硬件流控。可在 main/Kconfig.projbuild 或 idf.py menuconfig 中调整波特率和任务栈大小；GPIO4、GPIO5 在源码中直接定义。
04_WIFI
本示例连接 Wi-Fi 后，通过 HTTP 请求心知天气 API，获取北京的实时天气数据并将服务器响应输出到串口。一次请求完成后等待 30 分钟，再发起下一次请求。
烧录前执行 idf.py menuconfig，在 Example Connection Configuration 中填写 Wi-Fi 的 SSID 和密码。开发板连接 2.4 GHz 网络时，请确认路由器已启用对应频段。
注意：示例中的天气 API 地址、位置和访问密钥在
main/main.c中固定，且使用明文 HTTP。用于产品或公开网络前，应替换为自己的密钥，并使用 HTTPS、证书校验及安全的密钥管理方式。
05_Bluetooth
本示例启动 BLE GATT Server，广播名称为 ESP_GATTS_DEMO，等待手机或其他 BLE GATT Client 连接。服务包含两个 16 位 UUID：
| 服务 UUID | 特征 UUID | 功能 |
|---|---|---|
0x00FF | 0xFF01 | 读、写、通知、指示 |
0x00EE | 0xEE01 | 读、写、通知 |
使用手机 BLE 调试工具 扫描并连接 ESP_GATTS_DEMO 后，可读取或写入数据。
06_TCA9554_IO_Expander
本示例演示通过 I2C 控制 TCA9554 八位 GPIO 扩展器，使用 espressif/esp_io_expander_tca9554 组件。I2C0 的 SDA 为 GPIO23、SCL 为 GPIO24，器件地址配置为 0x20。
程序将 TCA9554 的 P0、P1 配置为输出，将 P2、P3 配置为输入；P0、P1 每 500 ms 在高低电平间切换，并输出 P2、P3 的当前状态。
07_1.83inch_Touch_LCD_LVGL
本示例驱动 1.83 英寸触摸 LCD，使用 ST7789 显示控制器和 CST816 触摸控制器，并基于 LVGL 9 显示三张图片。左右滑动屏幕可循环切换图片。
显示分辨率为 240 × 284，显示接口为 SPI2，像素时钟为 40 MHz；触摸接口为 I2C0，频率为 400 kHz。工程依赖 esp_lvgl_port、esp_lcd_touch_cst816s 和 lvgl，会在首次构建时由组件管理器获取。
屏幕连接
| 功能 | ESP32-C5-Pico GPIO |
|---|---|
| LCD SCLK | GPIO7 |
| LCD MOSI | GPIO8 |
| LCD CS | GPIO9 |
| LCD DC | GPIO10 |
| LCD RST | GPIO15 |
| LCD 背光 | GPIO25 |
| 触摸 I2C SCL | GPIO24 |
| 触摸 I2C SDA | GPIO23 |
| 触摸 INT | GPIO5 |
| 触摸 RST | GPIO26 |
该工程的屏幕和触摸引脚在 main/lcd_driver/lcd_driver.h 与 main/touch_driver/touch_driver.h 中定义。使用不同屏幕或接线时，请先修改这些定义，再重新构建烧录。
常见问题
- 无法烧录或找不到串口：检查 USB 数据线、设备管理器中的串口号，以及开发板是否进入下载模式。
- 构建目标错误：在示例根目录重新执行
idf.py fullclean和idf.py set-target esp32c5，再构建。 - 组件下载失败：检查网络连接和 ESP-IDF Component Manager 配置后重试。
- UART 无接收数据：确认 GPIO4 与 GPIO5 已短接，且不要把它们接到其他外设。
- Wi-Fi 无法连接：核对 SSID、密码及 2.4 GHz 网络可用性；串口日志会给出连接失败原因。