1. 系统/框架

本仓库的运行时配置体系建立在 ESP-IDF v5.x + MicroPython 之上，采用三层叠加方式组织：

  • 构建期配置：通过 ESP-IDF 的 sdkconfig.* 片段与 CMake 组合，控制编译器选项、LWIP/mbedTLS/FreeRTOS 等底层行为。

  • 端口/板级配置：MicroPython 的 mpconfigport.h 与每个板型的 mpconfigboard.h 决定启用的 Python 内置模块、VFS、USB REPL、I2C/SPI 引脚映射等。

  • 运行期持久化配置：通过 ESP32 NVS（Non-Volatile Storage）以 key/value 形式保存用户配置，暴露为 Python 层 esp32.NVS 类型。

  • 文件系统/应用脚本：启动时按顺序执行冻结的 _boot.py、SPIFFS/LittleFS 中的 boot.py 和 main.py，作为应用级配置入口。

  • 开发工具配置：esp32s3/firmware/eim_config.toml 是 EIM（Espressif IoT Manager）工具的本地环境配置，不参与固件编译。

2. 关键文件与位置

  • ESP-IDF sdkconfig 片段（构建期）：esp32s3/firmware/boards/sdkconfig.base、sdkconfig.ble、sdkconfig.spiram*、sdkconfig.p4_wifi_*、sdkconfig.riscv、sdkconfig.flash_2MiB、sdkconfig.free_ram 等；各板型目录下的 sdkconfig.board、sdkconfig.usb 覆盖默认值。

  • MicroPython 端口配置：firmware/port/mpconfigport.h（ESP32 port）、esp32s3/firmware/boards/*/mpconfigboard.h（每块板）。前者定义全局 MICROPY_* 宏（如 MICROPY_PY_MACHINE、MICROPY_VFS、MICROPY_PY_USSL、MICROPY_PORT_BUILTIN_MODULES），后者声明 MICROPY_HW_BOARD_NAME、MICROPY_HW_MCU_NAME、引脚、功能开关（如 MICROPY_PY_AUDIO、MICROPY_PY_RFID）。

  • 板级 main.c：esp32s3/firmware/builtins/main.c（S3 统一入口）、esp32s3/firmware/boards/*/main.c（旧版 S3 板型）、firmware/port/builtins/main.c（ESP32 port 入口），负责初始化 NVS、创建 mp_task、加载 _boot.py / boot.py / main.py。

  • NVS Python 接口：firmware/port/builtins/esp32_nvs.c，实现 NVS(namespace) 对象及 get_i32/set_i32/get_blob/set_blob/erase_key/commit 方法，固定使用 user_nvs 命名空间。

  • 分区表：esp32s3/firmware/boards/*/partitions-*.csv（如 partitions-16MiB.csv），定义 nvs、phy_init、factory、vfs（spiffs）、voice_data（fat）、model（spiffs）、user_nvs 等分区；firmware/port/partitions.csv 对应 ESP32 port。

  • 应用脚本：firmware/port/file_system/main.py 演示读取 build_date.txt 与 uos.uname().version 展示固件信息；各板型可放置自己的 boot.py/main.py。

  • EIM 工具配置：esp32s3/firmware/eim_config.toml，仅用于本地 EIM 工具链安装路径与镜像源设置，不进入固件。

3. 架构与设计约定

  • 分层配置：sdkconfig.base 提供通用基线，各 sdkconfig.* 片段按特性（BLE、PSRAM、WiFi 芯片族、RISC-V）叠加；板级 sdkconfig.board/sdkconfig.usb 再覆盖具体硬件差异。新增板型需复制一份并修改 mpconfigboard.h、partitions-*.csv 与 sdkconfig.board。

  • 板型枚举：S3 固件支持 5 种板型——mpython_v3、labplus_for_xuejing、labplus_Ledong_v2、labplus_xunfei_js_middle、labplus_xunfei_js_primary，每种在 esp32s3/firmware/boards/<board>/ 下拥有独立 mpconfigboard.h、main.c、partitions-*.csv、manifest.py 等。

  • 启动流程即配置加载：app_main() → MICROPY_BOARD_STARTUP()（默认调用 boardctrl_startup() 初始化 NVS）→ xTaskCreatePinnedToCore(mp_task, ...) → mp_task 中依次执行 pyexec_frozen_module("_boot.py") → pyexec_file_if_exists("boot.py") → 若处于 friendly REPL 且未强制退出则执行 pyexec_file_if_exists("main.py")。因此 boot.py/main.py 是应用层配置的主要挂载点。

  • NVS 命名空间约定：所有 NVS 读写均通过 esp32.NVS("user_nvs") 打开名为 user_nvs 的命名空间，该命名空间由分区表中的 user_nvs 分区提供（偏移 0xFFC000，大小 0x4000）。键名使用字符串，值支持 i32 与 blob。

  • 日志级别：sdkconfig.base 将默认日志级别设为 ERROR，最大级别设为 INFO，以便 esp.osdebug() 在运行时提升日志等级。

  • USB/串口 REPL 选择：S3 板型通过 MICROPY_HW_ESP_USB_SERIAL_JTAG、MICROPY_HW_ENABLE_USBDEV、MICROPY_HW_ENABLE_UART_REPL 宏切换 USB Serial JTAG、原生 USB OTG 或 UART REPL；ESP32 port 通过 CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG / CONFIG_USB_OTG_SUPPORTED 条件编译。

  • 内存与 VFS：mpconfigport.h 启用 MICROPY_VFS、MICROPY_FATFS_ENABLE_LFN、MICROPY_MODULE_FROZEN_MPY=1，配合分区表中的 vfs（spiffs）分区，使 Python 代码可从 SPIFFS 加载。

4. 约定与约束

  • 新增板型必须补齐的配置集：至少包含 mpconfigboard.h、main.c、partitions-*.csv、sdkconfig.board、manifest.py（可选），并在 boards/ 顶层 make-pins.py 或 CMake 中注册。

  • NVS 写入前必须 commit：esp32_nvs.c 暴露的 commit() 方法用于将缓冲区写入 Flash，未调用可能导致数据丢失。

  • NVS 损坏恢复：boardctrl_startup() 在 nvs_flash_init() 返回 ESP_ERR_NVS_NO_FREE_PAGES 或 ESP_ERR_NVS_NEW_VERSION_FOUND 时自动擦除并重试，避免启动卡死。

  • 应用配置优先于构建配置：boot.py/main.py 可在运行时覆盖构建期宏所决定的行为（例如动态开启调试日志、切换网络参数），但无法改变已编译进固件的 MICROPY_* 宏。

  • 分区布局不可随意改动：user_nvs 分区位于分区表末尾（0xFFC000），其大小 0x4000 是 NVS 存储容量上限；修改分区表需同步调整 sdkconfig.base 中的 CONFIG_PARTITION_TABLE_CUSTOM_FILENAME。

  • EIM 配置仅限开发者机器：eim_config.toml 中的 path、idf_path、mirror 等字段指向本地路径，不应提交到版本库影响他人构建（当前仓库已保留示例值）。

  • 平台标识：mpconfigport.h 将 MICROPY_PY_SYS_PLATFORM 设为 "esp32"，S3 板型通过 MICROPY_HW_MCU_NAME = "ESP32S3" 区分 MCU 型号，应用可通过 sys.platform 与 machine 模块判断目标芯片。

5. 与文档/示例的关系

  • 文档侧（docs/、esp32s3/docs/）主要面向教师/学生/开发者说明 API 与教程，不涉及构建期配置细节；但 library/mPython/ 下的 mpython.rst 与源码 mpython.py 封装了板载功能，这些功能的可用性受 mpconfigboard.h 中宏控制（如 MICROPY_PY_AUDIO、MICROPY_PY_RFID）。

  • 示例程序通常放在 examples/ 或各板型 file_system/ 目录下，通过 boot.py/main.py 被启动流程加载，构成“应用级配置”的实际用法。