ESP32 产品线

本文引用的文件

docs/README.md
firmware/README.md
esp32s3/firmware/README.md
firmware/port/Makefile
firmware/port/boards/mpython/mpconfigboard.h
firmware/port/boards/mpython-classroom-kit/mpconfigboard.h
firmware/port/boards/labplus-experiment-box-2024/mpconfigboard.h
esp32s3/firmware/boards/mpython_v3/mpconfigboard.h
esp32s3/firmware/main/Kconfig.projbuild
esp32s3/firmware/components/gen_bmgr_codes/board_manager.defaults
docs/docs/zh_CN/board/introduction.rst

产品概述

本项目为 ESP32 掌控板产品线的知识基座，覆盖标准掌控板、课堂套件、实验箱等板型，以及其对应的固件与文档体系。ESP32 版本基于 MicroPython + ESP-IDF v3.3.2/v4.0.1 + Makefile 构建；ESP32-S3 版本基于 ESP-IDF v5.x + MicroPython + CMake 构建，并新增 LVGL、AI 视觉等能力。文档源位于 docs/（Sphinx + reStructuredText），固件源位于 firmware/（ESP32）与 esp32s3/firmware/（ESP32-S3）。

目标用户：K12 教师与学生、创客开发者、教育设备集成商
核心价值：以 Python 降低入门门槛，提供从图形化到代码的平滑学习路径；通过多板型覆盖教学、竞赛、实验场景
适用场景：课堂编程、项目式学习、物联网原型开发、AI 语音/视觉体验

章节来源

docs/README.md:1-16
firmware/README.md:1-57
esp32s3/firmware/README.md:1-242
docs/docs/zh_CN/board/introduction.rst:1-18

核心业务流程

围绕“选择板型 → 配置构建环境 → 编译固件 → 烧录运行”的主流程，结合不同板型的差异化配置，形成统一的可复用构建链路。

flowchart TD
A["开始"] --> B{"选择板型"}
B --> |ESP32| C["设置 ESPIDF 环境变量<br/>指向 v3.3.2 或 v4.0.1"]
B --> |ESP32-S3| D["安装 ESP-IDF v5.x<br/>准备 CMake 工具链"]
C --> E["指定 BOARD=mpython / classroom-kit / experiment-box"]
D --> F["通过 Kconfig 选择 mpython_v3 / Ledong_v2 等"]
E --> G["执行 make submodules && make"]
F --> H["执行 idf.py build / make 构建"]
G --> I["生成 bootloader.bin / partitions.bin / application.bin"]
H --> I
I --> J["使用 esptool 或 idf.py flash 烧录"]
J --> K["上电运行 REPL 与示例程序"]

图示来源

firmware/port/Makefile:1-52
esp32s3/firmware/README.md:77-143

章节来源

firmware/port/Makefile:1-52
esp32s3/firmware/README.md:77-143

功能模块清单

本仓库按“文档 + 固件 + 板型配置”组织，形成面向教学与开发的完整能力矩阵。

文档层（docs/）
- 中文文档（docs/docs/zh_CN/）：板卡介绍、驱动、库参考、教程、项目指南、FAQ
- 示例代码（docs/examples/）：display/button/audio/ble/IoT/game 等分类，便于快速上手
固件层（firmware/port/）
- builtins/：C 级模块（machine/motion/music/radio/network 等）
- modules/：Python 级模块（bluebit/gui/neopixel/urequests 等）
- drivers/：C 硬件驱动（codec/mpu6050/rfid/rgbLED5x5）
- file_system/：扩展库（siot/yeelight/xunfei/smartcamera 等）
板型配置（firmware/port/boards/）
- mpython（标准掌控板）
- mpython-classroom-kit（课堂套件）
- labplus_classroom_kit_II（课堂套件 II）
- labplus_1956
- labplus-experiment-box-2024（实验箱）
- GENERIC（通用）
ESP32-S3 固件层（esp32s3/firmware/）
- 新增 usercmodule（LVGL 绑定、ESP-Who AI 视觉）
- 新增 components（esp_lcd_jd9853 屏幕驱动、gen_bmgr_codes）
- 新增 modules（ai_cloud、ATGM336H_5N、max30102、CSK6011A、xgo 等）
ESP32-S3 板型配置（esp32s3/firmware/boards/）
- mpython_v3（标准 S3 掌控板）
- labplus_Ledong_v2（乐动掌控 2.0）
- labplus_for_xuejing（学境版）
- labplus_xunfei_js_primary / middle（讯飞 JS 初级/中级版）

章节来源

docs/README.md:1-16
firmware/README.md:1-57
esp32s3/firmware/README.md:1-242

数据与状态

板型标识与 MCU 名称
- ESP32 板型在 mpconfigboard.h 中定义 MICROPY_HW_BOARD_NAME 与 MICROPY_HW_MCU_NAME
- ESP32-S3 板型同样在 mpconfigboard.h 中声明，并通过 Kconfig 选择具体板型
构建产物状态
- ESP32：make 生成 bootloader.bin、partitions.bin、application.bin，最终打包为 firmware.bin
- ESP32-S3：idf.py/build 生成对应分区与应用镜像，支持 OTA/SPIRAM 等变体
运行时状态
- 通过 REPL（UART/USB）进行交互调试
- WiFi/BLE 连接状态由网络模块管理
- 传感器与外设状态由各自驱动维护（如 motion、audio、framebuf）

classDiagram
class BoardConfig {
+string board_name
+string mcu_name
+bool adc_enabled
+bool dac_enabled
}
class BuildSystem {
+string toolchain
+string idf_version
+string target_board
+generate_bin()
}
class Runtime {
+repl()
+wifi_state()
+peripheral_status()
}
BoardConfig --> BuildSystem : "决定编译选项"
BuildSystem --> Runtime : "生成可执行镜像"

图示来源

firmware/port/boards/mpython/mpconfigboard.h:1-22
firmware/port/boards/mpython-classroom-kit/mpconfigboard.h:1-26
firmware/port/boards/labplus-experiment-box-2024/mpconfigboard.h:1-21
esp32s3/firmware/boards/mpython_v3/mpconfigboard.h:1-29
esp32s3/firmware/main/Kconfig.projbuild:1-32

章节来源

firmware/port/boards/mpython/mpconfigboard.h:1-22
firmware/port/boards/mpython-classroom-kit/mpconfigboard.h:1-26
firmware/port/boards/labplus-experiment-box-2024/mpconfigboard.h:1-21
esp32s3/firmware/boards/mpython_v3/mpconfigboard.h:1-29
esp32s3/firmware/main/Kconfig.projbuild:1-32

关键约束与边界

构建环境与依赖
- ESP32：要求 ESP-IDF v3.3.2 或 v4.0.1（通过 git hash 校验），pyparsing < 2.4；需 xtensa-esp32-elf 工具链
- ESP32-S3：要求 ESP-IDF v5.x（如 v5.0.4），CMake 工具链；支持 OTA、SPIRAM 等变体
板型差异边界
- ESP32 板型通过 mpconfigboard.h 启用/禁用 ADC/DAC、内置模块（motion、rgbLED5x5）
- ESP32-S3 板型通过 Kconfig 选择具体板型，并在 mpconfigboard.h 中启用音频、RFID、I2C 等新特性
运行时边界
- 网络：WiFi/BLE 需在系统初始化后配置；部分板型需切换天线
- 存储：NVS 用于持久化配置；文件系统支持 FAT/LFS2
- 显示：ESP32 使用 OLED（SSD1106），ESP32-S3 使用 TFT LCD（st7789）
许可与开源协议
- 软件 GPL-3，硬件 CERN，文档 CC0；OSHWA 认证开源硬件

章节来源

firmware/port/Makefile:65-118
esp32s3/firmware/README.md:22-75
firmware/port/boards/mpython-classroom-kit/mpconfigboard.h:1-26
esp32s3/firmware/boards/mpython_v3/mpconfigboard.h:1-29
esp32s3/firmware/main/Kconfig.projbuild:1-32
firmware/README.md:44-57