快速入门

本文档引导用户完成 Ameba Rust SDK 的环境搭建,并通过 Hello World 示例完成第一次编译、烧录与日志验证。

备注

下面的编译步骤编译的是 Rust SDK 中已有的 examples/hello-world 示例工程。如果要新建自己的项目,推荐使用 ameba-generate 一键生成,而不是手动复制示例工程。

准备工作

硬件:

  • Ameba 开发板(RTL8721F EVB)

  • USB Type-C 数据线

  • 开发主机:Linux (Ubuntu 22.04+)、Windows 10/11 或 macOS (13 Ventura+,仅限 Apple Silicon / M 系列芯片),磁盘空间 ≥ 10 GB

软件:

  • Git 2.0+

  • VS Code 或其他代码编辑器

  • USB 转串口驱动(若开发主机未自动识别)

硬件连接

用 USB Type-C 数据线连接开发板与开发主机,既用于烧录固件,也用于串口日志。

../../_images/sdk_quick_start_diagram.png

开发板详细用户指南:EVB User Guide

下载 SDK

Rust SDK 仓库包含固件源码与编译工具,以及每个应用打包和烧录时所需的预编译 Bootloader、Wi-Fi 核固件和 Flash Loader。

SDK 下载

环境搭建

安装 rustup 即可,stable 工具链和交叉编译 target 会依据 rust-toolchain.toml 自动安装。

开发环境搭建

编译

在 Rust SDK 根目录执行:

$ cd <workdir>/rust
$ cargo xtask build example --name hello-world

--name 为 examples/ 下的目录名,嵌套的示例用斜杠分隔,例如 --name gpio/basic。

编译成功后输出:

[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)

编译产出两个文件:

  • build/rtl8721f/app.bin:烧录用固件,包含 Wi-Fi 核固件和 Rust 应用固件。

  • build/rtl8721f/ota_all.bin:加了 OTA 头的同一份固件,用于 OTA 升级(见 OTA 指南 )。

烧录与日志监控

一条命令完成串口烧录并打开串口监视:

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

cargo xtask run example 会重新编译示例,将 boot.bin 和 app.bin 写入 Flash 并复位开发板,随后以 1500000 波特率持续打印串口日志,按 Ctrl-C 退出。开发板正在运行正常固件时会自动重启进入下载模式,无需按任何按键;否则请先手动让开发板进入下载模式再烧录。

不传 --port 时会读取环境变量 RTK_SERIAL_PORT,设置一次即可省略:

Linux / WSL:
$ export RTK_SERIAL_PORT=/dev/ttyUSB0
$ cargo xtask run example --name hello-world

Hello World 预期输出:

[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
...

其中 [run] not in download mode, rebooting into UART burn mode ... 表示 ameba-flash 正在自动让开发板重启进入下载模式,属正常现象。上面省略了 [package] 之前 cargo 的编译输出。

备注

各示例的 .cargo/config.toml 也已将 ameba-flash 配置为 cargo runner。安装一次 ameba-flash 后(见 开发环境搭建 ),可以直接在示例目录下用 cargo run 完成编译、烧录和日志监控:

$ cd <workdir>/rust/examples/hello-world
$ cargo run --release -- --port <串口>

其中的 -- 不能省略,它用于分隔 cargo run 自身的参数与转发给 ameba-flash 的参数。

如只需查看日志而不重新烧录,可用任意串口工具以 1500000 波特率连接开发板,复位后即可看到运行日志。

Log 工具