• Stars
    star
    564
  • Rank 79,014 (Top 2 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created almost 6 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Rust embedded-hal HAL impl for the STM32F1 family based on japarics stm32f103xx-hal

stm32f1xx-hal

HAL for the STM32F1 family of microcontrollers

Continuous integration crates.io Released API docs

Quick start guide

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 (shown below), but if you have another f1 microcontroller, you should be able to adapt it.

blue pill pinout

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

Installing software

To program your microcontroller, you need to install:

  • openocd
  • gdb-multiarch (on some platforms you may need to use gdb-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 do so, run

rustup target install thumbv7m-none-eabi

Setting up your project

Create a new Rust project as you usually do with cargo init. The hello world of embedded development is usually to blink an LED and code to do so is available in examples/blinky.rs. Copy that file to the main.rs of your project.

You also need to add some dependencies to your Cargo.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 alternatives
panic-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 message is fixed by compiling for the right target.

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

cargo build

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

Programming the microcontroller

It is now time to actually run the code on the hardware. To do so plug your debug probe into the blue pill and start openocd 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 the embeddonomicon.

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

We will use gdb for uploading the compiled binary to the microcontroller and for debugging. Cargo will automatically start gdb thanks to the .cargo/config you added earlier. gdb also needs to be told to connect to openocd which is done by copying .gdbinit to the root of your project.

You may also need to tell gdb that it is safe to load .gdbinit from the working directory.

  • Linux
    echo "set auto-load safe-path $(pwd)" >> ~/.gdbinit
  • Windows
    echo set auto-load safe-path %CD% >> %USERPROFILE%\.gdbinit

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

Going further

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

Selecting a microcontroller

This crate supports multiple microcontrollers in the stm32f1 family. Which specific microcontroller you want to build for has to be specified with a feature, for example stm32f103.

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

You may also need to specify the density of the device with medium, high or xl to enable certain peripherals. Generally the density can be determined by the 2nd character after the number in the device name (i.e. For STM32F103C6U, the 6 indicates a low-density device) 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 the connectivity line (stm32f105 and stm32f107) no density feature must be specified.

Supported Microcontrollers

  • stm32f100
  • stm32f101
  • stm32f103
  • stm32f105
  • stm32f107

Trying out the examples

You may need to give cargo permission to call gdb from the working directory.

  • Linux
    echo "set auto-load safe-path $(pwd)" >> ~/.gdbinit
  • Windows
    echo set auto-load safe-path %CD% >> %USERPROFILE%\.gdbinit

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 using an stlink V2, use stlink-v2.cfg. For more information, see the embeddonomicon.

Using as a Dependency

When using this crate as a dependency in your project, the microcontroller can be specified as part of the Cargo.toml definition.

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

Documentation

The documentation can be found at docs.rs.

License

Licensed under either of

at your option.

Contribution

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.

More Repositories

1

stm32-rs

Embedded Rust device crates for STM32 microcontrollers
Python
1,281
star
2

stm32f4xx-hal

A Rust embedded-hal HAL for all MCUs in the STM32 F4 family
Rust
550
star
3

stm32h7xx-hal

Peripheral access API for STM32H7 series microcontrollers
Rust
215
star
4

stm32f3xx-hal

A Rust embedded-hal HAL for all MCUs in the STM32 F3 family
Rust
164
star
5

stm32l4xx-hal

A Hardware abstraction layer for the stm32l432xx series chips written in rust.
Rust
156
star
6

stm32-eth

Embedded Ethernet driver in Rust
Rust
147
star
7

stm32f0xx-hal

A Rust `embedded-hal` implementation for all MCUs in the STM32 F0 family
Rust
125
star
8

stm32f7xx-hal

A Rust embedded-hal HAL for all MCUs in the STM32 F7 family
Rust
115
star
9

stm32-usbd

usb-device implementation for STM32 microcontrollers
Rust
99
star
10

stm32l0xx-hal

A hardware abstraction layer (HAL) for the STM32L0 series microcontrollers written in Rust
Rust
96
star
11

stm32g0xx-hal

Peripheral access API for STM32G0 series microcontrollers
Rust
72
star
12

stm32g4xx-hal

Peripheral access API for STM32G4 series microcontrollers
Rust
58
star
13

stm32-usbd-examples

stm32-usbd examples for different microcontrollers
Rust
48
star
14

stm32wlxx-hal

A Hardware abstraction layer for the stm32wl series chips written in rust.
Rust
45
star
15

stm32f407g-disc

Rust BSP crate for the STM32F4DISCOVERY (STM32F407G-DISC) development board
Rust
43
star
16

synopsys-usb-otg

usb-device implementation for Synopsys USB OTG IP cores
Rust
43
star
17

bxcan

bxCAN peripheral driver for STM32 chips
Rust
31
star
18

stm32-fmc

Hardware Abstraction Layer for STM32 Memory Controllers (FMC/FSMC)
Rust
17
star
19

stm32f429i-disc

Rust BSP crate for the STM32F429I-DISC development board
Rust
15
star
20

stm32-rs-nightlies

Up-to-date builds of current stm32-rs master branch, for use as Cargo git dependencies
Rust
14
star
21

fdcan

FDCAN peripheral driver for STM32 chips
Rust
12
star
22

stm32-rs-mmaps

Textual memory maps of stm32-rs devices, used to help review PRs to stm32-rs
9
star
23

stm32l1xx-hal

[WIP] Peripheral access API for STM32L1 series microcontrollers
Rust
9
star
24

stm32h5xx-hal

Rust
8
star
25

nucleo-f042k6

Rust BSP crate for the STM Nucleo-F042K6 development board
Shell
8
star
26

stm32-device-signature

Device electronic signature 'driver' for STM32 microcontrollers
Rust
8
star
27

stm32f072b-disco

A BSP/example crate for the STM32F072 Discovery kit
Rust
7
star
28

cube-parse

Rust
7
star
29

cube-MX-db

MCU database files from CubeMX
5
star
30

meta

Meta discussions and files applicable to the entire stm32-rs project
3
star
31

stm32c0xx-hal

Peripheral access API for STM32C0 series microcontrollers
Rust
2
star