Project Generator (ameba-generate)
Overview
ameba-generate is a CLI project generator for the Ameba Rust SDK. One command generates a ready-to-compile, ready-to-flash bare-metal Rust application — a workspace with a single app firmware crate, configured to use the SDK’s ameba-flash tool as its cargo runner — instead of copying and hand-editing an example project. This is the recommended way to start a new project; see
Quick Start
for the manual alternative.
Install
The crate is not yet published to crates.io, so install it from source:
$ git clone https://github.com/Ameba-AIoT/ameba-generate.git
$ cd ameba-generate
$ cargo install --path . --locked
Confirm the install:
$ ameba-generate --version
ameba-generate 0.1.0
Note
ameba-generate also requires the rustfmt component, used to format the generated project’s source files:
$ rustup component add rustfmt
To build and flash the generated project you also need the Rust toolchain and ameba-flash, see
Development Environment Setup
.
Quick Start
Interactive TUI (recommended)
Run with no arguments:
$ ameba-generate
You are prompted for the project name and SDK path. To skip typing the SDK path, pass it with --sdk; the prompt shows it as the default and pressing Enter accepts it:
$ ameba-generate --sdk <path/to/rust>
Project name: my-app
SDK path [<path/to/rust>]:
Then a full-screen menu lets you toggle options:
┌─────────────────────────────────────────────────────┐
│ ameba-generate — Select options │
├─────────────────────────────────────────────────────┤
│ ▸ Chip │
│ ► [✓] RTL8721F │
│ [✓] Embassy (async runtime) │
│ [ ] Wi-Fi (ameba-wifi, STA bring-up) │
├─────────────────────────────────────────────────────┤
│ Adds embassy-executor and embassy-time for │
│ async/await support. │
├─────────────────────────────────────────────────────┤
│ ↑↓ navigate Space toggle g generate q quit │
└─────────────────────────────────────────────────────┘
Key |
Action |
|---|---|
|
Move the cursor |
|
Toggle the option under the cursor |
|
Validate and generate the project |
|
Cancel and quit |
Options in the same group (currently only Chip) are mutually exclusive — selecting one deselects the other. Deselecting an option also deselects anything that requires it (for example, deselecting Embassy also deselects Wi-Fi). Pressing g with an unmet requirement shows a red error at the bottom instead of exiting.
Headless Mode
For CI and scripted use. Headless mode is entered automatically outside a TTY, explicitly with --headless, or whenever a project name or any -o option is passed — in that case --sdk is required:
$ ameba-generate --sdk <path/to/rust> -o rtl8721f -o embassy my-app --headless
✓ Generated project 'my-app' (sdk: <path/to/rust>)
Selected options: rtl8721f, embassy
cd my-app/app && cargo build
cd my-app/app && cargo run --release -- --port <PORT> # package + flash
The generator runs git init in the new project. If git is installed but init.defaultBranch is not configured, git prints hint: Using 'master' as the name for the initial branch ... before the lines above; if git is not installed, generation still succeeds and prints warning: could not run git init: program not found.
List all available options:
$ ameba-generate list-options
Available options:
[chip] Chip
Select the target Ameba SoC.
-o rtl8721f (group: chip) — RTL8721F
-o embassy — Embassy (async runtime)
Adds embassy-executor and embassy-time for async/await support.
-o wifi — Wi-Fi (ameba-wifi, STA bring-up)
Adds the ameba-wifi dependency and brings Wi-Fi up in STA mode at startup (WHC handlers,
background task, wifi_on). Connecting to an AP is left to you — see the SDK's
examples/wifi-connect.
requires: embassy
Required groups: chip
Available Options
Option |
Description |
Notes |
|---|---|---|
|
RTL8721F — required, exactly one chip must be selected |
Sets the |
|
Embassy async runtime (executor + time) |
— |
|
Adds the |
Requires |
Generated Project Structure
With rtl8721f + embassy selected:
my-app/
├── .git/ ← created by an automatic git init
├── .gitignore ← ignores /target
├── Cargo.toml ← workspace root (members = ["app"])
├── rust-toolchain.toml ← toolchain lock (stable)
└── app/ ← the firmware crate — run `cargo build` / `cargo run` from here
├── .cargo/
│ └── config.toml ← ARM target, linker, rustflags, ameba-flash runner
├── Cargo.toml ← dependencies (ameba-hal, ameba-rt, ...)
└── src/
└── main.rs ← application entry point
With the wifi option selected, the layout is the same; ameba-wifi is added to app/Cargo.toml
and the Wi-Fi bring-up code is generated directly in main.rs.
Why the Target Configuration Lives in app/.cargo/config.toml
Cargo applies a .cargo/config.toml to the directory it lives in and every package under it. The
ARM target, linker flags and flash runner are kept in app/.cargo/config.toml so they apply to the
app crate only; building from the workspace root uses the host target instead (see
Troubleshooting
).
app/.cargo/config.toml contents:
[build]
target = "thumbv8m.main-none-eabi"
[target.thumbv8m.main-none-eabi]
linker = "rust-lld"
runner = "ameba-flash flash --monitor"
rustflags = [
"-Clink-arg=-Tameba.x",
"-Clink-arg=--gc-sections",
"-Clink-arg=--nmagic",
]
Building the Generated Project
cargo build must run from the app/ subdirectory, so it picks up the ARM target configuration in app/.cargo/config.toml:
$ cd my-app/app
$ cargo build # debug
$ cargo build --release # release (opt-level=z, panic=abort)
The build output is an ELF file. The app crate is a member of the my-app workspace, so it lands in the workspace root’s target/ directory:
target/thumbv8m.main-none-eabi/debug/my-app
target/thumbv8m.main-none-eabi/release/my-app
Flashing (ameba-flash Runner)
The generated project uses the Rust SDK’s ameba-flash tool as its cargo runner. cargo run builds
the ELF, then hands it to ameba-flash, which extracts the loadable sections, packages app.bin,
flashes it over UART together with the Bootloader, and opens a serial monitor.
Install ameba-flash once from the Rust SDK checkout passed to --sdk at generation time (see also
Development Environment Setup
):
$ cargo install --path <rust-sdk>/ameba-flash --locked
The Bootloader, Wi-Fi core firmware and flash loader are embedded in the binary. Make sure ~/.cargo/bin is on PATH.
Note
Run cargo install from the Rust SDK checkout. If it prints a warning that the default toolchain is
overridden by a rust-toolchain.toml, use cargo +stable install --path <rust-sdk>/ameba-flash --locked.
Installing again replaces any previously installed ameba-flash.
Flash and monitor:
$ cd my-app/app
$ cargo run --release -- --port /dev/ttyUSB0 # or COM29 on Windows
The port can also come from the RTK_SERIAL_PORT environment variable:
$ export RTK_SERIAL_PORT=/dev/ttyUSB0
$ cargo run --release
If the board is running normal firmware it reboots into download mode by itself; otherwise reset it into
download mode manually. Stop the monitor with Ctrl-C.
The generated template prints my-app running once at startup and then idles silently, so the serial
monitor shows no further output after that line. This is normal.
Note
The -- before --port is required: it separates cargo run’s own arguments from the ones
forwarded to the runner.