Embedded Rust device crates for STM32 microcontrollers
APACHE-2.0 License
This repository provides Rust device support crates for all STM32 microcontrollers, providing a safe API to that device's peripherals using svd2rust and a community-built collection of patches to the basic SVD files. There is one crate per device family, and each supported device is a feature-gated module in that crate. These crates are commonly known as peripheral access crates or "PACs".
To view the generated code that makes up each crate, visit the stm32-rs-nightlies repository, which is automatically rebuilt on every commit to stm32-rs master. The stm32-rs repository contains the patches to the underlying SVD files and the tooling to generate the crates.
While these crates are widely used, not every register of every device will have been tested on hardware, and so errors or omissions may remain. We can't make any guarantee of correctness. Please report any bugs you find!
You can see current coverage status for each chip here. Coverage means that individual fields are documented with possible values, but even devices with low coverage should have every register and field available in the API. That page also allows you to drill down into each field on each register on each peripheral.
In your own project's Cargo.toml
:
[dependencies.stm32f4]
version = "0.15.1"
features = ["stm32f405", "rt"]
The rt
feature is optional but helpful. See
svd2rust for
details.
Then, in your code:
use stm32f4::stm32f405;
let mut peripherals = stm32f405::Peripherals::take().unwrap();
Refer to svd2rust
documentation for further usage.
Replace stm32f4
and stm32f405
with your own device; see the individual
crate READMEs for the complete list of supported devices. All current STM32
devices should be supported to some level.
Whenever the master branch of this repository is updated, all device crates are
built and deployed to the
stm32-rs-nightlies
repository. You can use this in your Cargo.toml
:
[dependencies.stm32f4]
git = "https://github.com/stm32-rs/stm32-rs-nightlies"
features = ["stm32f405", "rt"]
The nightlies should always build and be as stable as the latest release, but contain the latest patches and updates.
svd2rust
, svdtools
, and form
:
make install
to download pre-built binaries at thecargo
(double check versions against scripts/tool_install.sh
):
cargo install form --version 0.12.1
cargo install svdtools --version 0.3.18
cargo install svd2rust --version 0.33.4
rustup component add rustfmt
make patch
(you probably want -j
for all make
invocations)
cargo-make
runner and then use it instead of make
. Works on MS Windows natively:
cargo install cargo-make
cargo make patch
make svd2rust
make form
This project serves two purposes:
When this project began, many individual crates existed for specific STM32 devices, typically maintained separately with hand-edited updates to the SVD files. This project hopes to reduce that duplication of effort and centralise the community's STM32 device support in one place.
This project is still young and there's a lot to do!
peripherals/
and grab a reference manual!Please see the individual crate READMEs for the full list of devices each crate supports. All SVDs released by ST for STM32 devices are covered, so probably your device is supported to some extent!
Devices that are nearly identical, like the STM32F405/F415, are supported by ST under a single SVD file STM32F405, so if you can't find your exact device check if its sibling is supported instead. The crate READMEs make this clear.
Many peripherals are not yet patched to provide the type-safe friendly-name interface (enumerated values); please consider helping out with this!
Check out the full list of supported devices here.
svd/vendor
to include new SVDs.make extract
to extract the new zip files.devices/
with the new SVD path and include anystm32_part_table.yaml
.scripts/makecrates.py
.scripts/matchperipherals.py
script to find out what existingpyyaml
svdtools
dependencies.python scripts/matchperipherals.py peripherals/rcc devices/stm32h562.yaml
scripts/makecrates.py devices/
to update the crates with the new devices.make
to rebuild, which will make a patched SVD and then run svd2rust
If adding a new STM32 family (not just a new device to an existing family), complete these steps as well:
CRATES
field in Makefile
.workflows/ci.yaml
and workflows/nightlies.yaml
.make extract
at least once to pull the SVDs out.make
to rebuild all the crates using svd patch
and svd2rust
.cd stm32f4; cargo build --features stm32f405
If you've added a new peripheral, consider using the matchperipherals.py
script to see which devices it would cleanly apply to.
To generate a new peripheral file from scratch, consider using
periphtemplate.py
, which creates an empty peripheral file based on a single
SVD file, with registers and fields ready to be populated. For single bit wide
fields with names ending in 'E' or 'D' it additionally generates sample
"Enabled"/"Disabled" entries to save time.
Please see the svdtools documentation for full details of the patch file format.
Notes for maintainers:
CHANGELOG.md
with changes since last release and new contributorsREADME.md
to bump version number in example snippetscripts/makecrates.py
to update version number for generated PACsmake clean
make -j16 form
for f in stm32f0 stm32f1 stm32f2 stm32f3 stm32f4 stm32f7 stm32h7 stm32l0 stm32l1 stm32l4 stm32l5 stm32g0 stm32g4 stm32mp1 stm32wl stm32wb; cd $f; pwd; cargo publish --allow-dirty --no-default-features; cd ..; end
git tag -a vX.X.X -m vX.X.X
git push vX.X.X
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.