Repository files navigation

HAL for the STM32F1 family of microcontrollers

Embedded Rust development requires a bit more setup than ordinary development.For this guide, we'll assume you're using a stm32 blue pill board (shownbelow), but if you have another f1 microcontroller, you should be able to adaptit.

You will also need a debug probe, for example anstlink v3mini for programming and debugging.(There are many different STLink probes out there, all of themshould work fine with the instructions given here, other JTAG or SWD debug probes will work as well but will need different software or configuration).

To program your microcontroller, you need to install:

• openocd
• gdb-multiarch (on some platforms you may need to usegdb-arm-none-eabi instead, make sure to update.cargo/config to reflect this change)

Finally, you need to install arm target support for the Rust compiler. To doso, run

rustup target install thumbv7m-none-eabi

Create a new Rust project as you usually do withcargo init. The hello worldof embedded development is usually to blink an LED and code to do so isavailable inexamples/blinky.rs. Copy that file to themain.rs of your project.

You also need to add some dependencies to yourCargo.toml:

[dependencies]embedded-hal ="0.2.7"nb ="1"cortex-m ="0.7.6"cortex-m-rt ="0.7.1"# Panic behaviour, see https://crates.io/keywords/panic-impl for alternativespanic-halt ="0.2.0"[dependencies.stm32f1xx-hal]version ="0.10.0"features = ["rt","stm32f103","medium"]

If you build your project now, you should get a single error:error: language item required, but not found: eh_personality. This unhelpful error messageis fixed by compiling for the right target.

We also need to tell Rust how to link our executable, and how to lay out theresult in memory. To accomplish all this, copy.cargo/config.toml andmemory.x from thestm32f1xx-hal repo to your project.

cargo build

If everything went well, your project should have built without errors.

It is now time to actually run the code on the hardware. To do so plug yourdebug probe into the blue pill and startopenocd using

openocd -f interface/stlink-v3.cfg -f target/stm32f1x.cfg

If you are not using an stlink V3, change the interface accordingly.For more information, see theembeddonomicon.

If all went well, it should detect your microcontroller and sayInfo : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints. Keep it running inthe background.

We will use gdb for uploading the compiled binary to the microcontroller andfor debugging. Cargo will automatically startgdb thanks to the.cargo/config you added earlier.gdb also needs to be toldto connect to openocd which is done by copying.gdbinit to the rootof your project.

You may also need to tellgdb that it is safe to load.gdbinit from theworking directory.

• Linux

  echo"set auto-load safe-path$(pwd)">>~/.gdbinit

• Windows

  echo set auto-load safe-path%CD%>>%USERPROFILE%\.gdbinit

  You may need restart your computer

If everything was successful, cargo should compile your project, start gdb,load your program and give you a prompt. If you typecontinue in the gdbprompt, your program should start and the green led on the blue pill shouldstart blinking.

From here on, you can start adding more code to your project to make it dosomething more interesting. For crate documentation, seedocs.rs/stm32f1xx-hal. There are also a lotmoreexamples available. If something is unclear in the docs orexamples, please, open an issue and we will try to improve it.

This crate supports multiple microcontrollers in thestm32f1 family. Which specific microcontroller you want to build for has to bespecified with a feature, for examplestm32f103.

If no microcontroller is specified, the crate will not compile.

You may also need to specify the density of the device withmedium,high orxlto enable certain peripherals. Generally the density can be determined by the 2nd characterafter the number in the device name (i.e. For STM32F103C6U, the 6 indicates a low-densitydevice) but check the datasheet or CubeMX to be sure.

• 4, 6 => low density, no feature required
• 8, B =>medium feature
• C, D, E =>high feature
• F, G =>xl feature

For microcontrollers of theconnectivity line (stm32f105 andstm32f107) nodensity feature must be specified.

• stm32f100
• stm32f101
• stm32f103
• stm32f105
• stm32f107

You may need to givecargo permission to callgdb from the working directory.

• Linux

  echo"set auto-load safe-path$(pwd)">>~/.gdbinit

• Windows

  echo set auto-load safe-path%CD%>>%USERPROFILE%\.gdbinit

  You may need restart your computer

Compile, load, and launch the hardware debugger.

$ rustup target add thumbv7m-none-eabi# on another terminal$ openocd -f interface/$INTERFACE.cfg -f target/stm32f1x.cfg# flash and debug the "Hello, world" example. Change stm32f103 to match your hardware$ cargo run --features stm32f103 --example hello

$INTERFACE should be set based on your debugging hardware. If you are usingan stlink V2, usestlink-v2.cfg. For more information, see theembeddonomicon.

When using this crate as a dependency in your project, the microcontroller canbe specified as part of theCargo.toml definition.

[dependencies.stm32f1xx-hal]version ="0.9.0"features = ["stm32f100","rt"]

The documentation can be found atdocs.rs.

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in the work by you, as defined in the Apache-2.0 license, shall bedual licensed as above, without any additional terms or conditions.