SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场m5-onboard

m5-onboard

智能体与模型

查看项目

更新于 11-10 18:23

技能介绍

m5-onboard 是一个用于 M5Stack ESP32 设备冷启动初始化的技能，自动化检测、识别、刷写固件和安装应用的全流程。支持设备包括 Cardputer、Cardputer-Adv、Core、CoreS3、Stick 等型号，运行于 macOS、Linux 和 Windows。

用途

当用户插入 M5Stack 设备并希望完成配置时使用此技能。主要场景包括：新设备或未知设备需要从头初始化；设备已刷写固件但需要安装或刷新应用；设备运行异常需要基础硬件检查；或查看设备总线及能力。

主要能力

技能提供以下脚本模块：

  • scripts/onboard.py：主控脚本，按顺序调用子脚本，处理重启等待、MAC 捕获和进度报告。默认命令为 python3 scripts/onboard.py --apps buddy，针对全新 Cardputer-Adv 安装 buddy 应用包。
  • scripts/detect.py：枚举串口，过滤 USB-UART 桥接器（CH9102、CP210x、FTDI）或 ESP32-S3 原生 USB-JTAG 接口，用 esptool 确认芯片。若未指定端口，自动选择最可能的候选端口。
  • scripts/fetch_firmware.py：查询 M5Burner 清单 API 下载对应 UIFlow 2.0 二进制文件，缓存于系统临时目录。
  • scripts/flash.py：封装 esptool 进行刷写，UART 桥接器使用 460800 波特率，原生 USB S3 设备使用 115200 波特率并加 --no-stub。
  • scripts/install_apps.py：通过 REPL 粘贴模式将源目录中的 .py 文件上传至 /flash/，支持 --src buddy 或任意文件系统路径。若应用包包含根目录 main.py，会自动设置 NVS boot_option=2 以接管启动流程。
  • scripts/smoke_test.py：执行 I2C 扫描、LCD 测试图案、扬声器蜂鸣和按钮读取。
  • scripts/mpy_repl.py：共享串口/REPL 辅助函数，包括粘贴模式、硬复位和启动日志捕获。

参考文档 references/hardware_signatures.md 提供芯片和 I2C 指纹到型号及固件的映射；references/uiflow2_nvs.md 提供 NVS 键类型及故障模式说明。

使用方式

  1. 克隆仓库 https://github.com/moremas/build-with-claude，并在其 onboard/ 目录下执行脚本，确保 --apps buddy 解析到同级 buddy/device/ 负载。
  2. 默认初始化命令：python3 scripts/onboard.py --apps buddy。若设备已刷写固件，仅需安装应用：python3 scripts/install_apps.py --port <PORT> --src buddy。
  3. 在 Google Antigravity 环境中，需使用后台运行并 tee 日志，再通过 Monitor 工具或定期查看日志文件来实时展示进度。示例：python3 scripts/onboard.py --apps buddy 2>&1 | tee /tmp/m5-onboard.log，然后监控关键事件。
  4. 刷写阶段必须由用户手动操作：按住 G0 按钮，短暂按下并释放 RST 按钮，保持 G0 约一秒后释放，屏幕完全变暗表示进入下载模式。若设备重启回 UIFlow，说明 G0 释放过早，需重试并延长按住时间。
  5. 若未指定 --port，detect.py 会自动选择候选端口；存在多个候选时会询问用户。
  6. 应用包名称 buddy 对应仓库中 buddy/device/ 目录（包含自定义启动器、Hello、Antigravity Buddy BLE 客户端和 Snake）。其他 --apps 值视为文件系统路径。

适用场景

  • 新设备首次配置：运行完整 onboard 流程，检测、识别、刷写固件并安装应用。
  • 已有固件设备：仅运行 install_apps.py 推送或刷新应用，跳过刷写。
  • 设备异常排查：运行 smoke_test.py 检查 I2C、LCD、扬声器和按钮。
  • 多设备环境：指定端口以针对特定设备操作。

限制与注意事项

  • 原生 USB ESP32-S3 设备（Cardputer、Cardputer-Adv、CoreS3）必须手动按键进入下载模式，无软件路径。刷写期间切勿拔掉设备，否则可能导致闪存状态不一致，但掩膜 ROM 通常仍可访问，重新运行技能即可恢复。
  • 波特率固定为 UART 桥接器 460800、原生 USB 115200 加 --no-stub，不要提高至 921600。
  • NVS 写入必须使用 set_str 而非 set_blob，否则设备会启动循环。
  • REPL 多行代码需使用粘贴模式（Ctrl-E 进入，Ctrl-D 执行）。
  • 原生 USB 设备的 DTR/RTS 复位无效，需使用 mpy_repl.repl_reset() 通过 REPL 发送 machine.reset()。
  • Cardputer-Adv 的 BLE 外设需要 boot_option=2 加自定义 main.py，以避免 NimBLE 控制器卡死。
  • 依赖 pyserial（已内置 3.5 版本）和 esptool（需通过 pip 安装，脚本启动时会检查并提示安装）。
  • 若未明确指定型号，默认按 Cardputer-Adv 处理；若用户仅说“Cardputer”需询问确认，因为两者固件镜像不同，刷错会导致启动循环。
  • 技能自带的事件 WiFi 自动连接使用硬编码 SSID（cardputer），凭据位于 buddy/device/wifi_event.py，连接为尽力而为，失败不影响启动器。若在活动外使用，需编辑该文件或移除相关调用。
  • 恢复至 UIFlow 原生启动器：在设备 REPL 中执行 os.remove('/flash/main.py') 后 machine.reset()。若要完全重新开始（包括固件），重新运行技能时不带 --apps 参数。