烧录固件

本章说明如何将 AmebaClaw 固件烧录到开发板。提供两种方式：

  • 在线烧录：使用浏览器内置烧录工具，无需安装任何软件，直接完成固件烧录。

  • 手动烧录：适合开发者使用命令行进行自定义编译与烧录。

备注

在线烧录工具依赖 Web Serial API，该 API 仅在 Chrome 和 Edge 最新版本中受支持。Firefox 和 Safari 目前不支持。

在线烧录

前置条件

  • 使用支持 Web Serial API 的浏览器（推荐 Chrome / Edge 最新版本）

  • 开发板通过 USB 数据线连接至电脑

警告

请使用 USB 数据线而非充电线。部分充电线不含数据引脚，连接后电脑无法识别串口设备。

烧录步骤

  1. 打开在线烧录页面。

  2. 在 "选择应用" 区域，依次从下拉菜单中选择 平台 和 应用固件。

  3. 在 "选择设备" 区域，选中对应的 开发板型号。

  4. 点击 "开始烧录" 按钮。浏览器弹出串口选择对话框，从列表中选择对应的 COM 口并确认。工具将自动下载并烧录固件，约需 1～2 分钟，期间请勿断开连接或关闭页面。

  5. 烧录日志显示 "烧录完成" 后即可进行 Wi-Fi 配置（参阅 Wi-Fi 配置）。

小技巧

如果串口列表中没有出现预期的 COM 端口，请检查 USB 连接是否稳固，或尝试重新插拔 USB 数据线。部分系统需要安装 USB 转串口驱动（如 CH340 / CP2102）。

手动烧录（命令行）

手动烧录适合开发者使用，例如需要自定义固件路径、集成到 CI/CD 流程或在无图形界面的环境中操作。普通用户建议使用在线烧录工具。

前置条件

  • 已安装 Python 3.8 或更高版本

  • 已克隆 AmebaClaw 代码仓库并完成编译环境配置

  • 开发板通过 USB 数据线连接至电脑，且系统已识别对应串口设备（如 /dev/ttyUSB0）

备注

在执行任何命令之前，请先在代码仓库根目录运行 source env.sh 初始化编译环境。未初始化环境时，ameba.py 命令将无法找到必要的工具链和配置文件。

烧录命令

按顺序执行以下命令完成编译与烧录：

# 1. 初始化编译环境（每次新开终端时均需执行）
source env.sh

# 2. 指定目标 SoC 型号
python ameba.py soc RTL8721F

# 3. 编译固件（将 /path/to/ameba_claw 替换为实际路径）
python ameba.py build -a /path/to/ameba_claw

# 4. 烧录固件到开发板（根据实际串口设备修改 -p 参数）
python ameba.py flash -p /dev/ttyUSB0 -b 1500000

# 5. 打开串口监视器查看运行日志
python ameba.py monitor -p /dev/ttyUSB0 -b 1500000

参数说明：

  • -p /dev/ttyUSB0：串口设备路径。Windows 系统上对应 COM3、COM4 等，请根据设备管理器中显示的端口号替换。

  • -b 1500000：波特率，烧录和监视均使用 1500000 bps。

小技巧

按 Ctrl+C 可退出串口监视器。监视器本身不会影响开发板的运行状态。