常见错误
本页收录 ameba-generate 及其生成的项目最常见的报错,按遇到的先后顺序排列:先是选项校验,然后是 SDK 路径探测,再是编译生成的项目,最后是用 ameba-flash runner 烧录。
无头模式未选芯片
Error: No option selected for required group 'chip'.
Use -o <chip> where <chip> is one of: rtl8721f
Run `ameba-generate list-options` for the full list.
原因:无头模式下每个必选分组都要显式传 -o,chip 是必选分组。
解决:加上 -o rtl8721f。
选了 wifi 但没选 embassy
Error: option 'wifi' requires 'embassy' to also be selected.
解决:同时加上 -o embassy -o wifi。
SDK 路径不存在
Error: SDK path does not exist: /path/to/rust
解决:确认 --sdk 指向的是 Ameba Rust SDK 的检出目录。
--sdk 指向的不是 Rust SDK 检出
Error: '/tmp' does not look like an Ameba Rust SDK checkout (missing ameba-hal/Cargo.toml).
这项检查提前拦下了错误的 --sdk,否则错误会拖到生成项目里执行 cargo build 时,才以"找不到 path dependency"的形式出现,离病根很远。
解决:指向含 ameba-hal/Cargo.toml 的目录,即 Rust SDK 仓库根。
目标目录已存在
Error: destination 'my-app' already exists
解决:删除或重命名已有目录,或换一个项目名。
cargo build 报 unknown directive .thumb_func
说明 cargo build 在错误的目录下运行,读到的是宿主机(x86)target,而不是 app/.cargo/config.toml 里配置的 ARM target。
$ cd my-app/app && cargo build # 正确
$ cd my-app && cargo build # 错误——读到 workspace 根的配置,没有 ARM target
$ cargo build --manifest-path app/Cargo.toml # 错误——不会读 app/.cargo/config.toml
解决:必须在 app/ 目录下运行 cargo build。
cargo run 报找不到 ameba-flash
error: could not execute process `ameba-flash flash --monitor <path>/target/thumbv8m.main-none-eabi/release/my-app` (never executed)
原因: app/.cargo/config.toml 中配置的 runner 未安装,或 ~/.cargo/bin 不在 PATH 中。
解决:从 Rust SDK 目录安装,并确认 ~/.cargo/bin 已加入 PATH:
$ cargo install --path <rust-sdk>/ameba-flash --locked
cargo run 报未提供 --port
error: the following required arguments were not provided:
--port <PORT>
Usage: ameba-flash flash --port <PORT> --monitor <ELF>
For more information, try '--help'.
原因: ameba-flash 需要指定串口,但既没有传 --port,也没有设置环境变量 RTK_SERIAL_PORT。
解决:在 -- 之后传入串口,或设置环境变量:
$ cargo run --release -- --port /dev/ttyUSB0
$ export RTK_SERIAL_PORT=/dev/ttyUSB0
$ cargo run --release
cargo run 报 failed to open <port>
[run] flashing on /dev/ttyUSB99 ...
error: failed to open /dev/ttyUSB99: No such file or directory
固件会先完成打包,所以该错误之前会先打印 [package] 和 [pack] 行。
原因:串口不存在,或已被串口终端等其他程序占用。
解决:检查串口名(Linux 上为 /dev/ttyUSB*,Windows 上为 COM*),并关闭占用该串口的其他程序。
cargo run 报 ROM handshake failed
[run] ROM handshake ...
[run] not in download mode, rebooting into UART burn mode ...
error: ROM handshake failed: SysProto; if the board's log UART is not at 1500000 baud, reset it into download mode manually
原因: ameba-flash 通过在 log UART 上发送命令,让正在运行正常固件的开发板重启进入下载模式。如果开发板上的固件不响应该命令,或 log UART 波特率不是 1500000,这一步就会失败。
解决:手动让开发板进入下载模式后,重新执行 cargo run。