embassy-rs/embassy
GitHub: embassy-rs/embassy
Embassy 是一个基于 Rust 异步特性的现代嵌入式开发框架，通过编译期状态机实现高效多任务，为资源受限设备提供安全、节能的裸机开发方案。
Stars: 9013 | Forks: 1435
# Embassy
Embassy 是新一代嵌入式应用框架。使用 Rust 编程语言、其 async 特性以及 Embassy 库，可以更快地编写安全、正确且节能的嵌入式代码。
## [文档](https://embassy.dev/book/index.html) - [API 参考](https://docs.embassy.dev/) - [网站](https://embassy.dev/) - [聊天](https://matrix.to/#/#embassy-rs:matrix.org)
## Rust + async ❤️ embedded
Rust 编程语言速度极快且内存效率高，没有运行时、垃圾回收器或 OS。得益于其全面的内存和线程安全性以及富有表现力的类型系统，它可以在编译时捕获各种 bug。
Rust 的 [async/await](https://rust-lang.github.io/async-book/) 使得在嵌入式系统中进行前所未有的简单高效的多任务处理成为可能。任务在编译时被转换为协作运行的状态机。它不需要动态内存分配，并在单个栈上运行，因此无需针对每个任务调整栈大小。它使得带有内核上下文切换的传统 RTOS 变得过时，并且比传统 RTOS [更快、更小](https://tweedegolf.nl/en/blog/65/async-rust-vs-rtos-showdown)！
## 开箱即用
- **硬件抽象层**
- HAL 实现了安全、符合 Rust 惯用法的 API 以使用硬件功能，因此无需操作原始寄存器。Embassy 项目为特定硬件维护 HAL，但你仍然可以在 Embassy 中使用其他项目的 HAL。
- [embassy-stm32](https://docs.embassy.dev/embassy-stm32/)，适用于所有 STM32 微控制器系列。
- [embassy-nrf](https://docs.embassy.dev/embassy-nrf/)，适用于 Nordic Semiconductor nRF52、nRF53、nRF54 和 nRF91 系列。
- [embassy-rp](https://docs.embassy.dev/embassy-rp/)，适用于 Raspberry Pi RP2040 和 RP23xx 微控制器。
- [embassy-mspm0](https://docs.embassy.dev/embassy-mspm0/)，适用于 Texas Instruments MSPM0 微控制器。
- [embassy-mcxa](https://docs.embassy.dev/embassy-mcxa/)，适用于 NXP 的 MCX-A 系列微控制器。
- [esp-rs](https://github.com/esp-rs)，适用于 Espressif Systems ESP32 系列芯片。
- 针对 Espressif 芯片的 Embassy HAL 支持，以及 Async Wi-Fi、Bluetooth 和 ESP-NOW，正在 [esp-rs/esp-hal](https://github.com/esp-rs/esp-hal) 仓库中开发。
- [ch32-hal](https://github.com/ch32-rs/ch32-hal)，适用于 WCH 32 位 RISC-V(CH32V) 系列芯片。
- [mpfs-hal](https://github.com/AlexCharlton/mpfs-hal)，适用于 Microchip PolarFire SoC。
- [py32-hal](https://github.com/py32-rs/py32-hal)，适用于 Puya Semiconductor PY32 系列微控制器。
- **开箱即用的时间管理** -
不再需要摆弄硬件定时器。[embassy_time](https://docs.embassy.dev/embassy-time) 提供了全局可用且永不过期的 Instant、Duration 和 Timer 类型。
- **实时就绪** -
同一个 async executor 上的任务协作运行，但你可以创建具有不同优先级的多个 executor，以便高优先级任务抢占低优先级任务。请参阅[示例](https://github.com/embassy-rs/embassy/blob/main/examples/nrf52840/src/bin/multiprio.rs)。
- **低功耗就绪** -
轻松构建具有数年电池寿命的设备。当没有工作要做时，async executor 会自动让核心进入睡眠状态。任务由中断唤醒，等待时没有忙循环轮询。
- **网络** -
[embassy-net](https://docs.embassy.dev/embassy-net/) 网络栈实现了广泛的网络功能，包括 Ethernet、IP、TCP、UDP、ICMP 和 DHCP。Async 极大地简化了超时管理和并发处理多个连接。
- **Bluetooth**
- [trouble](https://github.com/embassy-rs/trouble) crate 提供了 Bluetooth Low Energy 4.x 和 5.x Host，可在任何实现 [bt-hci](https://github.com/embassy-rs/bt-hci) traits 的微控制器上运行（目前支持
`nRF52`、`nrf54`、`rp2040`、`rp23xx` 和 `esp32` 以及 `serial` 控制器）。
- [nrf-softdevice](https://github.com/embassy-rs/nrf-softdevice) crate 为 nRF52 微控制器提供 Bluetooth Low Energy 4.x 和 5.x 支持。
- [embassy-stm32-wpan](https://github.com/embassy-rs/embassy/tree/main/embassy-stm32-wpan) crate 为 stm32wb 微控制器提供 Bluetooth Low Energy 5.x 支持。
- **LoRa** -
[lora-rs](https://github.com/lora-rs/lora-rs) 项目提供了一个 async LoRa 和 LoRaWAN 协议栈，可在 Embassy 上良好运行。
- **USB** -
[embassy-usb](https://docs.embassy.dev/embassy-usb/) 实现了设备端 USB 协议栈。提供了常见类（如 USB serial (CDC ACM) 和 USB HID）的实现，并且丰富的 builder API 允许构建你自己的类。
- **Bootloader 和 DFU** -
[embassy-boot](https://github.com/embassy-rs/embassy/tree/main/embassy-boot) 是一个轻量级 bootloader，支持以防掉电的方式升级固件应用，具有试启动和回滚功能。
## 抢先看
```
use defmt::info;
use embassy_executor::Spawner;
use embassy_time::{Duration, Timer};
use embassy_nrf::gpio::{AnyPin, Input, Level, Output, OutputDrive, Pin, Pull};
use embassy_nrf::{Peri, Peripherals};
// Declare async tasks
#[embassy_executor::task]
async fn blink(pin: Peri<'static, AnyPin>) {
let mut led = Output::new(pin, Level::Low, OutputDrive::Standard);
loop {
// Timekeeping is globally available, no need to mess with hardware timers.
led.set_high();
Timer::after_millis(150).await;
led.set_low();
Timer::after_millis(150).await;
}
}
// Main is itself an async task as well.
#[embassy_executor::main]
async fn main(spawner: Spawner) {
let p = embassy_nrf::init(Default::default());
// Spawned tasks run in the background, concurrently.
spawner.spawn(blink(p.P0_13.into()).unwrap());
let mut button = Input::new(p.P0_11, Pull::Up);
loop {
// Asynchronously wait for GPIO events, allowing other tasks
// to run, or the core to sleep.
button.wait_for_low().await;
info!("Button pressed!");
button.wait_for_high().await;
info!("Button released!");
}
}
```
## 示例
示例位于
`examples/` 文件夹中，按其设计运行的芯片制造商进行分类。例如：
* `examples/nrf52840` 运行于
`nrf52840-dk` 板 (PCA10056)，但应能轻松适配其他 nRF52 芯片和板卡。
* `examples/nrf5340` 运行于 `nrf5340-dk` 板 (PCA10095)。
* `examples/stm32xx` 用于各种 STM32 系列。
* `examples/rp` 用于 RP2040 和 RP235x 芯片。
* `examples/mcxa` 运行于 `FRDM-MCXA266` 板。
* `examples/std` 设计为在你的 PC 本地运行。
### 运行示例
- 按照 上的说明安装 `probe-rs`。
- 切换目录到示例的基础目录。例如：
```
cd examples/nrf52840
```
- 确保 `Cargo.toml` 为你正在编程的芯片名称设置了正确的 feature。
如果此名称不正确，示例可能会运行失败或在被编程后立即崩溃。
- 确保 `.cargo/config.toml` 包含你正在编程的芯片名称。
- 运行示例
例如：
```
cargo run --release --bin blinky
```
有关入门的更多帮助，请参阅 [入门指南][1] 和 [运行示例][2]。
## 使用基于 Rust Analyzer 的编辑器开发 Embassy
[Rust Analyzer](https://rust-analyzer.github.io/) 被 [Visual Studio Code](https://code.visualstudio.com/)
及其他编辑器使用。鉴于 Embassy 服务于多个目标平台，因此没有 Cargo workspace 文件。相反，必须告诉 Rust Analyzer 要处理的目标项目。对于 Visual Studio Code，
请参阅 `.vscode/settings.json` 文件中的 `rust-analyzer.linkedProjects` 设置。
## 最低支持的 Rust 版本 (MSRV)
Embassy 保证在 stable Rust 1.75 及更高版本上编译。它*可能*
可以在旧版本上编译，但这可能会在任何新的补丁版本中发生变化。
## 为什么叫这个名字？
EMBedded ASYnc! :)
## 许可证
Embassy 根据以下任一许可证授权：
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) 或
)
- MIT license ([LICENSE-MIT](LICENSE-MIT) 或 )
由你选择。
## 贡献
除非你明确声明，否则根据 Apache-2.0 许可证的定义，你有意提交以包含在工作中的任何贡献，
均应按上述方式双重许可，无需任何额外条款或条件。
标签：async/await, Embassy, HAL, IoT, MCXA, MSPM0, nRF, RP2040, Rust, STM32, 低功耗, 内存安全, 单片机, 可视化界面, 固件开发, 嵌入式开发, 嵌入式框架, 嵌入式系统, 并发, 开发框架, 异步编程, 微控制器, 无OS, 物联网, 状态机, 硬件抽象层, 网络流量审计, 裸机编程, 通知系统, 驱动库