Ivan's Blog
主题

Async embedded

Async embedded 表示嵌入式 Rust 代码把 async 当成正式 API surface 或正式 runtime contract 来维护，而不是只在某个样例里顺手用了异步。

  • 硬件

目录

Definition

Async embedded 表示嵌入式 Rust 代码把 async 当成正式 API surface 或正式 runtime contract 来维护，而不是只在某个样例里顺手用了异步。它常见于两类场景：一类是 driver crate 通过 feature-gating 同时支持 sync/async；另一类是 firmware/product repo 直接把 Embassy 或同类 async runtime 当作任务调度基础。

这个 Topic 的重点不是“用了 Future”，而是维护者需要回答 async 在系统里承担什么角色。它通常和 Embedded Rust、embedded-hal driver、I2C 一起出现，但不替代这些相邻 Topic：Async embedded 解释 runtime/concurrency 边界，其他 Topic 解释语言生态、driver 形态、总线协议或具体器件（projects/bq25730-rs.md、projects/loadlynx.md、projects/ups120.md）。

When to use

当 Cargo.toml、README、project snapshot 或 checked-in docs 明确写出 async API、embedded-hal-async、Embassy runtime、任务调度、feature-gated sync/async 支持，且这些选择会影响 crate API、firmware 结构或默认验证时使用。若 async 只存在于示例、实验分支或非主路径代码，不应命中。

如果一个改动会改变任务调度、driver API 的 sync/async 兼容、background tasks、并发资源访问、feature flags 或异步测试方式，就应该命中 Async embedded。代表样本里，projects/bq25730-rs.md、projects/bq769x0-async-rs.md、projects/ft6336u-async.md 体现的是“driver crate 的双模式 API”；projects/loadlynx.md、projects/ups120.md 体现的是“产品 firmware 把 async runtime 当正式执行模型”。这两类都属于本 Topic，但审查重点并不相同。

Habits / defaults

  • “sync + async” 更适合通过 feature flags 或 trait layering 共存，而不是复制两套 crate；这样可以保持寄存器语义、错误类型和核心 API 一致（projects/bq25730-rs.md、projects/bq769x0-async-rs.md）。
  • driver crate 若把 async 作为可选能力，就要明确对比同步用法的边界；否则下游 firmware 会不知道什么时候该启用 runtime、什么时候只需阻塞式访问（projects/ft6336u-async.md、projects/pca9546a-rs.md）。
  • firmware/product repo 中，async 往往意味着任务调度和后台刷新成为正式架构。像 projects/loadlynx.md、projects/ups120.md 这类仓库，评审时要把 UI/网络/传感器轮询/电源管理看成并发系统，而不是单循环固件。
  • async embedded 默认要检查共享资源 ownership。I2C bus、display bus、ADC 采样、网络栈或 power state 若跨任务共享，文档里要保留仲裁方式，否则后续改动容易引入时序性故障。
  • 对 crate 类项目，测试策略通常不是 HIL-first，而是 mock/trait-level 验证为主，再由下游 firmware 补真实板级验证；Topic 回答里应说明这一分工（projects/ina3221-async-rs.md）。
  • 对 firmware 类项目，async 相关改动默认需要核对 task spawn、poll/update cadence、背压和错误恢复，不能只看编译是否通过。

Reference implementations

  • projects/bq25730-rs.md：典型的 driver crate，适合说明 sync/async 双模式 API 应怎样共存。
  • projects/bq769x0-async-rs.md：电池管理类 driver，适合观察 feature-gated async support 如何保持 crate 复用性。
  • projects/ft6336u-async.md：触摸控制器 driver，适合说明 async 能力与具体器件交互边界如何结合。
  • projects/loadlynx.md：产品级 firmware 仓库，说明 async runtime 不只是 crate API，而是系统级调度骨架。
  • projects/ups120.md：带后台任务和电源行为的 firmware，适合补充“并发任务改变系统行为”的那一面。

Failure modes

  • 只因为依赖名或 crate 命名里有 async 就打标签，会让 Topic 失去判别力。
  • 把 Async embedded 当成整个仓库的总括标签，忽略 Embedded Rust、embedded-hal driver、I2C 等相邻 Topic，会让后续 Agent 无法判断真正要验证的是 runtime、协议、器件还是产品行为。
  • 对 driver crate 不写 sync/async 边界，会让下游不知道 feature flag 改动是否是 breaking change。
  • 对 firmware repo 只写“用了 Embassy”不写任务模型和共享资源边界，会让并发 bug 在 topic 层完全不可见。
  • 把 async 改动只当编译问题处理，而不审查 poll cadence、资源仲裁和错误恢复，通常会把最难复现的板级故障留到最后。

Evidence index

  • projects/bq25730-rs.md
  • projects/bq769x0-async-rs.md
  • projects/display-ambient-light-board-rs.md
  • projects/ft6336u-async.md
  • projects/gc9307-async-rs.md
  • projects/gc9d01-rs.md
  • projects/ina3221-async-rs.md
  • projects/isolarail.md
  • projects/loadlynx.md
  • projects/network-monitor-esp-rs-no-std.md
  • projects/pd-sink-stm32g431cbu6-rs.md
  • projects/sc8815-rs.md
  • projects/sk150c-kit.md
  • projects/sw2303-rs.md
  • projects/tca6424-rs.md
  • projects/tps55288-rs.md
  • projects/ups120.md
  • projects/xca9545a-async-rs.md
  • skills/style-playbook/references/data/topics/async-embedded.json

相关内容