例程开发流程与公共组件

本文说明酷世 DIY 两款开发板例程的通用开发流程和公共组件架构。
视频系列：A04 · 总索引：文档总目录与视频教程大纲
Korvo S3 详见 Korvo例程学习指南；P4C5 详见 P4C5例程学习指南。

---

〇、例程资料怎么来

说明	内容
本 esp-idf-docs 文档	公开，讲解 API 与例程用法
完整例程工程	不公开下载；淘宝 酷世DIY 拍下对应板子后 联系客服，客服用 百度网盘 发全套资料
解压后目录	Korvo → Korvo_Firmware/ · P4C5 → P4_C5_4.3_Firmware/
路径要求	解压路径不要含中文

开发板	淘宝
Korvo	681702043224
P4C5	667230365314

---

一、两款开发板例程目录

开发板	解压后例程根目录	芯片 target	推荐 IDF
ESP32S3 Korvo 2 V3	Korvo_Firmware/	esp32s3	5.5.x
ESP32P4-C5 4.3寸屏	P4_C5_4.3_Firmware/	esp32p4	5.5.3

两套例程采用相同的目录命名规范：

01.basic.*          基础外设和系统能力
02.beginner.*       联网、USB、屏幕、存储、音频入门
03.development.*    LVGL、多媒体、USB 复合设备等
04.advanced.*       摄像头、视觉、综合项目、整板测试
components/         公共组件（BSP、显示 UI、板卡描述）

---

二、标准开发流程

2.1 环境准备

1. 安装 ESP-IDF（见 搭建编译环境）
   可先浏览 ESP-IDF 框架整体构成 了解 IDF 与工程的关系
2. PowerShell 执行 idf 导入环境
3. 从淘宝客服处获取 百度网盘 例程包，解压到本地（见上文 §〇）

2.2 首次编译某工程

cd <例程目录>
idf.py set-target esp32s3    # Korvo 用 esp32s3
# 或
idf.py set-target esp32p4    # P4C5 用 esp32p4

idf.py build flash monitor

set-target 只需在该工程首次或切换芯片时执行。

2.3 日常修改代码

idf.py build flash monitor       # 编译 + 烧录 + 看 log
idf.py build app-flash monitor   # 只烧 app 分区（更快）
idf.py -p COM5 flash monitor     # 指定串口
idf.py -b 2000000 flash          # 提高波特率

退出 monitor：Ctrl + ]

2.4 切换例程

每个子目录是独立工程，必须 cd 到新目录再 build。不要在一个 build 目录里混编不同工程。

2.5 menuconfig 常用配置

idf.py menuconfig

菜单	用途
Serial flasher config	默认 COM 口、Flash 大小
Example Configuration	部分例程的 SSID/密码等
Partition Table	自定义分区
Component config → ESP PSRAM	PSRAM 策略（P4 必看）
Component config → ESP-Hosted	P4C5 的 C5 SDIO/Wi-Fi

2.6 工程目录结构（ESP-IDF 标准）

以 01.basic.hello_world 为例：框架级说明见 ESP-IDF 框架整体构成；逐文件说明（含 Keil 对照、CMakeLists）见 ESP-IDF 工程结构详解。

此处仅列目录骨架：

01.basic.hello_world/
  CMakeLists.txt           顶层 CMake
  sdkconfig.defaults       默认配置
  partitions.csv           部分工程有自定义分区
  main/
    CMakeLists.txt         源文件列表
    hello_world_main.c     app_main() 入口
  build/                   编译输出（勿提交 Git）
  managed_components/      在线组件缓存（勿提交）

阅读顺序：main/*.c 的 app_main() → main/CMakeLists.txt → 顶层 CMakeLists.txt → 相关 components/。

---

三、公共组件设计思想

两块板外设都很多。如果在每个例子里复制 LCD、触摸、音频、电源初始化，初学者很快会迷路。

因此仓库采用分层：

业务逻辑（main/）
    ↓ 调用
公共组件（components/）
    ↓ 驱动
硬件（屏幕/触摸/Codec/PMIC…）

原则：例子的业务逻辑在 main/，板级硬件初始化尽量放在 components/。

---

四、Korvo S3 公共组件

组件	用途	适用场景
ksdiy_example_display	统一屏幕 UI（标题 + 三张状态卡）	单功能基础/入门例程
ksdiy_korvo_bsp	完整 BSP API（LCD/触摸/音频/摄像头/按键）	自研产品工程
ksdiy_korvo_s3	ESP Board Manager 板卡 YAML	接乐鑫官方例程

4.1 普通例程 UI

ksdiy_example_display_bootstrap("02.beginner.wifi_station", "connect to router");
ksdiy_example_display_set_lines("wifi connected", "ip: 192.168.1.10", "rssi: -48");

页面：STATE / DATA / DETAIL 三张卡 + 顶部标题。

适合：hello_world、gpio、wifi、usb_cdc 等单功能例程。
不适合：完整 LVGL Demo、摄像头预览、视频播放器、整板测试。

4.2 BSP 方式（做产品）

ksdiy_korvo_audio_config_t audio_cfg = KSDIY_KORVO_AUDIO_DEFAULT_CONFIG();
ksdiy_korvo_audio_init(&audio_cfg);
ksdiy_korvo_buttons_init(button_cb, NULL);

参考：04.advanced.korvo_bsp_demo

4.3 Board Manager 方式（接官方例程）

idf.py bmgr -b ..\components\ksdiy_korvo_s3

ESP_ERROR_CHECK(esp_board_manager_init());
esp_board_device_get_handle("display_lcd", &handle);

设备名：display_lcd、lcd_touch、camera、audio_dac、audio_adc、adc_button_group

参考：04.advanced.korvo_board_manager_demo

方式	适合
example_display	学习单功能、快速看屏幕状态
BSP	自己写产品、同时用多种外设
Board Manager	把乐鑫官方例子迁移到 Korvo 板

---

五、P4C5 公共组件

P4C5 组件按功能分四个目录，并同步发布到在线组件库。

本地目录	核心组件	在线名
components/	ksdiy_p4c5_bsp	kevincoooool/ksdiy_p4c5_bsp
components_audio/	ksdiy_p4c5_audio	kevincoooool/ksdiy_p4c5_audio
components_camera/	ksdiy_csi_camera 等	kevincoooool/ksdiy_csi_camera
components_cellular/	ksdiy_cellular_modem	kevincoooool/ksdiy_cellular_modem

5.1 一键初始化显示

nvs_flash_init();
ksdiy_lvgl_port_init();   // AXP → MIPI DSI → 触摸 → LVGL 9

之后所有例程（包括 01.basic.gpio）都能在 4.3 寸屏显示状态。

5.2 LVGL 线程安全

if (ksdiy_lvgl_lock(100)) {
    /* LVGL API 调用 */
    ksdiy_lvgl_unlock();
}

5.3 在线组件 vs 本地组件

• 在线：main/idf_component.yml 声明依赖，build 时自动下载
• 本地：CMakeLists.txt 中 EXTRA_COMPONENT_DIRS 指向仓库 components/

详见 P4C5在线组件使用说明

---

六、每个例程教程的标准结构

阅读或编写单个例程文档时，建议按此结构：

1. 这个例子在干嘛
2. 硬件现象（屏幕 + 串口）
3. 编译烧录命令
4. 关键文件
5. 核心代码流程
6. 常见问题
7. 动手改造

---

七、常见问题

编译时 sdkconfig 被大量修改

不同 IDF 版本会重写 sdkconfig，属正常行为。团队开发请统一 IDF 版本。

build 目录太大

build/ 和 managed_components/ 可删除后重新生成，不要提交 Git。

工程路径含中文

ESP-IDF 不支持中文路径，请将工程放在纯英文目录。

首次 build 很慢

需下载在线组件；关闭杀毒软件可加速；之后增量编译会快很多。

Korvo 和 P4 能混用 build 目录吗？

不能。 target 不同（esp32s3 / esp32p4），显示与 Wi-Fi 栈也不同。教程按板分篇：Korvo例程详解-* 与 P4C5例程详解-*。

---

八、与通用外设教程的关系

本教程 docs/ 下的 GPIO 等讲解 ESP-IDF 通用 API；百度网盘例程包则在 API 之上叠加板级 BSP 和完整可运行工程。

推荐学习路径：

1. 读通用教程理解 API 概念
2. 解压例程包后打开对应工程，看完整实现并改参数
3. 改例程参数验证理解
4. 用 BSP/在线组件搭建自己的工程

---

酷世DIY · Kevincoooool