Expand description
§Embassy STM32 HAL
The embassy-stm32 HAL aims to provide a safe, idiomatic hardware abstraction layer for all STM32 families. The HAL implements both blocking and async APIs for many peripherals. Where appropriate, traits from both blocking and asynchronous versions of embedded-hal v0.2 and v1.0 are implemented, as well as serial traits from embedded-io[-async].
- embassy-stm32 on crates.io
- Documentation (Important: use docs.embassy.dev rather than docs.rs to see the specific docs for the chip you’re using!)
- Source
- Examples
§embassy-stm32 supports all STM32 chip families
STM32 microcontrollers come in many families and flavors, and supporting all of them is a big undertaking. Embassy takes advantage of the fact that the STM32 peripheral versions are shared across chip families. For example, instead of re-implementing the SPI peripheral for every STM32 chip family, embassy has a single SPI implementation that depends on code-generated register types that are identical for STM32 families with the same version of a given peripheral.
In practice, this works as follows:
- You tell the compiler which chip you’re using with a feature flag
- The stm32-metapac module generates register types for that chip at compile time, based on data from the stm32-data module
- The embassy-stm32 HAL picks the correct implementation each peripheral based on automatically-generated feature flags, and applies any other tweaks which are required for the HAL to work on that chip
Be aware that, while embassy-stm32 strives to consistently support all peripherals across all chips, this approach can lead to slightly different APIs and capabilities being available on different families. Check the documentation for the specific chip you’re using to confirm exactly what’s available.
§Embedded-hal
The embassy-stm32
HAL implements the traits from embedded-hal (v0.2 and 1.0) and embedded-hal-async, as well as embedded-io and embedded-io-async.
§embassy-time
time driver
If a time-driver-*
feature is enabled, embassy-stm32 provides a time driver for use with embassy-time. You can pick which hardware timer is used for this internally via the time-driver-tim*
features, or let embassy pick with time-driver-any
.
embassy-time has a default tick rate of 1MHz, which is fast enough to cause problems with the 16-bit timers currently supported by the embassy-stm32 time driver (specifically, if a critical section delays an IRQ by more than 32ms). To avoid this, it’s recommended to pick a lower tick rate. 32.768kHz is a reasonable default for many purposes.
§Interoperability
This crate can run on any executor.
Optionally, some features requiring embassy-time
can be activated with the time
feature. If you enable it,
you must link an embassy-time
driver in your project.
The low-power
feature integrates specifically with embassy-executor
, it can’t be used on other executors for now.
§Feature flags
rt
(enabled by default) — Enablestm32-metapac
’srt
featuredefmt
— Usedefmt
for loggingmemory-x
— Automatically generatememory.x
file usingstm32-metapac
trustzone-secure
— Use secure registers when TrustZone is enabledunstable-pac
— Re-export stm32-metapac atembassy_stm32::pac
. This is unstable because semver-minor (non-breaking) releases of embassy-stm32 may major-bump (breaking) the stm32-metapac version. If this is an issue for you, you’re encouraged to directly depend on a fixed version of the PAC. There are no plans to make this stable.unchecked-overclocking
— Enable this feature to disable the overclocking check. DO NOT ENABLE THIS FEATURE UNLESS YOU KNOW WHAT YOU’RE DOING.
§Time
time
— Enables additional driver features that depend on embassy-timetime-driver-any
— Use any time drivertime-driver-tim1
— Use TIM1 as time drivertime-driver-tim2
— Use TIM2 as time drivertime-driver-tim3
— Use TIM3 as time drivertime-driver-tim4
— Use TIM4 as time drivertime-driver-tim5
— Use TIM5 as time drivertime-driver-tim8
— Use TIM8 as time drivertime-driver-tim9
— Use TIM9 as time drivertime-driver-tim12
— Use TIM12 as time drivertime-driver-tim15
— Use TIM15 as time drivertime-driver-tim20
— Use TIM20 as time drivertime-driver-tim21
— Use TIM21 as time drivertime-driver-tim22
— Use TIM22 as time drivertime-driver-tim23
— Use TIM23 as time drivertime-driver-tim24
— Use TIM24 as time driver
§Analog Switch Pins (Pxy_C) on STM32H7 series
Get PXY
and PXY_C
singletons. Digital impls are on PXY
, Analog impls are on PXY_C
If disabled, you get only the PXY
singleton. It has both digital and analog impls.
split-pa0
— Split PA0split-pa1
— Split PA1split-pc2
— Split PC2split-pc3
— Split PC3_split-pins-enabled
— internal use only_dual-core
— internal use only
§Chip-selection features
Select your chip by specifying the model as a feature, e.g. stm32c011d6
.
Check the Cargo.toml
for the latest list of supported chips.
Important: Do not forget to adapt the target chip in your toolchain,
e.g. in .cargo/config.toml
.
Re-exports§
pub use stm32_metapac as pac;
Modules§
- Analog to Digital Converter (ADC)
- Controller Area Network (CAN)
- Cyclic Redundancy Check (CRC)
- Digital to Analog Converter (DAC)
- Direct Memory Access (DMA)
- External Interrupts (EXTI)
- Flash memory (FLASH)
- General-purpose Input/Output (GPIO)
- Inter-Integrated-Circuit (I2C)
- Interrupt definitions.
- Low-power timer (LPTIM)
- Operating modes for peripherals.
- Types for the peripheral singletons.
- Reset and Clock Control (RCC)
- Real Time Clock (RTC)
- Serial Peripheral Interface (SPI)
- Time units
- Timers, PWM, quadrature decoder.
- USB Type-C/USB Power Delivery Interface (UCPD)
- Unique ID (UID)
- Universal Synchronous/Asynchronous Receiver Transmitter (USART, UART, LPUART)
- Universal Serial Bus (USB)
- Watchdog Timer (IWDG, WWDG)
Macros§
- Macro to bind interrupts to handlers.
- Convenience converting into reference.
Structs§
embassy-stm32
global configuration.- An exclusive reference to a peripheral.
- Struct containing all the peripheral singletons.
Constants§
- Number available in the NVIC for configuring priority
Traits§
- Trait for any type that can be used as a peripheral of type
P
.
Functions§
- Initialize the
embassy-stm32
HAL with the provided configuration.