Troubleshooting
This page covers the errors most commonly reported by ameba-generate and by the generated project, in the order you are likely to hit them: option selection, SDK path resolution, building the generated project, then flashing it with the ameba-flash runner.
No Chip Selected (Headless Mode)
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.
Cause: headless mode requires an explicit -o for every required option group, and chip is required.
Fix: add -o rtl8721f.
wifi Selected Without embassy
Error: option 'wifi' requires 'embassy' to also be selected.
Fix: select both, e.g. -o embassy -o wifi.
SDK Path Does Not Exist
Error: SDK path does not exist: /path/to/rust
Fix: confirm --sdk points at the Ameba Rust SDK checkout.
--sdk Does Not Point at a Rust SDK Checkout
Error: '/tmp' does not look like an Ameba Rust SDK checkout (missing ameba-hal/Cargo.toml).
This is checked up front so a wrong --sdk fails immediately, rather than surfacing much later as an unresolvable path dependency when cargo build runs inside the generated project.
Fix: pass the Rust SDK repository root — the directory containing ameba-hal/Cargo.toml.
Destination Already Exists
Error: destination 'my-app' already exists
Fix: remove or rename the existing directory, or choose a different project name.
cargo build Fails with unknown directive .thumb_func
This means cargo build ran from the wrong directory and picked up the host (x86) target instead of the ARM target configured in app/.cargo/config.toml.
$ cd my-app/app && cargo build # correct
$ cd my-app && cargo build # wrong — reads the workspace root config, no ARM target
$ cargo build --manifest-path app/Cargo.toml # wrong — does not read app/.cargo/config.toml
Fix: always run cargo build from inside app/.
cargo run: ameba-flash Not Found
error: could not execute process `ameba-flash flash --monitor <path>/target/thumbv8m.main-none-eabi/release/my-app` (never executed)
Cause: the runner configured in app/.cargo/config.toml is not installed, or ~/.cargo/bin is not on PATH.
Fix: install it from the Rust SDK checkout, and make sure ~/.cargo/bin is on PATH:
$ cargo install --path <rust-sdk>/ameba-flash --locked
cargo run: --port Not Provided
error: the following required arguments were not provided:
--port <PORT>
Usage: ameba-flash flash --port <PORT> --monitor <ELF>
For more information, try '--help'.
Cause: ameba-flash needs a serial port, and neither --port nor the RTK_SERIAL_PORT environment variable was given.
Fix: pass the port after --, or set the environment variable:
$ 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
The firmware is packaged first, so the [package] and [pack] lines are printed before this error.
Cause: the serial port does not exist, or is already held by another program such as a serial terminal.
Fix: check the port name (/dev/ttyUSB* on Linux, COM* on Windows), and close any other program that has it open.
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
Cause: ameba-flash reboots a board running normal firmware into download mode by sending a command on its log UART. This does not work when the board’s firmware does not respond to it, or when the log UART is not at 1500000 baud.
Fix: put the board into download mode manually, then run cargo run again.