Quick Start
This guide walks you through setting up the Ameba Rust SDK environment and completing your first build, flash, and log verification with the Hello World example.
Note
The build steps below compile the examples/hello-world project already checked into the
Rust SDK. For a new project of your own,
ameba-generate
is the recommended way to generate it instead of copying an example by hand.
Prerequisites
Hardware:
Ameba development board (RTL8721F EVB)
USB Type-C cable
Host machine: Linux (Ubuntu 22.04+), Windows 10/11, or macOS (13 Ventura+, Apple Silicon / M-series only), and ≥ 10 GB free disk space
Software:
Git 2.0+
VS Code or another code editor
USB-to-serial driver (if not auto-detected by the host OS)
Hardware Connection
Connect the development board to the host machine with a USB Type-C cable. The same connection is used for both firmware flashing and serial log output.
Board detailed user guide: EVB User Guide
SDK Download
The Rust SDK repository contains the firmware source code and build tooling, along with the prebuilt Bootloader, Wi-Fi core firmware and flash loader that every application is packaged and flashed with.
Environment Setup
Install rustup. The stable toolchain and cross-compilation targets are then installed automatically
from rust-toolchain.toml.
Build
Run the following from the Rust SDK root:
$ cd <workdir>/rust
$ cargo xtask build example --name hello-world
--name is the directory name under examples/. Nested examples use a slash-separated path,
for example --name gpio/basic.
Expected output on success:
[run] cd ".../examples/hello-world" && CARGO_TARGET_DIR=".../build/rtl8721f/cargo" "cargo" "build" "--release" "--target" "thumbv8m.main-none-eabi"
Compiling hello-world v0.1.0 (.../examples/hello-world)
Finished `release` profile [optimized] target(s) in ...
[package] xip=...B sram=...B psram=...B total=...B
[package] build/rtl8721f/km4tz_image2_all.bin
[pack] cert=4096B manifest=4096B km4ns=...B km4tz=...B app=...B
[pack] ota image_size=...B checksum=...
[done] app.bin → build/rtl8721f/app.bin (... bytes)
[done] ota_all.bin → build/rtl8721f/ota_all.bin (... bytes)
The build produces two files:
build/rtl8721f/app.bin: the flash image, containing the Wi-Fi core firmware and the Rust application firmware.build/rtl8721f/ota_all.bin: the same image with an OTA header, used for OTA upgrades (see OTA Guide ).
Flash and Monitor
Flash over UART and open a serial monitor in one step:
$ cargo xtask run example --name hello-world --port /dev/ttyUSB0
cargo xtask run example --name hello-world --port COM29
$ cargo xtask run example --name hello-world --port /dev/cu.usbserial-xxxx
cargo xtask run example rebuilds the example, writes boot.bin and app.bin to flash, resets
the board, then prints the serial log at 1500000 baud until you press Ctrl-C. If the board is
running normal firmware it is rebooted into download mode automatically, so there is no need to hold
any button; otherwise, put the board into download mode manually before flashing.
When --port is omitted, the serial port is read from the RTK_SERIAL_PORT environment variable,
so it can be set once:
$ export RTK_SERIAL_PORT=/dev/ttyUSB0
$ cargo xtask run example --name hello-world
$env:RTK_SERIAL_PORT = "COM29"
cargo xtask run example --name hello-world
$ export RTK_SERIAL_PORT=/dev/cu.usbserial-xxxx
$ cargo xtask run example --name hello-world
Expected Hello World output:
[package] xip=...B sram=...B psram=...B total=...B
[package] build/rtl8721f/km4tz_image2_all.bin
[pack] cert=4096B manifest=4096B km4ns=...B km4tz=...B app=...B
[pack] ota image_size=...B checksum=...
[done] app.bin → build/rtl8721f/app.bin (... bytes)
[done] ota_all.bin → build/rtl8721f/ota_all.bin (... bytes)
[run] flashing on /dev/ttyUSB0 ...
[run] ROM handshake ...
[run] not in download mode, rebooting into UART burn mode ...
[run] loading floader ...
[run] floader handshake ...
[run] pre-flight checks ...
[run] downloading boot.bin ...
[run] boot.bin: 100%
[run] downloading app.bin ...
[run] app.bin: 100%
[run] resetting device ...
[run] flash done.
[run] monitoring /dev/ttyUSB0 @ 1500000 (Ctrl-C to stop) ...
Hello World
Hello World
...
The [run] not in download mode, rebooting into UART burn mode ... line means ameba-flash is
rebooting the board into download mode by itself; it is normal. The cargo build lines printed before
[package] are omitted above.
Note
Each example’s .cargo/config.toml also sets ameba-flash as the cargo runner. After installing
ameba-flash once (see
Development Environment Setup
),
an example can be built, flashed and monitored with plain cargo run from its own directory:
$ cd <workdir>/rust/examples/hello-world
$ cargo run --release -- --port <serial-port>
The -- is required: it separates cargo run’s own arguments from the ones forwarded to
ameba-flash.
To view the log without reflashing, connect any serial terminal to the board at 1500000 baud and reset the board.