Crate stm32_hal2
source ·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 = "0.7.3"
cortex-m-rt = "0.7.0"
stm32-hal2 = { version = "^1.5.0", 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, 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.
Modules
Dma::cfg_channel
method is called by modules that use DMA.rtic-monotonic
, but has uses beyond that.Low power modes
of the L4 Reference Manual.usbd
crate.Macros
Mutex<RefCell<Option>>>
from an interrupt-free
context - eg in interrupt handlers.Mutex<RefCell<Option>>>
.
eg in interrupt handlers. Ideal for non-copy-type variables that can’t be initialized
immediatiately.Mutex<Cell<>>>
.
eg in interrupt handlers. Ideal for copy-type variables.