项目生成器(ameba-generate)

概述

ameba-generate 是 Ameba Rust SDK 的项目生成器,一条命令即可生成可直接编译、可直接烧录的裸机 Rust 应用——一个只包含 app 固件 crate 的 workspace,并已配置为使用 SDK 的 ameba-flash 工具作为 cargo runner,无需复制示例工程再手动修改。这是新建项目的推荐方式;手动方式见 快速入门 。

安装

该 crate 尚未发布到 crates.io,需从源码安装:

$ git clone https://github.com/Ameba-AIoT/ameba-generate.git
$ cd ameba-generate
$ cargo install --path . --locked

确认安装:

$ ameba-generate --version
ameba-generate 0.1.0

备注

ameba-generate 还需要 rustfmt 组件,用于格式化生成项目的源码:

$ rustup component add rustfmt

编译和烧录生成的项目还需要 Rust 工具链和 ameba-flash,参见 开发环境搭建 。

快速开始

交互式 TUI(推荐)

不带任何参数运行:

$ ameba-generate

系统会依次提示输入项目名和 SDK 路径。如果不想每次输入 SDK 路径,可以用 --sdk 预先指定,提示中会显示为默认值,直接回车即可接受:

$ ameba-generate --sdk <path/to/rust>
Project name: my-app
SDK path [<path/to/rust>]:

随后进入全屏菜单勾选选项:

┌─────────────────────────────────────────────────────┐
│  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   │
└─────────────────────────────────────────────────────┘

按键

操作

↑ / k、↓ / j

移动光标

Space / Enter

切换光标所在选项

g / s

校验并生成项目

q / Esc

取消退出

同一分组内的选项互斥(目前只有 Chip 一个分组):选中一个会自动取消另一个。取消某选项时,依赖它的选项也会一并取消(例如取消 Embassy 会连带取消 Wi-Fi)。未满足依赖时按 g 只会在底部显示红色错误提示,不会退出。

命令行(无头)模式

适用于 CI 环境和脚本调用。在非 TTY 环境下会自动进入该模式,也可用 --headless 显式指定;此外,只要传入了项目名或任一 -o 选项,也会进入该模式,此时必须指定 --sdk:

$ 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

生成器会在新项目中执行 git init。已安装 git 但未配置 init.defaultBranch 时,上面几行输出之前会先出现 git 打印的 hint: Using 'master' as the name for the initial branch ...;未安装 git 时仍可正常生成,只会打印 warning: could not run git init: program not found。

查看所有可用选项:

$ 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

可用选项

选项

说明

备注

rtl8721f

RTL8721F ——必选,芯片分组必须选一个

会设置 thumbv8m.main-none-eabi target

embassy

Embassy 异步运行时(executor + time)

——

wifi

添加 ameba-wifi 依赖,并在启动时以 STA 模式启动 Wi-Fi:注册 WHC 处理函数、启动 run_blk_api() 后台任务并调用 wifi_on()

依赖 embassy。连接 AP 需自行实现——参照 SDK 的 examples/wifi-connect 中的 wifi_connect、DHCP 与 TCP 流程

生成的项目结构

以选择 rtl8721f + embassy 为例:

my-app/
├── .git/                  ← 自动执行 git init 生成
├── .gitignore             ← 忽略 /target
├── Cargo.toml             ← workspace 根(members = ["app"])
├── rust-toolchain.toml    ← 工具链锁定(stable)
└── app/                   ← 固件 crate,在此目录下运行 `cargo build` / `cargo run`
    ├── .cargo/
    │   └── config.toml    ← ARM target、linker、rustflags、ameba-flash runner
    ├── Cargo.toml         ← 依赖声明(ameba-hal、ameba-rt 等)
    └── src/
        └── main.rs        ← 应用入口

选中 wifi 选项时目录结构不变:app/Cargo.toml 会增加 ameba-wifi 依赖,Wi-Fi 启动代码直接生成在 main.rs 中。

为什么 target 配置放在 app/.cargo/config.toml

Cargo 会将某个目录下的 .cargo/config.toml 应用到该目录及其下所有的包。ARM target、链接参数和烧录 runner 都放在 app/.cargo/config.toml 中,只对 app crate 生效;在 workspace 根目录编译会使用主机 target(见 常见错误 )。

app/.cargo/config.toml 内容:

[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",
]

编译生成的项目

cargo build 必须在 app/ 子目录下运行,才能读到 app/.cargo/config.toml 中的 ARM target 配置:

$ cd my-app/app
$ cargo build              # 调试版
$ cargo build --release    # 发布版(opt-level=z,panic=abort)

编译产物是 ELF 文件。app crate 属于 my-app workspace,因此产物位于 workspace 根目录的 target/ 下:

target/thumbv8m.main-none-eabi/debug/my-app
target/thumbv8m.main-none-eabi/release/my-app

烧录(ameba-flash runner)

生成的项目使用 Rust SDK 的 ameba-flash 工具作为 cargo runner。cargo run 编译出 ELF 后交给 ameba-flash,由它提取可加载段、打包 app.bin,与 Bootloader 一起通过串口烧录,并打开串口监视。

从生成时 --sdk 指定的 Rust SDK 目录安装一次 ameba-flash (另见 开发环境搭建 ):

$ cargo install --path <rust-sdk>/ameba-flash --locked

Bootloader、Wi-Fi 核固件和 Flash Loader 均已内嵌在可执行文件中。请确认 ~/.cargo/bin 已加入 PATH。

备注

请在 Rust SDK 目录下执行 cargo install。如果提示默认工具链被 rust-toolchain.toml 覆盖,可改用 cargo +stable install --path <rust-sdk>/ameba-flash --locked。重复安装会替换之前已安装的 ameba-flash。

烧录并监视串口:

$ cd my-app/app
$ cargo run --release -- --port /dev/ttyUSB0      # Windows 上为 COM29 等

串口也可以通过环境变量 RTK_SERIAL_PORT 指定:

$ export RTK_SERIAL_PORT=/dev/ttyUSB0
$ cargo run --release

开发板正在运行正常固件时会自动重启进入下载模式;否则请手动让开发板进入下载模式。按 Ctrl-C 退出串口监视。

生成的模板只在启动时打印一次 my-app running,之后空转不再输出,串口监视窗口停在该行属正常现象。

备注

--port 前面的 -- 不能省略,它用于分隔 cargo run 自身的参数与转发给 runner 的参数。