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 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。
配置 ESP-IDF 开发环境
ESP32-P4 Platform 示例主要面向 ESP-IDF release/v5.4 及后续版本维护。建议使用 ESP-IDF v5.5.4；个别高级 UI 示例的兼容版本请以示例目录中的 README 为准。
以下内容以 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 环境,无需手动配置。
ESP32-P4 Platform 示例仓库
ESP32-P4 系列基础板的 ESP-IDF 示例统一维护在 ESP32-P4-Platform 仓库。仓库中的 examples/esp-idf/ 为独立 ESP-IDF 工程，config/ 提供 ESP32-P4 芯片版本配置覆盖文件，docs/ 提供示例选择、芯片版本配置和排查说明。
示例按从板卡验证到综合应用的顺序编号。初次使用时，先运行 00_board_check，确认烧录、串口监视器、PSRAM 和运行日志正常，再根据外设选择对应示例。
支持板卡
以下板卡使用 ESP32-P4-Platform 仓库中的示例程序。图片链接指向对应产品页面。
| ESP32-P4-NANO | ESP32-P4-Module-DEV-KIT | ESP32-P4-WIFI6-DEV-KIT | ESP32-P4-WIFI6 |
|---|---|---|---|
 |  |  |  |
| 产品页 | 产品页 | 产品页 | 产品页 |
| ESP32-P4-ETH | ESP32-P4-Pico | ESP32-P4-WIFI6-POE-ETH | ESP32-P4-Core-DEV-KIT |
|---|---|---|---|
 |  |  |  |
| 产品页 | 产品页 | 产品页 | 产品页 |
快速运行
以下命令以 00_board_check 为例。将 PORT 替换为实际串口号，例如 Windows 下的 COM5。
git clone https://github.com/waveshareteam/ESP32-P4-Platform.git
cd ESP32-P4-Platform/examples/esp-idf/00_board_check
idf.py set-target esp32p4
idf.py build
idf.py -p PORT flash monitor
ESP-IDF 示例运行前必须先构建并烧录。idf.py build 会生成可烧录固件；idf.py -p PORT flash monitor 会烧录固件并打开串口监视器。若修改了 menuconfig 或源码，需要重新构建后再烧录。
不同示例可能需要先配置引脚、Wi-Fi 凭据、Ethernet PHY、显示屏、摄像头或示例参数。运行这类示例前，请结合示例 README、板卡原理图和实际连接情况，在构建前执行：
idf.py menuconfig
ESP32-P4 芯片版本配置
ESP32-P4 rev v3.0 之前的工程样品与 rev v3.0 及之后的芯片，在 ESP-IDF 中使用不同的构建配置。若烧录或启动时出现类似 requires chip revision in range [v3.1 - v3.99] (this chip is revision v1.3) 的提示，请不要使用 --force 跳过检查，应按实际芯片版本重新构建。
在示例目录中执行以下命令之一：
| 芯片版本 | 配置文件 | 构建命令 |
|---|---|---|
| rev v3.1 或之后 | ../../../config/esp32p4_rev_v3_1.defaults | idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;../../../config/esp32p4_rev_v3_1.defaults" set-target esp32p4 build |
| rev v3.0 或之后 | ../../../config/esp32p4_rev_v3_0.defaults | idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;../../../config/esp32p4_rev_v3_0.defaults" set-target esp32p4 build |
| rev v0.x / v1.x 工程样品 | ../../../config/esp32p4_rev_pre_v3.defaults | idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults;../../../config/esp32p4_rev_pre_v3.defaults" set-target esp32p4 build |
切换芯片版本配置后，建议删除示例目录中的 sdkconfig，或为不同芯片版本使用独立的 SDKCONFIG 文件。已有 sdkconfig 会覆盖 sdkconfig.defaults 中的默认配置。
ESP-IDF 示例索引
| 编号 | 示例目录 | 用途 | 备注 |
|---|---|---|---|
| 00 | 00_board_check | 板卡、烧录、串口、PSRAM 和堆内存检查 | 无需外接硬件 |
| 01 | 01_HowToCreateProject | 最小 ESP-IDF 工程结构 | 适合查看工程目录组成 |
| 02 | 02_HelloWorld | 基础日志、芯片信息和重启倒计时 | 基础环境检查 |
| 03 | 03_nvs_counter | 使用 NVS 保存启动计数 | 无需外接硬件 |
| 04 | 04_freertos_tasks | FreeRTOS 任务和队列 | 无需外接硬件 |
| 05 | 05_gpio_io | GPIO 输入输出 | 可接跳线或 LED |
| 06 | 06_gpio_interrupt | GPIO 中断和消抖 | 建议接按键或跳线 |
| 07 | 07_uart_loopback | UART 发送和回环接收 | 建议接 TX/RX 跳线 |
| 08 | 08_i2c_tools | I2C 扫描与命令行调试 | 可用于检查 I2C 设备地址 |
| 09 | 09_sdmmc | SD 卡挂载和读写测试 | 需要 SD 卡和对应卡槽或接线 |
| 10 | 10_wifistation | Wi-Fi STA 连接 | 需要带 Wi-Fi 支持的板卡 |
| 11 | 11_ethernetbasic | Ethernet 链路和 DHCP 获取 IP | 需要 Ethernet PHY 和网口 |
| 12 | 12_I2SCodec | I2S Codec 音频播放或回声模式 | 需要音频 Codec / 喇叭 / 麦克风支持 |
| 13 | 13_Displaycolorbar | LCD 色条显示 | 用于显示屏点亮检查 |
| 14 | 14_lvgl_demo_v9 | LVGL v9 图形界面示例 | 需要显示屏和 PSRAM |
| 15 | 15_eth2ap | Ethernet 到 Wi-Fi AP 网络示例 | 需要 Ethernet 与 Wi-Fi 路径 |
| 16 | 16_video_lcd_display | 摄像头画面显示到 LCD | 需要摄像头、显示屏和 PSRAM |
| 17 | 17_simple_video_server | HTTP 摄像头视频流 | 需要摄像头和网络连接 |
| 18 | 18_esp_brookesia_phone | ESP-Brookesia Phone UI | 需要匹配的显示、触摸和板级配置 |
| 19 | 19_system_monitor | 串口诊断和运行状态监视 | 无需外接硬件 |
示例代码与配置入口
大多数示例的业务代码位于 main/，可配置项位于 main/Kconfig.projbuild、sdkconfig.defaults 或组件目录的 Kconfig。修改引脚、网络、显示屏、摄像头或音频参数时，优先通过 idf.py menuconfig 修改；需要固化到仓库时，再保存到对应示例的默认配置文件。
| 示例 | 主要代码入口 | 配置入口 | 运行前检查 |
|---|---|---|---|
00_board_check | main/board_check_main.c | sdkconfig.defaults | 查看串口日志中的芯片信息、PSRAM、堆内存和周期性 alive 输出。 |
01_HowToCreateProject | main/main.c | 根目录与 main/CMakeLists.txt | 适合复制工程结构；新增组件时同步检查 CMakeLists.txt。 |
02_HelloWorld | main/hello_world_main.c | sdkconfig.defaults | 用于检查 ESP-IDF 环境、串口输出和重启流程。 |
03_nvs_counter | main/nvs_counter_main.c | sdkconfig.defaults | 运行后会在 NVS 中保存计数；清除 Flash 后计数会重置。 |
04_freertos_tasks | main/freertos_tasks_main.c | sdkconfig.defaults | 用于查看任务、队列和周期日志，不依赖外接硬件。 |
05_gpio_io | main/gpio_io_main.c | main/Kconfig.projbuild：EXAMPLE_GPIO_OUTPUT、EXAMPLE_GPIO_INPUT、EXAMPLE_GPIO_INPUT_PULLUP | 按原理图确认 GPIO 未被板载外设占用。 |
06_gpio_interrupt | main/gpio_interrupt_main.c | main/Kconfig.projbuild：EXAMPLE_GPIO_INPUT、EXAMPLE_GPIO_INPUT_PULLUP、EXAMPLE_DEBOUNCE_MS | 输入脚建议接按键或跳线；根据按键电路设置上拉和消抖时间。 |
07_uart_loopback | main/uart_loopback_main.c | main/Kconfig.projbuild：EXAMPLE_UART_PORT_NUM、EXAMPLE_UART_TX_GPIO、EXAMPLE_UART_RX_GPIO、EXAMPLE_UART_BAUD_RATE | 将 TX 与 RX 对接后再运行，避免占用下载串口。 |
08_i2c_tools | main/i2ctools_example_main.c、main/cmd_i2ctools.c | main/Kconfig.projbuild：EXAMPLE_I2C_MASTER_SCL、EXAMPLE_I2C_MASTER_SDA、EXAMPLE_STORE_HISTORY | ESP32-P4 默认 SCL 为 GPIO8、SDA 为 GPIO7；接外设前确认电平和上拉。 |
09_sdmmc | main/sd_card_example_main.c、components/sd_card/sd_test_io.c | main/Kconfig.projbuild：总线宽度、EXAMPLE_PIN_CMD、EXAMPLE_PIN_CLK、EXAMPLE_PIN_D0 至 EXAMPLE_PIN_D3、格式化选项、LDO IO | ESP32-P4 默认 CMD/CLK/D0/D1/D2/D3 为 GPIO44/43/39/40/41/42；启用格式化选项会清除 SD 卡数据。 |
10_wifistation | main/station_example_main.c | main/Kconfig.projbuild：ESP_WIFI_SSID、ESP_WIFI_PASSWORD、认证阈值、重试次数 | ESP32-P4 本身不集成 Wi-Fi，需使用带 ESP32-C6 或等效 Wi-Fi 路径的板卡。 |
11_ethernetbasic | main/ethernet_example_main.c、components/ethernet_init/ethernet_init.c | main/Kconfig.projbuild、components/ethernet_init/Kconfig.projbuild：PHY 型号、PHY 地址、MDC、MDIO、复位脚、内部 EMAC 或 SPI Ethernet | ESP32-P4 内部 EMAC 默认 MDC 为 GPIO31、MDIO 为 GPIO52、PHY Reset 为 GPIO51；不同板卡按原理图修改。 |
12_I2SCodec | main/i2s_es8311_example.c、main/example_config.h、main/canon.pcm | main/Kconfig.projbuild：播放 / 回声模式、MIC 增益、音量、EXAMPLE_BSP；BSP 依赖见 main/idf_component.yml | 回声模式依赖麦克风输入；启用 BSP 前确认所选板级组件与硬件匹配。 |
13_Displaycolorbar | main/test_esp_lcd_jd9365.c | main/idf_component.yml、sdkconfig.defaults、sdkconfig.defaults.esp32p4 | 先用于点亮 LCD；若日志正常但屏幕无显示，检查背光、复位、电源和屏幕型号。 |
14_lvgl_demo_v9 | main/main.c、components/bsp_extra/src/bsp_board_extra.c | main/idf_component.yml、components/bsp_extra/idf_component.yml、components/bsp_extra/Kconfig、sdkconfig.defaults | 先运行 13_Displaycolorbar；再检查 LVGL 缓冲区、分辨率、触摸控制器和 PSRAM。 |
15_eth2ap | main/ethernet_example_main.c | main/Kconfig.projbuild：EXAMPLE_WIFI_SSID、EXAMPLE_WIFI_PASSWORD、EXAMPLE_WIFI_CHANNEL、EXAMPLE_MAX_STA_CONN | 需要同时具备 Ethernet 和 Wi-Fi 路径；运行前确认网口链路和 AP 参数。 |
16_video_lcd_display | main/main.c、main/app_video.c | sdkconfig.defaults：MIPI-CSI SCCB SCL/SDA、OV5647、LVGL、PSRAM、CONFIG_BSP_LCD_DPI_BUFFER_NUMS；摄像头传感器在 Component config 中选择 | 默认 SCCB SCL 为 GPIO8、SDA 为 GPIO7；需连接 MIPI-CSI 摄像头和 LCD。 |
17_simple_video_server | main/simple_video_server_example.c、components/example_video_common/、frontend/ | main/Kconfig.projbuild：视频缓冲、JPEG 质量、mDNS；components/example_video_common/Kconfig.projbuild：网络、板级、摄像头接口、SCCB I2C、JPEG 编码器 | 需要摄像头和网络连接；烧录后按串口日志中的 IP 访问网页界面，也可在支持 mDNS 的网络中访问 http://esp-web.local。前端源码要求 Node.js 20 及以上；仓库已包含压缩后的网页资源，普通固件构建不需要先构建前端。 |
18_esp_brookesia_phone | main/main.cpp、components/esp32_p4_platform/、components/brookesia_* | components/esp32_p4_platform/Kconfig：Board Support Package(ESP32-P4) > Display > Select LCD type、色彩格式、I2C、I2S、SD、SPIFFS | 示例 README 以 1024 x 600 UI 样式为原型；移植到不同 Waveshare DSI 屏时先选择 LCD 类型和色彩格式。 |
19_system_monitor | main/system_monitor_main.c | sdkconfig.defaults | 串口控制台提供 help、info、heap、period <ms> 等命令；period 会写入 NVS。 |
兼容性参考
✅ 表示该示例预期可在对应板卡运行，❌ 表示缺少示例所需外设或当前示例未覆盖该板卡路径。运行前仍需按实际硬件修改 menuconfig。
| 编号 | 示例 | ESP32-P4-NANO | ESP32-P4-Module-DEV-KIT | ESP32-P4-WIFI6-DEV-KIT | ESP32-P4-WIFI6 | ESP32-P4-ETH | ESP32-P4-Pico | ESP32-P4-WIFI6-POE-ETH | ESP32-P4-Core-DEV-KIT |
|---|---|---|---|---|---|---|---|---|---|
| 00 | board_check | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 01 | HowToCreateProject | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 02 | HelloWorld | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 03 | nvs_counter | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 04 | freertos_tasks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 05 | gpio_io | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 06 | gpio_interrupt | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 07 | uart_loopback | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 08 | i2c_tools | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 09 | sdmmc | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| 10 | wifistation | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ |
| 11 | ethernetbasic | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ |
| 12 | I2SCodec | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| 13 | Displaycolorbar | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 14 | lvgl_demo_v9 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 15 | eth2ap | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
| 16 | video_lcd_display | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 17 | simple_video_server | ✅ | ✅ | ✅ | ✅ | ✅(Ethernet) | ❌ | ✅ | ❌ |
| 18 | esp_brookesia_phone | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 19 | system_monitor | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
构建与运行提示
- ESP32-P4 芯片本身不集成 Wi-Fi / Bluetooth。Wi-Fi 相关示例需要板载 ESP32-C6 或其他已配置的 Wi-Fi 伴随方案。
- Ethernet 示例需要板载或外接 Ethernet PHY。若网口、PHY 型号、PHY 地址、MDC/MDIO GPIO 或复位 GPIO 与示例默认值不同，请在
menuconfig中修改。 ESP32-P4-Core-DEV-KIT在 Platform 兼容性矩阵中不覆盖 SDMMC、Wi-Fi、Ethernet、I2S Codec、eth2ap和simple_video_server。如需验证相关外设，需外接对应硬件并按原理图调整示例配置。- 显示、LVGL、摄像头和 ESP-Brookesia 示例通常需要 PSRAM。先运行
00_board_check确认 PSRAM 初始化正常。 - 部分示例通过
idf_component.yml下载 ESP-IDF managed components。若构建停在组件下载阶段，请检查网络、Git 代理和 ESP-IDF 组件管理器配置。 05_gpio_io、06_gpio_interrupt、07_uart_loopback等基础接口示例可能与板载外设占用的 GPIO 冲突。运行前请按原理图确认引脚。