内部研发文档

本文引用的文件

升级到micropython_v1.23.0.md
new_board-labplus_Ledong_pro.md
project_add_esp_adf.md
usb-otg and usb-serial-jtag.md
CMakeLists.txt
mpython_v3/mpconfigboard.cmake
labplus_Ledong_v2/mpconfigboard.cmake
mpython_v3/mpconfigboard.h
labplus_Ledong_v2/mpconfigboard.h
mpython_v3/sdkconfig.usb
labplus_Ledong_v2/sdkconfig.usb

产品概述

本技术文档面向内部研发团队，聚焦以下主题：

MicroPython版本迁移（从旧版到v1.23.0及ESP-IDF v5.x）
新板型适配流程与要点（以乐动掌控系列为例）
ESP-ADF音频框架集成与裁剪策略
USB OTG与USB Serial/JTAG在S3板上的启用与配置

项目基于MicroPython for ESP32/ESP32-S3定制，采用ESP-IDF CMake构建系统，按板型隔离配置与模块，便于多产品线并行开发与发布。

核心业务流程

版本迁移流程：引入新版Micropython与ESP-IDF，调整构建脚本、组件路径、QSTR与模块注册，确保各板型可编译并功能可用。
新板型适配流程：复制基础模板，完成引脚、I2C、PSRAM、分区表、manifest冻结、builtin模块与Python库的板级配置，验证REPL/USB/显示/音频等关键能力。
ESP-ADF集成流程：按需拷贝组件、裁剪依赖、合并sdkconfig，控制固件体积，提供录音/播放/语音识别/合成等能力。
USB OTG/Serial JTAG流程：通过sdkconfig启用TinyUSB CDC与JTAG Console，结合板级配置实现自动下载与调试。

flowchart TD
A["开始"] --> B["选择目标板型<br/>mpython_v3 / labplus_Ledong_v2"]
B --> C{"是否新增板型?"}
C -- 是 --> D["新建板目录与配置<br/>mpconfigboard.* / sdkconfig.*"]
C -- 否 --> E["复用现有板配置"]
D --> F["添加builtin与Python模块<br/>manifest冻结"]
E --> F
F --> G{"是否需要ESP-ADF?"}
G -- 是 --> H["拷贝并裁剪组件<br/>audio_stream/esp-sr/..."]
G -- 否 --> I["跳过ADF集成"]
H --> J["合并sdkconfig并构建"]
I --> J
J --> K{"是否启用USB OTG/JTAG?"}
K -- 是 --> L["启用CONFIG_USB_OTG_SUPPORTED<br/>CONFIG_TINYUSB_CDC_ENABLED<br/>CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG"]
K -- 否 --> M["保持默认串口控制台"]
L --> N["构建/烧录/联调"]
M --> N
N --> O["结束"]

章节来源

升级到micropython_v1.23.0.md:23-94
new_board-labplus_Ledong_pro.md:1-43
project_add_esp_adf.md:1-12
usb-otg and usb-serial-jtag.md:1-5

功能模块清单

构建系统与板级配置
- 顶层CMakeLists负责解析MICROPY_BOARD、包含板级mpconfigboard.cmake、合并sdkconfig、生成合并配置文件并调用idf_build_set_property与project(micropython)。
- 板级mpconfigboard.cmake定义IDF_TARGET、SDKCONFIG_DEFAULTS、MICROPY_SOURCE_BOARD与MICROPY_SOURCE_BOARD_DIR、冻结manifest路径，并可开启板级宏开关。
板型差异与外设
- mpython_v3与labplus_Ledong_v2均启用音乐、音频、RFID与新I2C驱动；I2C引脚不同；USB Serial/JTAG与OTG支持通过sdkconfig.usb启用。
模块冻结与内置C模块
- 通过manifest.py将常用Python模块冻结入ROM，减少内存占用并提升启动速度；builtin层包含machine_pin、touchpad、framebuf、i2c、timer、music、nvs、network_wlan等。
ESP-ADF音频能力
- 通过拷贝必要组件并按需裁剪，提供录音、播放、TTS/IAT等能力；注意去除冗余依赖以降低固件体积。
USB OTG与调试
- 启用TinyUSB CDC与JTAG Console，配合bootloader与工具链实现自动下载与调试；缓冲区大小可按需调整。

章节来源

CMakeLists.txt:12-66
mpython_v3/mpconfigboard.cmake:1-44
labplus_Ledong_v2/mpconfigboard.cmake:1-50
mpython_v3/mpconfigboard.h:1-29
labplus_Ledong_v2/mpconfigboard.h:1-29
mpython_v3/sdkconfig.usb:1-9
labplus_Ledong_v2/sdkconfig.usb:1-8

数据与状态

构建产物与配置
- 顶层CMake生成sdkconfig.combined.in并输出为sdkconfig.combined供ESP-IDF使用；锁定文件用于检测依赖变更。
板级状态标志
- 通过MPY_PORT_DIR、MICROPY_BOARD、MICROPY_BOARD_VARIANT、MPYTHON_V3_BOARD/LABPLUS_LEDONG_V2_BOARD等宏区分板型与变体，影响源文件集合与组件目录。
运行时模块状态
- 冻结manifest决定哪些Python模块被预编译并驻留ROM；builtin C模块初始化顺序影响I2C、TouchPad、Pin、Timer、Music、NVS、WiFi等子系统可用性。
音频与USB状态
- ESP-ADF组件加载后，音频流、编解码器、网络服务处于待命或运行态；USB OTG/CDC启用后，控制台与虚拟串口就绪。

graph TB
subgraph "构建期"
T["顶层CMakeLists.txt"] --> B["板级mpconfigboard.cmake"]
B --> S["合并sdkconfig.combined"]
S --> IDF["ESP-IDF构建"]
end
subgraph "运行期"
ROM["冻结Python模块(ROM)"] --> APP["用户应用"]
BUILTIN["Builtin C模块"] --> APP
ADF["ESP-ADF组件"] --> APP
USB["USB OTG/CDC/JTAG"] --> APP
end
IDF --> ROM
IDF --> BUILTIN
IDF --> ADF
IDF --> USB

图表来源

CMakeLists.txt:32-66
mpython_v3/mpconfigboard.cmake:19-44
labplus_Ledong_v2/mpconfigboard.cmake:19-50

章节来源

CMakeLists.txt:32-66
mpython_v3/mpconfigboard.cmake:19-44
labplus_Ledong_v2/mpconfigboard.cmake:19-50

关键约束与边界

版本与依赖边界
- 升级至Micropython v1.23.0与ESP-IDF v5.0.4时，需遵循新的CMake与组件管理方式；qstr、模块注册、GC指针管理等细节需对齐新版本。
板型边界
- 每块板独立维护mpconfigboard.与sdkconfig.；I2C引脚、PSRAM类型与容量、分区表布局必须与硬件一致；manifest冻结需按板型裁剪。
ESP-ADF边界
- 仅拷贝必要组件并按需裁剪CMake依赖，避免引入冗余代码导致固件过大；tone_partition与wifi_service等组件需显式处理依赖关系。
USB OTG/Serial JTAG边界
- 启用USB OTG与CDC需保证引脚与电源设计满足要求；JTAG Console需与bootloader协同，确保自动下载与调试链路畅通。
性能与体积
- 冻结模块可减少RAM占用并加速启动；精简ADF组件与禁用未用功能有助于降低Flash占用与功耗。

章节来源

升级到micropython_v1.23.0.md:23-94
new_board-labplus_Ledong_pro.md:1-43
project_add_esp_adf.md:1-12
usb-otg and usb-serial-jtag.md:1-5
mpython_v3/sdkconfig.usb:1-9
labplus_Ledong_v2/sdkconfig.usb:1-8