Crate stm32_hal2[−][src]
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. WL support is a WIP, with many features not implemented.
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, written by toudi, 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 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.
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 = "0.7.3"
cortex-m-rt = "0.6.13"
stm32-hal2 = { version = "^1.0.1", 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 stm32_hal2::{
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, &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 i2c = I2c::new(dp.I2C1, Default::default(), &clock_cfg);
loop {
i2c.write(0x50, &[1, 2, 3]);
low_power::sleep_now();
}
}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 STM32L4x3, and some aspects are not accurate for other
variants. We currently don’t have a good solution to this problem, and may
self-host docs in the future.
Modules
Support for the ADC (Analog to Digital Converter) peripheral.
Support for Controller Area Network (CAN) bus. Thinly wraps the bxCAN library.
Note that this is currently for bxCAN only; different from the fdCAN used on newer families.
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.
Cyclic Redundancy Check (CRC) support
Support for the digital to Analog converter (DAC) peripheral.
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.
Read and write onboard flash memory. The Flash memory is organized as 72-bit wide memory cells (64 bits plus 8 ECC bits) that can be used for storing both code and data constants.
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.
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.
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.
Peripheral access API for STM32L4X3 microcontrollers (generated using svd2rust v0.19.0 ( ))
In the prelude, we export helper macros.
Support for the Random Number Generator (RNG) peripheral.
Serial audio interface (SAI) support. Used for I2S, PCM/DSP, TDM, AC’97 etc. See L443 Reference Manual, section 41. H743 FM, section 51.
Support for the Serial Peripheral Interface (SPI) bus peripheral. Provides APIs to configure, read, and write from SPI, with blocking, nonblocking, and DMA functionality.
Provides support for timers. Includes initialization, countdown functionality, interrupts, and PWM features.
This module allows for serial communication using the STM32 USART module. Provides APIs to configure, read, and write from USART, with blocking, nonblocking, and DMA functionality.
USB support, including for simulated COM ports. This module is a thin wrapper required to work with
the stm32_usbd crate.
Macros
Syntax helper for getting global variables of the form Mutex<RefCell<Option>>> from an interrupt-free
context - eg in interrupt handlers.
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.
Syntax helper for setting global variables of the form Mutex<Cell<>>>.
eg in interrupt handlers. Ideal for copy-type variables.
Enables and resets peripheral clocks on various RCC registesr.
The first argument is a apb1, ahb2 etc to specify the reg block. The second is something like
tim1, and the third is a pac::RCC.
Functions
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.