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

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

RTL8721F — required, exactly one chip must be selected

Sets the thumbv8m.main-none-eabi target

embassy

Embassy async runtime (executor + time)

—

wifi

Adds the ameba-wifi dependency and brings Wi-Fi up in STA mode at startup: registers the WHC handlers, spawns the run_blk_api() background task and calls wifi_on()

Requires embassy. Connecting to an AP is left to you — see the SDK’s examples/wifi-connect for wifi_connect, DHCP and TCP

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.