开始前适用开发板：ESP32-P4 + ESP32-C5 · 开发框架：ESP-IDF
例程目录
P4_C5_4.3_Firmware/— 淘宝 拍下 P4C5 板 后 联系客服，百度网盘 发全套资料
视频系列 P：文档总目录与视频教程大纲
硬件介绍见 ESP32P4-C5开发板介绍
面向第一次接触 ESP32-P4 或本开发板的用户。按章节顺序阅读，约 2～4 小时 可完成环境搭建、验板与第一个 LVGL 界面。
一、拿到板子后先做什么
1.0 获取例程（必读）
- 淘宝 酷世DIY 购买 P4C5 开发板
- 下单后联系客服，索取例程资料
- 客服通过 百度网盘 发送压缩包（含
P4_C5_4.3_Firmware/及说明） - 解压到无中文路径（如
D:\Firmware\）
1.1 开箱检查
| 序号 | 物品 | 检查项 |
|---|---|---|
| 1 | ESP32P4-C5 4.3寸触摸屏开发板 | 屏幕无裂痕、排针无弯折 |
| 2 | USB Type-C 数据线 | 必须是数据线（非纯充电线） |
| 3 | TF 卡（视套餐） | 多媒体例程需要，FAT32 格式 |
| 4 | 例程资料 | 淘宝下单后 联系客服，百度网盘 发链接（非公开下载） |
1.2 上电验板（无需编程）
若出厂已烧录 p4c5_board_test 固件：
- USB 连接板子 Type-C 与电脑
- 等待约 3 秒，屏幕自动亮起
- 出现 NODE P4 赛博风格界面 表示正常
1.3 第一次自己编译烧录
# 百度网盘下载解压后（路径不要含中文）
cd D:\Firmware\P4_C5_4.3_Firmware\04.advanced.p4c5_board_test
idf # Windows PowerShell 导入 IDF 环境
idf.py set-target esp32p4 # 首次必须执行
idf.py build
idf.py -p COM15 flash monitor # COM 口改成你的实际端口
成功标志：编译无 ERROR；烧录 100%；串口有 KSDIY_TEST 等日志；屏幕显示 NODE P4 界面。
1.4 板级测试功能导航
| 入口 | 功能 |
|---|---|
| 主界面 | 硬件健康度、频谱动画 |
| 硬件检测 | AXP / ES8311 / ES7210 / GPIO 按键 / I2C |
| Wi-Fi 扫描 | C5 扫描周边 AP |
| MIPI CSI | SC2336 相机预览（需安装传感器） |
| USB 相机 | UVC 预览（需 USB Host 接相机） |
| IMU | LSM6DS3 加速度/角速度 |
| 语音 | ES7210 + 唤醒词演示 |
逐项进入，绿色/OK 表示该项硬件正常。
二、例程仓库结构
P4_C5_4.3_Firmware/
├── 01.basic.* 基础外设
├── 02.beginner.* 屏幕/Wi-Fi/USB/SD/音频入门
├── 03.development.* LVGL/USB/MP3/PPA 等
├── 04.advanced.* 摄像头/AVI/AI/相册
├── 04.application.* 智能面板/天气时钟等
├── 05.test.* 硬件专项测试
├── 06.gmf_examples GMF 多媒体框架
├── components/ 核心 BSP、屏幕驱动、PMIC…
├── components_audio/ 音频、SkaiNet
├── components_camera/ CSI、UVC、视觉
└── components_cellular/ 4G 模组
共 108 个独立 ESP-IDF 工程。每个子目录切换时需 cd 进去再 idf.py build，不要混用 build 目录。
三、为什么每个例程都能在屏上显示？
即使 01.basic.gpio 也会在 4.3 寸屏显示状态，因为所有例程共享 ksdiy_p4c5_bsp 组件：
nvs_flash_init();
ksdiy_lvgl_port_init(); // 内部：AXP 上电 → MIPI DSI → 触摸 → LVGL 9
之后用 LVGL 标准 API 画界面，操作前加锁：
if (ksdiy_lvgl_lock(100)) {
lv_obj_t *label = lv_label_create(lv_scr_act());
lv_label_set_text(label, "Hello P4C5");
lv_obj_center(label);
ksdiy_lvgl_unlock();
}
在自己的空白工程里也可通过在线组件使用，见 P4C5在线组件使用说明。
四、分级学习路线
路线总图
┌─────────────────────┐
│ 04.advanced.* │
│ 综合项目 / 产品级 │
└──────────▲──────────┘
│
┌──────────┴──────────┐
│ 03.development.* │
│ LVGL / USB / 音频 │
└──────────▲──────────┘
│
┌──────────┴──────────┐
│ 02.beginner.* │
│ 屏/卡/Wi-Fi/USB │
└──────────▲──────────┘
│
┌──────────┴──────────┐
│ 01.basic.* │
│ GPIO/UART/I2C/RTOS │
└──────────▲──────────┘
│
┌──────────┴──────────┐
│ p4c5_board_test │
│ 验板 & 熟悉硬件 │
└─────────────────────┘
阶段 0：验板（必做）
| 工程 | 时间 | 目标 |
|---|---|---|
04.advanced.p4c5_board_test | 0.5 天 | 确认硬件 OK，熟悉 UI 导航 |
阶段 1：C 语言 + FreeRTOS 基础
| 顺序 | 工程 | 你将学会 |
|---|---|---|
| 1 | 01.basic.hello_world | 工程结构、日志 |
| 2 | 01.basic.blink / gpio | GPIO（WS2812 + 外接 LED） |
| 3 | 01.basic.uart_echo | 串口调试 |
| 4 | 01.basic.i2c | I2C 扫描 |
| 5 | 01.basic.adc_oneshot | ADC 采样 |
| 6 | 01.basic.ledc_pwm | PWM |
| 7 | 01.basic.gptimer | 硬件定时器 |
| 8 | 01.basic.rmt_led_strip | RMT 驱动 WS2812 |
| 9 | 01.basic.nvs | 非易失存储 |
| 10 | 01.basic.spiffs / fatfs / littlefs | 三种文件系统 |
| 11 | 01.basic.freertos | 多任务/队列/信号量 |
| 12 | 01.basic.deep_sleep | 低功耗与唤醒 |
阶段 2：屏幕 + 存储 + 音频
| 顺序 | 工程 | 你将学会 |
|---|---|---|
| 1 | 02.beginner.mipi_lcd_touch | MIPI + 触摸 + LVGL 最小系统 |
| 2 | 03.development.lvgl_esp_adapter | esp_lvgl_adapter 标准用法 |
| 3 | 03.development.lvgl_esp_adapter_rotate | 屏幕旋转 0°/90°/180°/270° |
| 4 | 02.beginner.sdmmc_sd | TF 卡读写 |
| 5 | 03.development.lvgl_sdcard_jpg | TF 卡 JPG 显示 |
| 6 | 02.beginner.i2s_codec | 板载音频播放/录音 |
阶段 3：联网（理解 P4 + C5 双芯）
| 顺序 | 工程 | 你将学会 |
|---|---|---|
| 1 | 05.test.wifi_scan_c5 | 最小 Wi-Fi 扫描 |
| 2 | 02.beginner.wifi_station | 连接路由器 |
| 3 | 02.beginner.wifi_softap | 板子开热点 |
| 4 | 02.beginner.http_request | HTTP API |
| 5 | 02.beginner.http_server | 板载 Web 服务 |
| 6 | 02.beginner.mqtt_tcp | MQTT |
| 7 | 02.beginner.ota | OTA 升级 |
| 8 | 02.beginner.ble_spp_server | BLE 透传 |
双芯要点：
- 应用跑在 P4，Wi-Fi API 与 S3 相同
- 底层 C5 + esp_hosted，log 可见
esp_wifi_remote - 首次联网等 C5 就绪（10～20 秒）
阶段 4：USB 与外设
| 顺序 | 工程 | 你将学会 |
|---|---|---|
| 1 | 02.beginner.usb_cdc | USB 虚拟串口 |
| 2 | 02.beginner.usb_msc_flash | 板子当 U 盘 |
| 3 | 02.beginner.usb_msc_ram | RAM 虚拟 U 盘 |
| 4 | 02.beginner.usb_hid_keyboard | HID 键盘 |
| 5 | 02.beginner.usb_hid_mouse | HID 鼠标 |
| 6 | 05.test.usb_uvc_display | USB 摄像头 → 屏幕 |
| 7 | 03.development.usb_cdc_msc | CDC + MSC 复合 |
| 8 | 03.development.usb_wireless_disk | 无线 + U 盘 |
详见 USB功能实现
阶段 5：多媒体与视觉（P4 强项）
| 顺序 | 工程 | 你将学会 |
|---|---|---|
| 1 | 04.advanced.avi_player | 硬件 JPEG 解 AVI |
| 2 | 04.advanced.avi_multi_player | 多路 AVI 轮播 |
| 3 | 04.advanced.avi_recorder | CSI 采集 + AVI 录制 |
| 4 | 04.advanced.mjpeg_album | 相册 + Wi-Fi 投屏 UI |
| 5 | 03.development.mp3_player | MP3 播放 |
| 6 | 03.development.audio_fft | 实时 FFT 频谱 |
| 7 | 04.advanced.spectrum_box_lite | 频谱可视化 |
| 8 | 04.advanced.camera_lvgl_display | 相机 LVGL 预览 |
| 9 | 04.advanced.qrcode_detection | 二维码 |
| 10 | 04.advanced.face_recognition | 人脸识别 |
| 11 | 03.development.p4c5_ppa_display | PPA 图像加速演示 |
TF 卡目录结构：
/sdcard/videos/ ← MJPEG 编码的 .avi
/sdcard/photos/ ← .jpg / .jpeg
/sdcard/music/ ← .mp3
阶段 6：综合项目（进阶选做）
| 工程 | 适合人群 |
|---|---|
04.advanced.esp-album-ksdiy | 电子相册 + HTTP 上传 |
04.advanced.xiaozhi_chat-ksdiy / xiaozhi_ksdiy-p4c5 | AI 语音助手 |
04.advanced.usb_extended_display | USB 副屏 |
04.advanced.esp_claw_p4c5 | AI Agent 框架 |
04.application.ksdiy_smart_panel | 智能面板成品向 |
ESP32P4_lcd_lvgl_sim | PC 上 LVGL 仿真（无需硬件） |
五、软件架构（进阶必读）
5.1 显示栈
你的 LVGL UI
↓ ksdiy_lvgl_lock / unlock
esp_lvgl_adapter（LVGL 9）
↓
esp_lcd ST7102 MIPI 驱动
↓
MIPI DSI → 4.3 寸屏
触摸：ST7123 → LVGL indev
5.2 音频栈
WAV/PCM/AVI 音频轨 → audio_decoder / I2S → ES8311/ES7210 → 喇叭/麦克风
5.3 Wi-Fi 栈
你的 app → esp_wifi_* API → esp_wifi_remote → esp_hosted SDIO → ESP32-C5
5.4 视频解码栈
TF 卡 AVI → avi_parser → P4 硬件 JPEG + PPA 缩放 → esp_lcd / LVGL
六、日常开发工作流
cd P4_C5_4.3_Firmware\03.development.lvgl_v9
idf.py build flash monitor
| 命令 | 用途 |
|---|---|
idf.py menuconfig | 改 COM 口、分区、ESP-Hosted 等 |
idf.py fullclean | 清 build 后重编 |
idf.py build app-flash | 只烧 app 分区 |
读 log：I=正常，W=警告，E=错误，panic=严重错误需复制完整 backtrace。
⚠️ 勿运行仓库中的 build kill.bat（会删 build/.clangd/.vscode）；清理 clangd 索引用 clangd_kill.bat。
七、验板失败排查
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 找不到 COM 口 | 纯充电线、驱动未装 | 换数据线，装 USB 串口驱动 |
| 烧录失败 | 端口占用 | 关闭其他串口工具 |
| 屏幕不亮 | 未烧录成功 | 重新 flash，看 AXP 初始化 log |
| Wi-Fi 扫描为空 | C5 未就绪 | 等 10～20 秒，查 esp_hosted log |
| 音频报错 | Codec 未检测到 | 硬件检测页对比 I2C 设备 |
八、常见问题 FAQ
Q1：屏幕亮了但触摸没反应？
确认使用 ksdiy_lvgl_port_init()；查 ST7123 初始化 log；跑板级测试硬件检测页。
Q2：Wi-Fi 连不上？
等 C5 初始化（Transport active）；改 SSID/密码；先用 05.test.wifi_scan_c5。
Q3：TF 卡读不到？
FAT32 格式；先跑 02.beginner.sdmmc_sd。
Q4：AVI 无画面或卡顿？
确认 MJPEG 编码 AVI；文件放 /sdcard/videos/；分辨率建议 ≤ 800×1280。
Q5：编译找不到组件？
idf.py fullclean
idf.py set-target esp32p4
idf.py build
需联网下载 managed_components/。
Q6：可以用 Arduino IDE 吗？
本例程基于 ESP-IDF，暂不支持 Arduino IDE。
九、30 天学习计划
| 天数 | 内容 | 产出 |
|---|---|---|
| Day 1 | 环境 + p4c5_board_test | 验板截图 |
| Day 2～3 | 01.basic 选读 | 理解基础外设 |
| Day 4～5 | mipi_lcd_touch + lvgl_v9 | 自建 Label/Button |
| Day 6～7 | sdmmc + lvgl_sdcard_jpg | TF 卡相册 |
| Day 8～9 | i2s_codec + mp3 + fft | 音频 + 频谱 |
| Day 10～12 | wifi + http + mqtt | 联网显示 |
| Day 13～14 | usb_cdc + usb_hid | USB 体验 |
| Day 15～17 | lvgl 组件选 3 个 | 丰富 UI |
| Day 18～20 | avi_player + mjpeg_album | 视频播放 |
| Day 21～23 | camera / qrcode / face 选做 | 视觉 |
| Day 24～30 | 自选 advanced 项目 | 完整小作品 |
十、推荐按兴趣快速入门
| 我想做什么 | 推荐例程 |
|---|---|
| 先验证板子 | 04.advanced.p4c5_board_test |
| 学 GPIO | 01.basic.blink |
| USB 键盘 | 02.beginner.usb_hid_keyboard |
| 连 Wi-Fi | 02.beginner.wifi_station |
| 播放 MP3 | 03.development.mp3_player |
| 音频频谱 | 04.advanced.spectrum_box_lite |
| 摄像头 | 04.advanced.camera_lvgl_display |
| AI 对话 | 04.advanced.xiaozhi_chat-ksdiy |
| 电子相册 | 04.advanced.esp-album-ksdiy |
十一、扩展专题与单例程教程
| 文档 | 内容 |
|---|---|
| 热门例程详解 | P4C5 单例程教程（P4C5例程详解-*.md） |
| P4C5专项测试例程 | 05.test.* 24 项测试 |
| P4C5-GMF多媒体例程 | 06.gmf_examples 官方媒体管道 |
| P4C5在线组件使用说明 | 组件注册库 |
| Korvo与P4C5例程对照表 | 查 Korvo/P4 类似工程名 |
祝你学习顺利，玩转 ESP32-P4！
酷世DIY · Kevincoooool