Crate stm32_hal2

Expand description

This library provides high-level access to STM32 peripherals.

Current family support: F3, F4, L4, L5, G0, G4, H7, and WB. U5 is planned once its SVD files and PAC become available.

Please see the Readme for a detailed overview, and the examples folder on Github for example code and project structure.

§Getting started

Review the syntax overview example for example uses of many of this library’s features. Copy and paste its whole folder (It’s set up using Knurling’s app template), or copy parts of Cargo.toml and main.rs as required.

The blinky example provides a detailed example and instructions for how to set up a blinking light (ie hello world) using an STM32F411 “blackpill” board. Its readme provides instructions for how to get started from scratch, and its code contains detailed comments explaining each part. The blinky with timer interrupt example demonstrates how to accomplish the same in a non-blocking way, using a hardware timer. It uses RTIC.

The conductivity module example is a complete example of simple production firmware. It uses the DAC, I2C, Timer, and UART peripherals, with a simple interupt-based control flow.

The PDM mic, DAC output passthrough example demonstrates how to read audio from a digital microphone, output it to headphones or speakers using the DAC, and use DMA to do this efficiently. It conducts minimal processing, but can be modified to process using DSP between input and output. This example uses RTIC.

Additional examples in the examples folder demonstrate how to use various STM32 peripherals; most of these examples focus on a single peripheral.

When specifying this crate as a dependency in Cargo.toml, you need to specify a feature representing your MCU. If this is for code that runs on an MCU directly (ie not a library), also include a run-time feature, following the template l4rt. For example:

cortex-m = { version = "^0.7.7", features = ["critical-section-single-core"] }
cortex-m-rt = "0.7.2"
hal = { package = "stm32-hal2", version = "^1.5.5", features = ["l4x3", "l4rt"]}

If you need embedded-hal traits, include the embedded-hal feature.

You can review this section of Cargo.toml to see which MCU and runtime features are available.

§Example highlights:

use cortex_m;
use cortex_m_rt::entry;
use hal::{
    clocks::Clocks,
    gpio::{Pin, Port, PinMode, OutputType},
    i2c::I2c,
    low_power,
    pac,
    timer::{Timer, TimerInterrupt},
};

#[entry]
fn main() -> ! {
   let mut dp = pac::Peripherals::take().unwrap();

   let clock_cfg = Clocks::default();
   clock_cfg.setup().unwrap();

   let mut pb15 = Pin::new(Port::A, 15, PinMode::Output);
   pb15.set_high();

   let mut timer = Timer::new_tim3(dp.TIM3, 0.2, Default::default(), &clock_cfg);
   timer.enable_interrupt(TimerInterrupt::Update);

   let mut scl = Pin::new(Port::B, 6, PinMode::Alt(4));
   scl.output_type(OutputType::OpenDrain);

   let mut sda = Pin::new(Port::B, 7, PinMode::Alt(4));
   sda.output_type(OutputType::OpenDrain);

   let mut dma = Dma::new(dp.DMA1);
   dma::mux(DmaPeriph::Dma1, DmaChannel::C1, DmaInput::I2c1Tx);

   let i2c = I2c::new(dp.I2C1, Default::default(), &clock_cfg);

   loop {
       i2c.write(0x50, &[1, 2, 3]);
       // Or:
       i2c.write_dma(0x50, &BUF, DmaChannel::C1, Default::default(), DmaPeriph::Dma1);

       low_power::sleep_now();
   }
}

Supports the RTIC Monotonic trait. To enable, use the monotonic feature.

This article provides some information on using this library, as well as background information on Rust embedded in general.

§Docs caveat

This Rust docs page is built for STM32H735, and some aspects are not accurate for other variants. Clock (RCC) config in particular varies significantly between variants. We currently don’t have a good solution to this problem, and may self-host docs in the future.

Re-exports§

pub use usb_otg as usb;

Modules§

adc: Support for the ADC (Analog to Digital Converter) peripheral.
can: Support for Controller Area Network (CAN) bus. Thinly wraps the bxCAN or can-fd libraries.
clocks: This module contains clock configurations for various MCUs. They tend to be significantly different from one another, so we’ve feature-gated these files, rather than code within the files, to differentiate families. This documentation is built for H723, and will not be correct for other variants. For F series defaults, check out the Default impl here. Check here for other H7 variants For other STM32 families, look here.
comp: Comparator
crc: Cyclic Redundancy Check (CRC) support
dac: Support for the digital to Analog converter (DAC) peripheral.
dfsdm: Digital filter for sigma delta modulators (DFSDM) support. Seem H742 RM, chapter 30.
dma: Support for the Direct Memory Access (DMA) peripheral. This module handles initialization, and transfer configuration for DMA. The Dma::cfg_channel method is called by modules that use DMA.
flash: Read and write onboard flash memory. Erase pages (sectors on H7), write data, and read data.
gpio: This module provides functionality for General Purpose Input and Output (GPIO) pins, including all GPIOx register functions. It also configures GPIO interrupts using SYSCFG and EXTI registers as appropriate. It allows pin mode configuration, interrupts, and DMA.
i2c: Support for the Inter-Integrated Circuit (I2C) bus peripheral. Also supports SMBUS. Provides APIs to configure, read, and write from I2C, with blocking, nonblocking, and DMA functionality.
instant: This module fits the requirement of rtic-monotonic, but has uses beyond that.
iwdg: Indepdent watchdog
low_power: This module contains code used to place the MCU in low power modes. Reference section 5.3.3: Low power modes of the L4 Reference Manual.
pac: Peripheral access API for STM32H73X microcontrollers (generated using svd2rust v0.24.1 ( ))
prelude: In the prelude, we export helper macros.
qspi: Quad Serial Peripheral Interface (SPI) bus: A specialized interface used for high-speed communications with external flash memory. Also supports OctoSPI on variants that support it.
rng: Support for the Random Number Generator (RNG) peripheral. This provides a simple API for accessing hardware-generated 32-bit random numbers, where constructing a Rng peripheral enables its peripheral clock, and provides some methods. Once this struct is constructed, the freestanding functions read(), and reading_ready() may be used to get a random number number, and check if a new one is available.
rtc: Support for the Real Time Clock (RTC) peripheral. For more details, see ST AN4759 Uses Chrono for dates and times.
sai: Serial audio interface (SAI) support, for digital audio input and output. Used for I2S, PCM/DSP, TDM, AC’97 etc. See L443 Reference Manual, section 41, or H743 RM, section 51.
spi: Support for the Serial Peripheral Interface (SPI) bus peripheral. Provides APIs to configure, read, and write from SPI, with blocking, nonblocking, and DMA functionality.
timer: Provides support for basic timer functionality. Includes initialization, interrupts, and PWM features. Also supports capture compare, output compare, burst DMA, and getting the current uptime using an overflowing wrapper. (In seconds, milliseconds, or microseconds)
usart: This module allows for serial communication using the STM32 U[S]ART peripheral It provides APIs to configure, read, and write from U[S]ART, with blocking, nonblocking, and DMA functionality.
usb_otg: USB support, including for simulated COM ports. This module is a thin wrapper required to work with the usbd crate.

Macros§

access_global: Syntax helper for getting global variables of the form Mutex<RefCell<Option>>> from an interrupt-free context - eg in interrupt handlers.
access_globals: Similar to access_global, but combining multiple calls.
check_errors
copy_be: Syntax helper for converting primitives to multi-byte fields.
copy_le: Syntax helper for converting primitives to multi-byte fields.
make_globals: Syntax helper for setting global variables of the form Mutex<RefCell<Option>>>. eg in interrupt handlers. Ideal for non-copy-type variables that can’t be initialized immediatiately.
make_simple_globals: Syntax helper for setting global variables of the form Mutex<Cell<>>>. eg in interrupt handlers. Ideal for copy-type variables.
parse_be: Syntax helper for parsing multi-byte fields into primitives.
parse_le: Syntax helper for parsing multi-byte fields into primitives.

Traits§

BaudPeriph: Uart only. Important: This assumes we use the default UART clock.
RccPeriph: Used to provide peripheral-specific implementation for RCC enable/reset, and for F3 and L4, DMA channel assignment.

Functions§

debug_workaround: Workaround due to debugger disconnecting in WFI (and low-power) modes. This affects most (all?) STM32 devices. In production on battery-powered devices that don’t use DMA, consider removing this, to prevent power use by the DMA clock. For why we enable the DMA clock, see STM32F446 errata, section 2.1.1.
delay_ms: A blocking delay, for a specified time in ms.
delay_us: A blocking delay, for a specified time in μs.

Crate stm32_hal2Copy item path