embassy book

入门

很高兴你想尝试 Embassy!开始之前,你需要安装一些工具:

  • rustup - Rust 工具链是编译 Rust 代码所必需的。
  • probe-rs - 用于将固件刷入你的设备。如果你已经设置了其他工具,如 OpenOCD,你也可以使用它们。

如果你没有任何受支持的开发板,也不用担心:你也可以在你的 PC 上使用 std 示例运行 embassy。

获取带有示例的开发板

Embassy 支持许多微控制器系列,但最快的入门方式是使用 Embassy 已经为其编写了示例代码的开发板。

此列表并非详尽无遗。如果你的开发板未包含在此处,请查看 examples 文件夹 以查看是否已为其编写示例代码。

nRF 套件

STM32 套件

RP2040 套件

ESP32

运行示例

首先,你需要克隆 github 仓库

git clone https://github.com/embassy-rs/embassy.git
cd embassy

在你拥有仓库副本后,找到你的开发板的 examples 文件夹,并构建一个示例程序。blinky 是一个不错的选择,因为它所做的只是闪烁 LED - 嵌入式世界中相当于 "Hello World" 的程序。

cd examples/nrf52840
cargo build --bin blinky --release

一旦你确认可以构建示例,使用调试探针将你的计算机连接到你的开发板,并在硬件上运行它:

cargo run --bin blinky --release

如果一切正常,你应该在你的开发板上看到一个闪烁的 LED,并在你的计算机上看到类似于以下的调试输出:

    Finished dev [unoptimized + debuginfo] target(s) in 1m 56s
     Running `probe-run --chip STM32F407VGTx target/thumbv7em-none-eabi/debug/blinky`
(HOST) INFO  flashing program (71.36 KiB)
(HOST) INFO  success!
────────────────────────────────────────────────────────────────────────────────
0 INFO  Hello World!
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:18
1 INFO  high
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:23
2 INFO  low
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:27
3 INFO  high
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:23
4 INFO  low
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:27

注意:cargo run 命令如何知道如何连接到我们的开发板并对其进行编程?在每个 examples 文件夹中,都有一个 .cargo/config.toml 文件,该文件告诉 cargo 使用 probe-rs 作为该文件夹中 ARM 二进制文件的运行器。probe-rs 处理与调试探针和 MCU 的通信。为了使其工作,probe-rs 需要知道它正在编程哪个芯片,因此如果你想在其他芯片上运行示例,则必须编辑此文件。

它没有工作!

如果你在运行 cargo run --release 时遇到问题,请检查以下内容:

  • 你在命令行中指定了正确的 --chip,或者
  • 你已将 .cargo/config.toml 的 run 行设置为正确的芯片,并且
  • 你已更改 examples/Cargo.toml 的 HAL(例如 embassy-stm32)依赖项的功能以使用正确的芯片(替换现有的 stm32xxxx 功能)

此时,项目应该可以运行。例如,如果你没有看到 blinky 的闪烁 LED,请务必检查代码是否正在切换开发板的 LED 引脚。

如果你尝试使用 cargo run --release 运行示例,并且看到以下输出:

0.000000 INFO Hello World!
└─ <invalid location: defmt frame-index: 14>
0.000000 DEBUG rcc: Clocks { sys: Hertz(80000000), apb1: Hertz(80000000), apb1_tim: Hertz(80000000), apb2: Hertz(80000000), apb2_tim: Hertz(80000000), ahb1: Hertz(80000000), ahb2: Hertz(80000000), ahb3: Hertz(80000000) }
└─ <invalid location: defmt frame-index: 124>
0.000061 TRACE allocating type=Interrupt mps=8 interval_ms=255, dir=In
└─ <invalid location: defmt frame-index: 68>
0.000091 TRACE   index=1
└─ <invalid location: defmt frame-index: 72>

要消除 frame-index 错误,请将以下内容添加到你的 Cargo.toml 中:

[profile.release]
debug = 2

如果你收到一个非常长的错误消息,其中包含类似以下内容:

error[E0463]: can't find crate for `std`
  |
  = note: the `thumbv6m-none-eabi` target may not support the standard library
  = note: `std` is required by `stable_deref_trait` because it does not declare `#![no_std]`

请确保你没有意外运行 cargo add probe-rs(这会将其添加为依赖项),而是 正确安装 probe-rs

如果你使用的是 raspberry pi pico-w,请确保你运行的是 cargo run --bin wifi_blinky --release 而不是常规的 blinky。pico-w 的板载 LED 连接到 WiFi 芯片,需要在闪烁 LED 之前对其进行初始化。

如果你使用的是 rp2040 调试探针(例如 pico 探针),并且在运行 probe-rs info 后遇到问题,请拔下并重新连接探针,使其断电重启。 已知运行 probe-rs info 会使 pico 探针进入无法使用的状态

Embassy 开发 FAQ 链接 Embassy Matrix 频道

如果你仍然遇到问题,请查看 FAQ,或在 Embassy 聊天室 中寻求帮助。

接下来是什么?

恭喜,你的第一个 Embassy 应用程序正在运行!以下是一些后续步骤的建议: