How to work with the STM32 Blue Pill in PlatformIO and not die trying

I’ve spent quite some years working with embedded systems now, and in recent years I tend to gravitate towards the Arduino platform a lot for prototyping due to its ease of use. As incredibly flexible and versatile as Arduino is (currently there are several manufacturers that use the Arduino software platform for their products as a complement to their own tools), the software tools it has are lacking in several areas, enter PlatformIO (PIO).

The folks at PlatformIO ( have developed a tool that integrates with several IDEs, with Visual Studio Code being the main one right now. This in contrast with the Arduino IDE, and several other microcontroller IDEs, is a significant improvement; bringing all the tried and true features of IDEs used for software development to the microcontroller world, something I’m deeply grateful for.

Pinout of the Blue Pill board. (Credits:

Recently I’ve been working a lot with the STM32 Blue Pill board, which has a STM32F103C8T6 microcontroller, which is a beast for such a small package. At 72Mhz clock frequency is an incredibly powerful and versatile microcontroller that, thanks to its strong community, can be programmed with the Arduino IDE via USB like any Arduino board out there. There are tons of blogs and tutorials showing how this last part can be done, such as here

The problem comes when trying to use PIO on the Blue Pill with this functionality, as is not straightforward and some options are needed in the .ini file of the PIO project. Although the information is available online in forums and such; there’s no one place to find it. So this is my attempt to record what I found to be the way to configure a PIO project to be able to work with the Blue Pill and program it via USB.

In order to show how to configure the project, I will show some of the prior steps (I kinda love it when tutorials do this), the first thing is to create a new project with the following configurations: the board will be the STM32F103C8 (20K RAM, 64K Flash) (Generic). The framework will be Arduino. Your screen should look like this right before clicking Finish.

Project Creation Window

Once this process is finished a new project will be created, on the root of the project there is a platformio.ini file that will have the basic configuration PIO has already set up for the project. When you create a project this file looks like this.

Original platformio.ini file

This platformio.ini file, tells PlatformIO which framework to use (basically which compiler and additional libraries that might be necessary) as well as what board it will be using and such, more information can be found on the documentation ( So what does this file look like for a project using the Blue Pill and program it via USB? Well, the config file that I found out makes the whole thing looks like this

What the platformio.ini file should look like to work with the Blu Pill board

I apologize right now for using an image instead of text, I’ll try to fix this in later versions, but I do it to show how it looks in Visual Studio Code as is. The first thing to note is that the board selected is a generic one, but that is based on the microcontroller used in the Blue Pill. Fortunately, PIO allows us to specify variants for the board, which is necessary to tell PIO to use a specific bootloader and how to program the board.

The other important thing to note is that the platform to be selected is ststm32 and not any of the Maple versions. On my first attempts I used both Maple 1.0 and 2.0, and even though I was able to program the board, it also broke the USB connection, which meant that I couldn’t program it a second time, or even see the Serial output out of USB. However, just specifying ststm32 as platform will tell PIO to use the standard bootloader for Arduino, which doesn’t work with USB directly; to fix that, we need to add another parameter which is board_build.variant and tell it that we’ll be using a Blue Pill based on the F103 Series microcontrollers.

At this point we can program the device via USB multiple times, and won’t break a thing. However, we won’t be getting any output out of USB (like a serial port on Arduino) with this configuration. In order to achieve that, we need to include the PIO_FRAMEWORK_ARDUINO_ENABLE_CDC option on the build flags to tell it to use the USB port as s serial device during operation.

With all these options we’re now set to work in the project and program it like any other PIO project with Arduino. Hope this is helpful to everyone.

Electrical Engineer with passion for technology, especially for programming languages.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store