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.

../../_images/sdk_quick_start_diagram.png

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.

SDK Download

Environment Setup

Install rustup. The stable toolchain and cross-compilation targets are then installed automatically from rust-toolchain.toml.

Development Environment Setup

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:

Linux / WSL:
$ cargo xtask run example --name hello-world --port /dev/ttyUSB0

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:

Linux / WSL:
$ export RTK_SERIAL_PORT=/dev/ttyUSB0
$ 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.

Log Tool