Crate embassy_stm32

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:

1. You tell the compiler which chip you’re using with a feature flag
2. The stm32-metapac module generates register types for that chip at compile time, based on data from the stm32-data module
3. 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) — Enable stm32-metapac’s rt feature
• defmt — Use defmt for logging
• memory-x — Automatically generate memory.x file using stm32-metapac
• trustzone-secure — Use secure registers when TrustZone is enabled
• unstable-pac — Re-export stm32-metapac at embassy_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-time
• time-driver-any — Use any time driver
• time-driver-tim1 — Use TIM1 as time driver
• time-driver-tim2 — Use TIM2 as time driver
• time-driver-tim3 — Use TIM3 as time driver
• time-driver-tim4 — Use TIM4 as time driver
• time-driver-tim5 — Use TIM5 as time driver
• time-driver-tim8 — Use TIM8 as time driver
• time-driver-tim9 — Use TIM9 as time driver
• time-driver-tim12 — Use TIM12 as time driver
• time-driver-tim15 — Use TIM15 as time driver
• time-driver-tim20 — Use TIM20 as time driver
• time-driver-tim21 — Use TIM21 as time driver
• time-driver-tim22 — Use TIM22 as time driver
• time-driver-tim23 — Use TIM23 as time driver
• time-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 PA0
• split-pa1 — Split PA1
• split-pc2 — Split PC2
• split-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

• adc
  Analog to Digital Converter (ADC)
• can
  Controller Area Network (CAN)
• crc
  Cyclic Redundancy Check (CRC)
• cryp
  Crypto Accelerator (CRYP)
• dac
  Digital to Analog Converter (DAC)
• dcmi
  Digital Camera Interface (DCMI)
• dma
  Direct Memory Access (DMA)
• dsihost
  DSI HOST
• eth
  Ethernet (ETH)
• exti
  External Interrupts (EXTI)
• flash
  Flash memory (FLASH)
• fmc
  Flexible Memory Controller (FMC) / Flexible Static Memory Controller (FSMC)
• gpio
  General-purpose Input/Output (GPIO)
• hash
  Hash generator (HASH)
• hrtim
  High Resolution Timer (HRTIM)
• hsem
  Hardware Semaphore (HSEM)
• i2c
  Inter-Integrated-Circuit (I2C)
• i2s
  Inter-IC Sound (I2S)
• interrupt
  Interrupt definitions.
• lptim
  Low-power timer (LPTIM)
• ltdc
  LTDC - LCD-TFT Display Controller See ST application note AN4861: Introduction to LCD-TFT display controller (LTDC) on STM32 MCUs for high level details This module was tested against the stm32h735g-dk using the RM0468 ST reference manual for detailed register information
• mode
  Operating modes for peripherals.
• opamp
  Operational Amplifier (OPAMP)
• peripherals
  Types for the peripheral singletons.
• qspi
  Quad Serial Peripheral Interface (QSPI)
• rcc
  Reset and Clock Control (RCC)
• rng
  Random Number Generator (RNG)
• rtc
  Real Time Clock (RTC)
• sai
  Serial Audio Interface (SAI)
• sdmmc
  Secure Digital / MultiMedia Card (SDMMC)
• spdifrx
  S/PDIF receiver
• spi
  Serial Peripheral Interface (SPI)
• time
  Time units
• timer
  Timers, PWM, quadrature decoder.
• uid
  Unique ID (UID)
• usart
  Universal Synchronous/Asynchronous Receiver Transmitter (USART, UART, LPUART)
• usb
  Universal Serial Bus (USB)
• wdg
  Watchdog Timer (IWDG, WWDG)

Macros

• bind_interrupts
  Macro to bind interrupts to handlers.
• into_ref
  Convenience converting into reference.

Structs

• Config
  embassy-stm32 global configuration.
• PeripheralRef
  An exclusive reference to a peripheral.
• Peripherals
  Struct containing all the peripheral singletons.
• SharedData
  Object containing data that embassy needs to share between cores.

Constants

• NVIC_PRIO_BITS
  Number available in the NVIC for configuring priority

Traits

• Peripheral
  Trait for any type that can be used as a peripheral of type P.

Functions

• init_primary
  Initialize the embassy-stm32 HAL with the provided configuration. This function does the actual initialization of the hardware, in contrast to init_secondary or try_init_secondary. Any core can do the init, but it’s important only one core does it.
• init_secondary
  Initialize the embassy-stm32 HAL based on the init done by the other core using init_primary.
• try_init_secondary
  Try to initialize the embassy-stm32 HAL based on the init done by the other core using init_primary.

Attribute Macros

• interrupt