ESP32-S3 固件架构

本文引用的文件

  • CMakeLists.txt

  • esp32_common.cmake

  • main/CMakeLists.txt

  • main/idf_component.yml

  • boards/mpython_v3/mpconfigboard.cmake

  • boards/labplus_Ledong_v2/mpconfigboard.cmake

  • components/esp_lcd_jd9853/CMakeLists.txt

  • components/gen_bmgr_codes/CMakeLists.txt

  • makeimg.py

产品概述

本仓库为 ESP32-S3 产品线（掌控板3.0、乐动掌控2.0等）的 MicroPython 固件工程，基于 ESP-IDF v5.x 与 CMake 构建系统组织代码。工程通过“顶层 CMake + 板级配置 + 组件化”的方式，将 MicroPython 核心、ESP-IDF 组件、用户自定义组件（LVGL/ESP-Who 等）与板型专属资源进行解耦，支持多板型一键构建与打包。目标用户为教育硬件开发者、系统集成商与创客工程师，适用于语音交互、AI视觉、GUI 显示、传感器采集与物联网通信等场景。

核心业务流程

  • 选择板型：通过 MICROPY_BOARD 指定 mpython_v3 / labplus_Ledong_v2 等，顶层 CMake 加载对应 mpconfigboard.cmake，并合并 SDKCONFIG_DEFAULTS。

  • 集成 IDF：包含 main/CMakeLists.txt 后引入 esp32_common.cmake，注册 MicroPython 主组件，链接 ESP-IDF 组件与 TinyUSB、音频/视频/AI 相关依赖。

  • 生成引脚头：根据 pins.csv 与 make-pins.py 生成 pins.c/pins.h，供运行时 Pin/TouchPad 等模块使用。

  • 冻结 Python 包：按板型 manifest.py 冻结第三方库与业务脚本到 ROM。

  • 构建产物：idf.py build 产出 bootloader/partition/app；随后 merge_bin 调用 makeimg.py 将 VFS/LittleFS、语音模型、字体、TTS 数据等按分区表写入最终 bin，并在 S3 上生成 UF2。

flowchart TD
A["设置 MICROPY_BOARD"] --> B["加载 boards/<board>/mpconfigboard.cmake"]
B --> C["合并 SDKCONFIG_DEFAULTS"]
C --> D["include main/CMakeLists.txt -> esp32_common.cmake"]
D --> E["注册 MicroPython 主组件与 IDF 依赖"]
E --> F["生成 pins.c/pins.h"]
F --> G["编译应用与组件"]
G --> H["merge_bin: makeimg.py 打包固件"]
H --> I{"IDF_TARGET=ESP32S2/S3?"}
I --> |是| J["生成 .uf2"]
I --> |否| K["仅输出 .bin"]

图表来源

  • CMakeLists.txt:12-46

  • esp32_common.cmake:243-265

  • esp32_common.cmake:355-378

  • makeimg.py:106-222

章节来源

  • CMakeLists.txt:12-46

  • esp32_common.cmake:243-265

  • esp32_common.cmake:355-378

  • makeimg.py:106-222

功能模块清单

  • 构建系统与入口

    • 顶层 CMake：定义板型、合并 sdkconfig、包含 IDF 项目、注册 merge_bin 目标、锁定文件检查。

    • main/CMakeLists.txt：设置端口路径并引入 esp32_common.cmake。

    • esp32_common.cmake：聚合 MicroPython 源、扩展模块、端口适配、TinyUSB、IDF 组件、编译选项与链接片段。

  • 板型配置体系

    • mpython_v3：启用 SPIRAM、BLE、240MHz、板级 builtin 源与 frozen manifest。

    • labplus_Ledong_v2：在 mpython_v3 基础上追加 ESP-Who 相关组件目录以启用 AI 视觉能力。

  • 自定义组件（components）

    • esp_lcd_jd9853：屏幕驱动组件，依赖 esp_lcd，私有依赖 driver。

    • gen_bmgr_codes：基于 esp_board_manager 生成板信息代码，整包归档。

  • 依赖管理（idf_component.yml）

    • 声明 mdns/tinyusb/esp-sr/esp_audio_codec/esp_video/esp32-camera 等官方组件，以及本地 gmf_* 系列组件路径覆盖。

  • 固件打包（makeimg.py）

    • 读取分区表，组装 bootloader/partitions/application/VFS/voice_data/model，必要时生成 UF2。

章节来源

  • CMakeLists.txt:12-46

  • CMakeLists.txt:79-106

  • main/CMakeLists.txt:1-14

  • esp32_common.cmake:40-55

  • esp32_common.cmake:182-224

  • esp32_common.cmake:277-329

  • boards/mpython_v3/mpconfigboard.cmake:1-44

  • boards/labplus_Ledong_v2/mpconfigboard.cmake:1-50

  • components/esp_lcd_jd9853/CMakeLists.txt:1-8

  • components/gen_bmgr_codes/CMakeLists.txt:1-13

  • main/idf_component.yml:1-55

  • makeimg.py:81-222

数据与状态

  • 构建期配置

    • 板型标志：MPY_PORT_DIR/MICROPY_BOARD/MICROPY_BOARD_DIR、MICROPY_BOARD_VARIANT。

    • 目标芯片：IDF_TARGET（esp32s3）。

    • SDK 配置：SDKCONFIG_DEFAULTS 合并多个 sdkconfig.* 文件，最终输出 sdkconfig.combined。

    • 冻结清单：MICROPY_FROZEN_MANIFEST 指向各板型 manifest.py。

  • 运行时依赖

    • IDF 组件：app_update/bootloader_support/bt/driver/esp_wifi/nvs_flash/sdmmc/spi_flash/vfs 等。

    • 外设与协议栈：tinyusb（CDC）、lwip、mbedtls、nimble（BLE）、esp_lcd、esp32-camera、esp-sr 等。

  • 存储与分区

    • 分区表由 partition-table.bin 描述，包含 bootloader、partitions、application、vfs(LittleFS)、voice_data、model(SR 模型) 等。

    • makeimg.py 按偏移写入各段，校验溢出并生成最终固件镜像；S3 平台额外生成 UF2。

graph TB
subgraph "构建期"
A["mpconfigboard.cmake<br/>设置 IDF_TARGET/SDKCONFIG_DEFAULTS"] --> B["esp32_common.cmake<br/>注册组件/链接依赖"]
B --> C["idf_component.yml<br/>声明外部组件版本/路径"]
end
subgraph "运行期"
D["bootloader"] --> E["partition-table.bin"]
E --> F["application (micropython.bin)"]
E --> G["vfs (littlefs.bin)"]
E --> H["voice_data / model"]
end
C --> B

图表来源

  • boards/mpython_v3/mpconfigboard.cmake:5-13

  • esp32_common.cmake:182-224

  • main/idf_component.yml:1-55

  • makeimg.py:144-186

章节来源

  • boards/mpython_v3/mpconfigboard.cmake:5-13

  • esp32_common.cmake:182-224

  • main/idf_component.yml:1-55

  • makeimg.py:144-186

关键约束与边界

  • 构建环境

    • 需要 ESP-IDF v5.2+（见 idf_component.yml），且存在 IDF_PATH 环境变量。

    • 构建前需确保 lockfiles 一致，否则维护者构建会失败或警告。

  • 板型差异

    • mpython_v3 与 labplus_Ledong_v2 共享基础配置，后者额外引入 ESP-Who 组件目录以启用摄像头/AI 视觉能力。

    • 不同板型的 builtin 源与 frozen manifest 可能不同，需按 mpconfigboard.cmake 配置。

  • 组件依赖

    • esp_lcd_jd9853 依赖 esp_lcd 与 driver；gen_bmgr_codes 依赖 esp_board_manager 并以 WHOLE_ARCHIVE 整包链接。

    • TinyUSB 针对 S3/S2/P4 启用，并通过补丁分支解决 DWC2 ZLP 问题。

  • 存储与分区

    • 最终镜像大小受分区表限制，makeimg.py 会在写入时检测溢出并报错退出。

    • 若启用原生 USB 烧录，S3 平台会自动生成 UF2 以便拖拽烧录。

章节来源

  • main/idf_component.yml:51-55

  • CMakeLists.txt:95-106

  • boards/labplus_Ledong_v2/mpconfigboard.cmake:43-49

  • components/esp_lcd_jd9853/CMakeLists.txt:1-8

  • components/gen_bmgr_codes/CMakeLists.txt:1-13

  • makeimg.py:190-222