固件架构与源码

本文引用的文件

firmware/port/README.md
esp32s3/firmware/README.md
firmware/port/mpconfigport.h
firmware/port/Makefile
esp32s3/firmware/CMakeLists.txt
esp32s3/firmware/esp32_common.cmake
esp32s3/firmware/makeimg.py
esp32s3/firmware/main/CMakeLists.txt
esp32s3/firmware/boards/mpython_v3/mpconfigboard.cmake
esp32s3/firmware/boards/labplus_Ledong_v2/mpconfigboard.cmake
esp32s3/firmware/boards/manifest.py
firmware/port/builtins/modmachine.c
firmware/port/builtins/modmusic.c
firmware/port/builtins/modnetwork.c
firmware/port/builtins/modradio.c
firmware/port/builtins/modframebuf.c
firmware/port/builtins/modmotion.c
firmware/port/builtins/modcodec.c
firmware/port/builtins/modxunfeiAI.c
firmware/port/modules/ssd1106.py
firmware/port/modules/neopixel.py
firmware/port/modules/mpython_ble/application/codexpad.py
firmware/port/file_system/siot.py
firmware/port/file_system/xunfei.py
firmware/port/file_system/yeelight.py
firmware/port/file_system/smartcamera.py
esp32s3/firmware/modules/radio.py
esp32s3/firmware/modules/ai_cloud.py
esp32s3/firmware/modules/xunfei.py

产品概述

mPython掌控板是基于ESP32双核芯片的MicroPython微控制器平台，面向K12创客教育场景。固件以MicroPython为核心，在FreeRTOS上运行，提供REPL、文件系统、GPIO/ADC/PWM/I2C/SPI等外设能力，以及WiFi/BLE网络、音频、传感器、显示等扩展能力。项目同时维护了两条产品线：

ESP32版（firmware/port）：成熟稳定，内置大量C级模块与Python扩展库，适合教学与快速原型。
ESP32-S3版（esp32s3/firmware）：基于ESP-IDF v5.x + CMake构建，新增LVGL/AI视觉、GPS、心率等能力，支持多板型（mpython_v3、labplus_Ledong_v2等）。

核心价值在于“C层高性能+Python层易用性”的分层设计，既满足底层驱动性能需求，又通过Python模块降低开发门槛；构建流程清晰、板型配置解耦，便于二次开发与定制。

章节来源

firmware/port/README.md:1-20
esp32s3/firmware/README.md:1-20

核心业务流程

启动与初始化
- 引导程序加载分区表与应用镜像，FreeRTOS任务调度MicroPython VM。
- 端口层初始化串口REPL、内存管理、VFS、网络栈、蓝牙等。
用户代码执行
- Python脚本从冻结模块或LittleFS文件系统加载执行。
- 调用C级builtins（如machine/music/network）或直接使用Python模块（如neopixel/gui）。
硬件交互
- C驱动访问外设（I2C/SPI/ADC/PWM/TIMERS），暴露为Python接口。
- 传感器/音频/显示等通过drivers与modules组合实现。
构建与烧录
- ESP32版使用Makefile+ESP-IDF v3/v4；ESP32-S3版使用idf.py+CMake。
- 生成bootloader/partitions/app/VFS/语音模型等，合并为最终固件镜像。

sequenceDiagram
participant Boot as "引导程序"
participant IDF as "ESP-IDF/FreeRTOS"
participant MP as "MicroPython VM"
participant Py as "用户Python脚本"
participant Mod as "C级模块/Python模块"
participant HW as "硬件外设"
Boot->>IDF : 加载分区表与应用
IDF->>MP : 创建并启动VM任务
MP->>Py : 执行boot.py/main.py
Py->>Mod : 调用machine/music/network等
Mod->>HW : 读写寄存器/中断/DMA
HW-->>Mod : 数据/事件
Mod-->>Py : 返回结果/回调
Py-->>MP : 继续执行/退出

图表来源

esp32s3/firmware/esp32_common.cmake:126-180
esp32s3/firmware/makeimg.py:179-200

章节来源

esp32s3/firmware/esp32_common.cmake:126-180
esp32s3/firmware/makeimg.py:179-200

功能模块清单

C级编译模块（builtins）
- machine：GPIO/ADC/PWM/I2C/SPI/TouchPad/Timer等基础外设控制。
- music：兼容micro:bit的音乐播放与节拍控制。
- network/WiFi：WLAN连接与网络协议栈。
- radio：无线广播（ESP32版）。
- framebuf：帧缓冲绘制。
- motion：六轴传感器（加速度/陀螺仪/磁力计）。
- codec：音频编解码与录音/播放（ESP32版）。
- xunfeiAI：讯飞语音听写与TTS（ESP32版）。
Python级模块（modules）
- 设备驱动与工具：ssd1106(OLED)、neopixel(WS2812)、gui、logging、weather等。
- BLE高级库：mpython_ble（advertising/services/gatts等）。
- 网络与物联网：urequests、umqtt、tinywebio、siot等。
硬件驱动（drivers）
- codec、mpu6050、rfid、rgbLED5x5等底层C驱动。
文件系统扩展（file_system）
- siot(SIoT物联网)、yeelight(智能灯)、xunfei(讯飞AI)、smartcamera(AI摄像头)等应用级库。

graph TB
subgraph "C级模块(builtins)"
M["modmachine"]
U["modmusic"]
N["modnetwork"]
R["modradio"]
F["modframebuf"]
O["modmotion"]
A["modcodec"]
X["modxunfeiAI"]
end
subgraph "Python模块(modules)"
S["ssd1106"]
P["neopixel"]
G["gui"]
B["mpython_ble"]
Q["urequests/umqtt"]
end
subgraph "驱动(drivers)"
D1["codec"]
D2["mpu6050"]
D3["rfid"]
D4["rgbLED5x5"]
end
subgraph "文件系统(file_system)"
FS1["siot"]
FS2["yeelight"]
FS3["xunfei"]
FS4["smartcamera"]
end
M --> D1
M --> D2
M --> D3
M --> D4
U --> M
N --> M
R --> M
F --> M
O --> M
A --> M
X --> N
S --> M
P --> M
G --> F
B --> N
Q --> N
FS1 --> N
FS2 --> N
FS3 --> N
FS4 --> N

图表来源

firmware/port/builtins/modmachine.c
firmware/port/builtins/modmusic.c
firmware/port/builtins/modnetwork.c
firmware/port/builtins/modradio.c
firmware/port/builtins/modframebuf.c
firmware/port/builtins/modmotion.c
firmware/port/builtins/modcodec.c
firmware/port/builtins/modxunfeiAI.c
firmware/port/modules/ssd1106.py
firmware/port/modules/neopixel.py
firmware/port/modules/mpython_ble/application/codexpad.py
firmware/port/file_system/siot.py
firmware/port/file_system/xunfei.py
firmware/port/file_system/yeelight.py
firmware/port/file_system/smartcamera.py

章节来源

firmware/port/builtins/modmachine.c
firmware/port/builtins/modmusic.c
firmware/port/builtins/modnetwork.c
firmware/port/builtins/modradio.c
firmware/port/builtins/modframebuf.c
firmware/port/builtins/modmotion.c
firmware/port/builtins/modcodec.c
firmware/port/builtins/modxunfeiAI.c
firmware/port/modules/ssd1106.py
firmware/port/modules/neopixel.py
firmware/port/modules/mpython_ble/application/codexpad.py
firmware/port/file_system/siot.py
firmware/port/file_system/xunfei.py
firmware/port/file_system/yeelight.py
firmware/port/file_system/smartcamera.py

数据与状态

构建配置与开关
- mpconfigport.h集中定义MicroPython特性开关（线程、VFS、SSL、WebREPL、FrameBuffer等）、内置模块注册、根指针与平台标识。
- 板级cmake（mpython_v3/labplus_Ledong_v2）指定目标芯片、SDKCONFIG默认集、源文件列表与冻结清单。
模块依赖关系
- builtins通过mpconfigport.h注册为内置模块名（machine/network/music/audio/radio等），被Python层直接import。
- modules与file_system作为扩展库，按需要冻结到固件或通过文件系统加载。
运行时状态
- FreeRTOS任务调度MicroPython VM；事件钩子处理挂起任务与异步事件。
- VFS将LittleFS挂载为内部文件系统，存储用户脚本与资源。
- NVS用于持久化配置（如传感器偏移、网络凭据等）。

flowchart TD
Start(["构建入口"]) --> Cfg["读取mpconfigport.h<br/>与板级cmake"]
Cfg --> Modules{"启用哪些模块?"}
Modules --> |C级| Builtin["注册builtins<br/>machine/network/music..."]
Modules --> |Python| Freeze["冻结modules/file_system"]
Builtin --> Build["编译链接"]
Freeze --> Build
Build --> Pack["makeimg.py打包<br/>bootloader/partitions/app/VFS/语音模型"]
Pack --> Flash["烧录到Flash"]
Flash --> Run["FreeRTOS启动MicroPython"]
Run --> App["执行用户脚本"]
App --> State["运行时状态: VFS/NVS/网络/外设"]

图表来源

firmware/port/mpconfigport.h:14-61
firmware/port/mpconfigport.h:180-218
esp32s3/firmware/boards/mpython_v3/mpconfigboard.cmake:1-44
esp32s3/firmware/boards/labplus_Ledong_v2/mpconfigboard.cmake:1-50
esp32s3/firmware/makeimg.py:179-200

章节来源

firmware/port/mpconfigport.h:14-61
firmware/port/mpconfigport.h:180-218
esp32s3/firmware/boards/mpython_v3/mpconfigboard.cmake:1-44
esp32s3/firmware/boards/labplus_Ledong_v2/mpconfigboard.cmake:1-50
esp32s3/firmware/makeimg.py:179-200

关键约束与边界

构建系统差异
- ESP32版：Makefile + ESP-IDF v3/v4，需设置ESPIDF路径与工具链，支持BOARD变量选择板型。
- ESP32-S3版：idf.py + CMake，顶层CMakeLists.txt包含板级配置，支持variant与lockfiles校验。
板型与配置边界
- 每个板型有独立mpconfigboard.cmake与sdkconfig集合，避免交叉污染。
- 冻结清单(manifest.py)决定Python模块是否内嵌，影响固件体积与启动时间。
模块可用性边界
- ESP32版：audio/radio/xunfeiAI为C级内置；ESP32-S3版：radio迁移至Python模块，新增ai_cloud/xunfei等。
- 部分引脚/外设受限（如P4光线、P10声音），通用IO需避开专用功能。
运行时约束
- 堆栈与内存：MicroPython任务栈与Python堆大小有限，需关注大对象分配。
- 网络与BLE：需正确配置天线与RF参数，不同板型可能需额外初始化。
集成与扩展边界
- drivers与modules分层清晰，新增驱动应优先放入drivers，Python封装放在modules。
- file_system中的扩展库属于应用层，不纳入核心构建，按需部署。

章节来源

firmware/port/Makefile:1-200
esp32s3/firmware/CMakeLists.txt:1-107
esp32s3/firmware/main/CMakeLists.txt:1-14
esp32s3/firmware/boards/manifest.py:1-16
esp32s3/firmware/modules/radio.py
esp32s3/firmware/modules/ai_cloud.py
esp32s3/firmware/modules/xunfei.py