乐鑫官方开发板

[English]

板级名称	参数 / 特性	产品链接	支持的接口
`esp32_s3_korvo2_v3`	ESP32-S3 支持 Wi-Fi Flash 16MB PSRAM 8MB	ESP32-S3-Korvo-2 V3	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `StorageFs` `StorageKv` `WifiBasic` `WifiSta` `WifiSoftAp`
`esp_box_3`	ESP32-S3 支持 Wi-Fi Flash 16MB PSRAM 16MB	ESP-BOX-3	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `StorageFs` `StorageKv` `WifiBasic` `WifiSta` `WifiSoftAp`
`esp_vocat_board_v1_0`	ESP32-S3 支持 Wi-Fi Flash 32MB PSRAM 16MB	ESP-VoCat V1.0	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `StorageFs` `StorageKv` `WifiBasic` `WifiSta` `WifiSoftAp`
`esp_vocat_board_v1_2`	ESP32-S3 支持 Wi-Fi Flash 32MB PSRAM 16MB	ESP-VoCat V1.2	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `StorageFs` `StorageKv` `WifiBasic` `WifiSta` `WifiSoftAp`
`esp32_p4_function_ev`	ESP32-P4 支持 Wi-Fi Flash 16MB PSRAM 32MB	ESP32-P4-Function-EV-Board	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `StorageFs` `StorageKv` `WifiBasic` `WifiSta` `WifiSoftAp`
`esp32_p4x_function_ev`	ESP32-P4 支持 Wi-Fi Flash 16MB PSRAM 32MB	ESP32-P4X Function-EV Board	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `StorageFs` `StorageKv` `WifiBasic` `WifiSta` `WifiSoftAp`
`esp32_s31_korvo1`	ESP32-S31 支持 Wi-Fi Flash 16MB PSRAM 16MB	ESP32-S31 Korvo1	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `StorageFs` `StorageKv` `WifiBasic` `WifiSta` `WifiSoftAp`
`esp_mosaico_v1_0`	ESP32-S31 支持 Wi-Fi Flash 16MB PSRAM 16MB 扩展插槽	官方用户指南 Brookesia 适配说明	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `PowerBattery` `StorageFs` `StorageKv` `ExpansionModuleManager` `Camera` （可选模块） `WifiBasic` `WifiSta` `WifiSoftAp`
`esp_mosaico_v1_2`	ESP32-S31 支持 Wi-Fi Flash 16MB PSRAM 16MB 扩展插槽部分验证，见适配说明	公开 BSP 版本 Brookesia 适配说明	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `DisplayBacklight` `PowerBattery` `StorageFs` `StorageKv` `ExpansionModuleManager` `Camera` （可选模块） `WifiBasic` `WifiSta` `WifiSoftAp`
`esp_sensair_shuttle`	ESP32-C5 支持 Wi-Fi Flash 16MB PSRAM 8MB	ESP Sensair Shuttle	`AudioCodecPlayer` `AudioCodecRecorder` `DisplayPanel` `DisplayTouch` `StorageFs` `StorageKv` `WifiBasic` `WifiSta` `WifiSoftAp`

ESP-Mosaico V1.0 适配说明

esp_mosaico_v1_0 支持 ESP-Mosaico V1.0 核心板的 Wi-Fi、480 x 480 显示与触摸、音频播放与录制、电池电压查询、LittleFS/NVS 和 NAND FATFS。摄像头通过可选扩展模块提供，模块未插入或不受支持时不影响核心板启动。

配置与使用

在示例工程目录中生成板级配置并编译。通用操作步骤请参考快速入门 - 如何使用示例工程。

idf.py gen-bmgr-config -b esp_mosaico_v1_0
idf.py --preview set-target esp32s31
idf.py build

板级默认配置包含以下设置：

扩展模块：启用 CONFIG_BROOKESIA_HAL_ADAPTOR_ENABLE_EXPANSION_MODULES，以及 Camera、DVP、OV3640 和 SC101IOT 驱动。
摄像头释放：CONFIG_BROOKESIA_HAL_ADAPTOR_VIDEO_KEEP_DEVICE_INITIALIZED_ON_RELEASE=n，最后一个会话关闭后释放摄像头设备。
设备注册容量：CONFIG_VFS_MAX_COUNT=12，供控制台、网络、文件系统和视频设备同时使用。
USB 控制台：启用 TinyUSB CDC 和自动下载；关闭 USB Serial/JTAG 辅助控制台、USB Service 自动注册及 System Core USB 文件传输桥接。
NAND：启用 FATFS 并挂载到 /nand；CONFIG_BROOKESIA_HAL_ADAPTOR_STORAGE_FILE_SYSTEM_FATFS_NAND_FORMAT_IF_MOUNT_FAILED=n，挂载失败时不会自动格式化。

备注

已有工程的 sdkconfig 优先于板级默认配置。更新开发板配置后，请通过 idf.py menuconfig 确认相关选项。使用 Board Manager 0.5.x 且指定非默认 SDKCONFIG 路径时，需在 SDKCONFIG_DEFAULTS 中包含 components/gen_bmgr_codes/board_manager.defaults。

扩展模块

Mosaico 每隔 300 ms 扫描可用插槽，连续三次得到相同结果后更新模块状态。扫描用于识别模块，功能硬件在对应 HAL 接口打开时初始化。

模块	插槽	支持范围
OV3640 摄像头	左槽	RGB565，640 x 480，7 fps；通过 Camera HAL 和 Video 接口取流。
SC101IOT 摄像头	左槽	YUV422，640 x 480，15 fps；通过 Camera HAL 和 Video 接口取流。
摄像头模块	右槽	报告 `Unsupported`，不初始化驱动。
其他有效模块	任意	识别模块信息并报告 `Unsupported`。

通过 Expansion:ModuleManager:0 查询和订阅插槽状态；应用也可使用 Device Service 的 GetExpansionModuleInfos 和 ExpansionModuleChanged。状态定义和异步回调约定请参考扩展模块支持。

使用注意事项

共享引脚：摄像头打开期间，两个插槽都会暂停扫描。摄像头成功关闭且共享引脚恢复后，重新扫描并恢复定期检测。
模块插拔：拔出摄像头前应先关闭摄像头，不支持取流过程中拔出模块。
USB 通道：GPIO33 同时用于 DVP D2 和 USB Serial/JTAG，不能与摄像头同时使用。板载 TinyUSB CDC 控制台使用独立通道；USB Service 尚不支持通过该通道传输文件。控制台初始化失败时，可恢复的错误会回退到 UART；无法恢复的标准流切换错误需要手动重启。
应用存储：NAND 可通过 HAL/Storage Service 访问。System Core 尚未自动将 /nand 纳入应用存储列表，App Store 显示其当前缓存目录所在分区的容量。
错误恢复：摄像头清理失败时应检查错误日志；Encoder HAL 的 close() 没有返回值。只有摄像头资源和共享引脚恢复后才会继续扫描；无法确认外设释放状态时需要手动重启。参见生命周期与错误处理。

hal/brookesia_hal_adaptor/test_apps 提供摄像头重复启停、扩展扫描恢复和 NAND 文件读写测试，可通过板载 USB 控制台选择用例。examples/system/super 用于运行完整系统示例。

实现与依赖

Mosaico 板级代码负责插槽识别、引脚复用和外设配置，上层使用通用 HAL 与 Service 接口。依赖兼容性说明见依赖补丁。

两个 Mosaico 版本均从 hal/brookesia_hal_boards/components/mosaico/ 选择共享组件：brookesia_hal_custom、esp_lcd_co5300 和 esp_mosaico_usb_console。每个版本目录保留 setup_device.c、board_devices.cpp、三份板级 YAML、sdkconfig.defaults.board 和 SOURCE.md。board_devices.cpp 中的注册代码将生成的板级配置转换为明确的共享设备参数；生命周期实现位于 brookesia_hal_custom/src/board/，接口位于 include/brookesia/hal_custom/board/。两版均不包含对方的源码文件。

setup_device.c 保留该版本的触摸工厂，并向共享面板工厂传入 LCD 时钟 GPIO。共享 audio_codec.c 提供供电使能和就绪等待 API：V1.0 注册前者控制 codec GPIO，V1.2 注册后者，在没有独立 GPIO 的情况下保留供电稳定延时。

硬件配置与部分初始化代码参考 Apache-2.0 许可的 ESP-Mosaico BSP。共享来源记录在 hal/brookesia_hal_boards/components/mosaico/SOURCE.md，版本专属参考保留在各板目录的 SOURCE.md。构建所需代码均包含在 Brookesia 仓库中。此前记录的实机结果早于本次源码布局重构，不代表重组后的布局已通过验证。

ESP-Mosaico V1.2 适配说明

esp_mosaico_v1_2 提供面向现有 HAL 和服务能力的 V1.2 CoreBoard 初步适配：Wi-Fi、480 x 480 显示与触摸、音频播放与录制、电池电压查询、LittleFS/NVS、NAND FATFS 和可选摄像头模块。

重要

V1.2 已完成部分实机验证，范围见下文。TinyUSB CDC 控制台菜单交互可用。当前样板触发自动下载后 USB 断开且未重新枚举，因此板级默认配置通过 CONFIG_BSP_USB_AUTO_DOWNLOAD=n 关闭自动下载。烧录前需通过 BOOT 手动进入 ROM 下载模式。

配置与版本差异

在示例工程目录中明确选择硬件版本；本次适配不通过 eFuse 自动选择板型。V1.0 CoreBoard 使用 esp_mosaico_v1_0，V1.2 CoreBoard 使用 esp_mosaico_v1_2。

idf.py gen-bmgr-config -b esp_mosaico_v1_2
idf.py --preview set-target esp32s31
idf.py build

相对于 V1.0 配置：

I2C 总线：板载设备与扩展模块使用独立的 I2C 外设；摄像头和模块管理器使用扩展总线。
显示：LCD 时钟/复位引脚按 V1.2 配置，触摸使用 CST9220 驱动。
Codec 供电：V1.2 不使用 V1.0 的独立 codec 供电 GPIO；通过板级依赖保留音频初始化前的 10 ms 供电稳定延时。
板级服务：NAND FATFS 和可选摄像头保留现有接口及生命周期处理；System Super 启动仍不依赖扩展模块。

V1.2 使用 Mosaico 实现说明中的共享组件布局，自己的 setup_device.c、board_devices.cpp 和配置文件保持独立于 V1.0 板目录。下述实机结果记录于本次源码布局重构之前，重组后的构建与实机验证需单独进行。

V1.2 保留 CONFIG_BSP_USB_CONSOLE=y 和 CONFIG_TINYUSB_CDC_ENABLED=y，但设置 CONFIG_BSP_USB_AUTO_DOWNLOAD=n 和 CONFIG_ESPTOOLPY_BEFORE_NORESET=y，避免手动进入 ROM 后再次复位。sdkconfig 优先级注意事项仍适用；已有 sdkconfig 需同步这两个设置。当前适配继续使用 Board Manager 0.5.15 依赖线及现有兼容补丁，依赖的完整升级另行处理。

V1.2 还设置 CONFIG_MBEDTLS_HARDWARE_SHA=n 和 CONFIG_MBEDTLS_HARDWARE_AES=n，使 HTTP/TLS 路径所用的 mbedTLS/PSA SHA/AES 使用软件实现，支持 LCD、NAND、摄像头与 HTTPS 共存。已有 V1.2 sdkconfig 需同步这两个选项。TLS 和签名验证仍保留，CPU 工作量可能增加，具体开销尚未测量。

这些设置不禁用直接硬件加密调用。Media SAL AES-CBC 直接调用 esp_aes_crypt_cbc，不受这两个选项控制。加密媒体与摄像头共存尚未验证。

范围与验证

当前样板已检查 LCD/CST9220 初始化和亮度控制、ES8311 初始化/释放、BQ27220 电压查询（约 3.9 V）、LittleFS/NVS，以及 SC101IOT 发现、初始化和释放。System Super 启动日志已出现 === System Example Completed ===；桌面显示、基本触摸交互和亮度滑杆拖动已人工确认正常。My Device 信息和附近 Wi-Fi 热点扫描也已确认正常，运行日志记录了网络校时成功。

NAND 格式化后挂载成功，上报总容量 119,746,560 字节。文件 write/fsync/seek/read/close/remove 操作以及卸载/重挂载测试已通过；文件数据断电持久化仍未验证。

SC101IOT 已通过 50 轮启停与取帧，使用原生 YUV422、640 x 480，每帧返回 614,400 字节。配置帧率为 15 fps，实际帧率及图像质量尚未验证。

完整 System Super 中的 Camera 应用预览在冷启动后可用，但 App Store 的 HTTPS 活动后无法重新打开。实机跟踪已确认 LCD 和 NAND 各占用一个 AXI GDMA RX 通道，硬件加密在 HTTPS 后持续占用剩余通道，阻止 DVP 分配。采用调整后 mbedTLS/PSA 默认配置的修复版固件，Camera 正常预览已由用户人工确认。这项目视确认独立于上述 HAL 取帧检查，最终串口捕获未记录本次操作。实际下载安装应用后的复测未单独记录。

音频播放/录制质量仍未验证。

NAND 配置为通过 HAL/Storage Service 挂载到 /nand，挂载失败时不自动格式化。System Core 尚未将 NAND 列为可选的应用安装位置。IMU 和马达服务接入不在本次适配范围内。

可选模块保留 V1.0 说明中的配置支持范围和使用限制，包括拔出前关闭摄像头、共享引脚恢复后再继续扫描。上述 SC101IOT 检查之外的路径仍待在 V1.2 上验证。未启用通过板载 TinyUSB CDC 通道进行 USB Service 文件传输。

hal/brookesia_hal_adaptor/test_apps 和 examples/system/super 均提供 sdkconfig.ci.board.esp_mosaico_v1_2 构建配置。现有 ESP32-S31 构建矩阵会发现这些文件；目标测试矩阵尚未配置 V1.2 硬件 runner。使用 HAL 测试程序完成剩余设备与生命周期检查，其他应用流程需另行验证。烧录前按住 BOOT 上电或复位，手动进入 ROM 下载模式；固件运行后仍可通过 CDC 控制台操作测试菜单。

版本专属配置参考 Apache-2.0 许可的公开 ESP-Mosaico BSP，提交 4a6c22b5。构建适配所需代码均包含在 Brookesia 仓库中。