Skip to content
Quickstart a Rust project for the blue pill board
Rust GDB Logos
Branch: master
Clone or download
This branch is 2 commits ahead of TeXitoi:master.

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.cargo
.vscode
src
.gitignore
.travis.yml
Cargo.lock
Cargo.toml
LICENSE
README.md
memory.x
openocd.cfg
openocd.gdb
st-link-v2-blue-pill.jpg

README.md

blue-pill-quickstart Build status

Quickstart a Rust project for the blue pill, or any similar STM32F103xx board.

Quickstart a new project

This section assumes your computer is ready to hack on a blue pill.

Get and cleanup:

git clone https://github.com/TeXitoi/blue-pill-quickstart.git my-new-project
cd my-new-project
rm -fr .git LICENSE README.md st-link-v2-blue-pill.jpg
git init

Edit Cargo.toml for author and project name, and you're ready to go.

MacOS

Install Rust and compiler via homebrew

brew cask install gcc-arm-embedded
brew install open-ocd
brew install rustup-init

rustup-init
rustup default nightly
rustup target add thumbv7m-none-eabi

Get example code and test

git clone https://github.com/SteveCooling/blue-pill-quickstart.git
cd blue-pill-quickstart
openocd && cargo run

Install VSCode plugins

  • Better TOML
  • C/C++
  • Native Debug
  • Rust
  • Rust (rls)

Setting up your machine

First, you need hardware. Buy a blue pill and an ST-Link V2. You also need a computer, the commands below are for a Debian based distribution. It should be easy to adapt the instructions to other operating systems (Linux, MacOSX, Windows).

Install rust and gdb support to compile and debug code for the Cortex-M3 which is the basis of the STM32F103xx MCU:

curl https://sh.rustup.rs -sSf | sh
rustup target add thumbv7m-none-eabi
sudo apt-get install gdb-arm-none-eabi openocd

If your distribution doesn't offer gdb-arm-none-eabi, you can try gdb-multiarch (on Ubuntu 18.04 for example) or gdb. In these cases, you'll have to update .cargo/config accordingly.

Clone the repository:

git clone https://github.com/TeXitoi/blue-pill-quickstart.git
cd blue-pill-quickstart

First connect your ST-Link to your blue pill, then connect the ST-Link to your computer.

ST-Link V2 to blue pill

Launch openocd:

openocd

You should see terminal output like this:

Open On-Chip Debugger 0.10.0
[...]
Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints

Open a new terminal, compile and flash

cd blue-pill-quickstart
cargo run

Now, the program is flashed, and you are on a gdb prompt. Type c (for continue) you can see the on board LED blinking.

Trouble Shooting

Wrong connection of the ST-Link

The pin mapping which is shown on the outer shell of your ST-Link might not be correct. If openocd returns unknown code 0x9, check the pin mapping by removing the ST-Link's shell, and check if the pin mapping printed on its PCB matches the mapping printed on the outer case. If they differ, then use the mapping printed on the PCB.

If you're unable to remove the shell or the PCB is not readable, you can try one of these pin mappings which are known to exist:

pin pin
1 RST 2 SWDIO
3 GND 4 GND
5 SWIM 6 SWCLK
7 3.3V 8 3.3V
9 5.0V 10 5.0V
pin pin
1 RST 2 SWCLK
3 SWIM 4 SWDIO
5 GND 6 GND
7 3.3V 8 3.3V
9 5.0V 10 5.0V

Flash protected

When flashing your blue pill for the first time, flashing may fail with the following messages in the openocd console:

Error: stm32x device protected
Error: failed erasing sectors 0 to 23
Error: flash_erase returned -4

This means your blue pill's flash is read-only protected. To unlock it, you can connect to your openocd session with:

telnet localhost 4444

... and type the following commands:

reset halt
stm32f1x unlock 0
reset halt

MCU in low power state

If the software which was already flashed to the Blue pill has put the processor core into a low power state, then this prevents the hardware debug interface from operating. In this case, then OpenOCD will create output like this:

Error: jtag status contains invalid mode value - communication failure
Polling target stm32f1x.cpu failed, trying to reexamine
Examination failed, GDB will be halted. Polling again in 100ms
Info : Previous state query failed, trying to reconnect

To workaround this, press the reset button on the blue pill board whilst starting openocd. If the software that you've flashed to the STM32F103xx is putting it into the low power mode (e.g. by using the wfi instruction), then you might want to disable this (e.g. by busy-looping instead) when building the code in development mode instead of release mode.

Sources

This quickstart is inspired by the cortex-m-quickstart and Discovery. I recommend reading them.

You can’t perform that action at this time.