3a90a8eb4a
711: Add DeviceStateHandler, DeviceCommand channel, and remote wakeup support r=Dirbaio a=alexmoon Apologies for the size of this PR. Once I started getting into the Vbus power management side of my device I found a couple of areas of functionality missing from embassy-usb. Specifically, I need the application to be able to respond to changes in the USB device state in order to properly control the amount of power I'm drawing from Vbus. I also wanted to enable remote wakeup support for my device. In order to enable device state monitoring, I've created a `DeviceStateHandler` trait and made it possible to pass in an optional reference a handler implementing that trait when creating the `UsbDeviceBuilder`. Remote wakeup required a way to send commands to the bus which is exclusively owned by the `UsbDevice::run` method. This is the same problem we were discussing for enabling/disabling the device on Vbus power events. My solution is to allow an optional `Channel` to be provided to the `UsbDeviceBuilder` (via `UsbDeviceBuilder::new_with_channel`), allowing the application to send commands into the `run` method. Right now it supports enable, disable and remote wakeup commands. Since there's now a way to dynamically enable and disable the device, I also added `Config::start_enabled` to control whether or not the `UsbDevice` should start in the enabled state. That also allowed me to make `UsbDeviceBuilder::build` sync again and move enabling the bus into `UsbDevice::run`. This led to a few driver changes: 1. `Driver::enable` became `Driver::into_bus` 2. `Bus::enable`, `Bus::disable`, and `Bus::remote_wakeup` were added 3. I removed `Bus::reset`, `Bus::suspend`, and `Bus::resume` because they were only ever called based on the result of `Bus::poll`. It made more sense to me to have `Bus::poll` handle the driver-specific state management itself. I've updated the `usb_hid_keyboard` example to take advantage of all these additional features. Let me know what you think. Thanks! Co-authored-by: alexmoon <alex.r.moon@gmail.com>
Embassy
Embassy is a project to make async/await a first-class option for embedded development. For more information and instructions to get started, go to https://embassy.dev.
Executor
The embassy::executor module provides an async/await executor designed for embedded usage.
- No
alloc, no heap needed. Task futures are statically allocated. - No "fixed capacity" data structures, executor works with 1 or 1000 tasks without needing config/tuning.
- Integrated timer queue: sleeping is easy, just do
Timer::after(Duration::from_secs(1)).await;. - No busy-loop polling: CPU sleeps when there's no work to do, using interrupts or
WFE/SEV. - Efficient polling: a wake will only poll the woken task, not all of them.
- Fair: a task can't monopolize CPU time even if it's constantly being woken. All other tasks get a chance to run before a given task gets polled for the second time.
- Creating multiple executor instances is supported, to run tasks with multiple priority levels. This allows higher-priority tasks to preempt lower-priority tasks.
Utils
embassy::util contains some lightweight async/await utilities, mainly helpful for async driver development (signaling a task that an interrupt has occured, for example).
HALs
Hardware Absraction Layers with asynchronous behaviors are provided for a variety of platforms.
For example, the embassy-nrf crate contains implementations for nRF 52 series SoCs.
-
uarte: UARTE driver implementingAsyncBufReadandAsyncWrite. -
qspi: QSPI driver implementingFlash. -
gpiote: GPIOTE driver. Allowsawaiting GPIO pin changes. Great for reading buttons or receiving interrupts from external chips. -
saadc: SAADC driver. Provides a full implementation of the one-shot sampling for analog channels. -
rtc: RTC driver implementingClockandAlarm, for use withembassy::executor.
Examples
Examples are found in the examples/ folder seperated by the chip manufacturer they are designed to run on. For example:
examples/nrfare designed to run on thenrf52840-dkboard (PCA10056) but should be easily adaptable to other nRF52 chips and boards.examples/rpare for the RP2040 chip.examples/stm32are designed for the STM32F429ZI chip but should be easily adaptable to other STM32F4xx chips.examples/stdare designed to run locally on your pc.
Running examples
- Setup git submodules (needed for STM32 examples)
git submodule init
git submodule update
- Install
probe-runwith defmt support.
cargo install probe-run
- Change directory to the sample's base directory. For example:
cd examples/nrf
- Run the example
For example:
cargo run --bin blinky
Developing Embassy with Rust Analyzer based editors
The Rust Analyzer is used by Visual Studio Code
and others. Given the multiple targets that Embassy serves, there is no Cargo workspace file. Instead, the Rust Analyzer
must be told of the target project to work with. In the case of Visual Studio Code,
please refer to the .vscode/settings.json file's rust-analyzer.linkedProjectssetting.
Minimum supported Rust version (MSRV)
Required nightly version is specified in the rust-toolchain.toml file. Nightly is required for:
generic_associated_types: for trait funcs returning futures.type_alias_impl_trait: for trait funcs returning futures implemented withasync{}blocks, and forstatic-executor.
Stable support is a non-goal until these features get stabilized.
Documentation
Embassy documentation is located in the docs/ folder. The documentation is built in embassy-book and published to https://embassy.dev by CI.
Why the name?
EMBedded ASYnc! :)
License
This work is licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.