STM32 “blue pill” easy development with Mbed

Develop for STM32F103 blue pill in Visual Studio Code with PlatformIO using Mbed framework.

The "blue pill" is an STM32F103 based development board. Although it is less popular, the board is cheaper than an Arduino Nano. More than that, STM32F103 is a device with Cortex-M3 ARM CPU that runs at 72 MHz, 20 kB of RAM and 64 or 128 kB of flash memory. The microcontroller (MCU) has USB port, two serial ports, 16 bit PWM pins and 12 bit ADC pins. It runs at 3.3V, but some of its pins are 5V tolerant.

I tried to program this development board using both Arduino IDE and STM32 HAL, but I wasn’t quite satisfied. Arduino framework is simplified and does not take advantage of platform’s features, while HAL was quite difficult for me. Using HAL in Eclipse come with another disadvantage: direct uploading of the binary in flash didn’t work, so I had to use ST-Link tools to upload it, outside of Eclipse. Recently I heard of PlatformIO IDE. This is a development environment supplied as Visual Studio Code or Atom plugin. One of its great advantages is the support for more than 500 development boards! Although VS Code and Atom are cross platform software, they are not at all lightweight, so you’ll need rather good hardware to run them smoothly.

Another great feature of PlatformIO is that for a development board you have multiple framework options. You can program the bluepill using Arduino API, just as you would do in Arduino IDE. Or you can program it using STM32Cube API. But, there is also Mbed OS framework, which I found it to be quite easy to develop.

Setting up the development environment requires installing VS Code, PlatformIO IDE. You also need the STM32 blue pill and ST-Link programmer (with drivers installed on the computer). PlatformIO should also be able to upload binary to blue pill using serial port or on board USB (if Arduino bootloader is installed), but I have only tested ST-Link uploading.

Start by installing Microsoft Visual Studio Code. It can be downloaded as installer for Windows and deb/rpm packages are available for Linux. Launch it, let it update if that’s the case, then go to Extensions and search platformio. Install the extension and reload Code. Quit Code for now.

Install PlatformIO in VS Code

At this point, the hardware should be ready for uploading binary. Connect ST-Link to the blue pill and plug into USB port of PC. If you’re using Windows, drivers are needed. STSW-LINK009 is the archive you can get from ST (you need to make an account to download it). Unarchive the driver package and use dpinst to install the correct driver for your system architecture. Reboot computer.

Linux users need only udev rules. Without them, OpenOCD (which is used by PlatformIO for uploading binary) will not gain access to ST-Link. Get this archive taken from Arduino STM32 package and run install.sh as root. Reboot computer.

Launch Code. It’s time for your first project. Click the PlatformIO icon on the left panel. PIO Home will load and on the welcome screen there should be New Project button. Set the following project options [Board = BluePill F103C8 (Generic), Framework = mbed]. Click Finish and wait. At this point Code is downloading compilers, libraries and everything else needed to set up the development environment. This happens only on the first usage of a new board/framework.

Create STM32 project in PlatformIO

When downloading and installing of tools is finished, you can find your project structure on the left pane. In src, open main.cpp by double clicking on it. Here is the code for sending some serial output and blinking the builtin LED.

#include <mbed.h>

#define LED_BUILTIN PC_13
#define SERIAL2_TX PA_2
#define SERIAL2_RX PA_3

Serial serial2(SERIAL2_TX, SERIAL2_RX, 115200);
DigitalOut led(LED_BUILTIN);

int main()
{
    // put your setup code here, to run once:
    serial2.printf("STM32 bluepill mbed test.\n");

    while (1)
    {
        // put your main code here, to run repeatedly:
        led = 0;
        wait_ms(500);
        led = 1;
        wait_ms(4500);

        serial2.printf("Blinking...\n");
    }
}

Build the code and upload it to board. Everything should work without any issues.

PlatformIO build and upload binary

Wasn’t that easy? If you hook up an USB Serial 3.3V adapter to PA2 and PA3 (serial port 2 pins) you can see output in a serial terminal set to 115200 baud. Using the USB port as virtual serial port requires use of USBSerial class, but that does not compile (not yet supported, unfortunately).

Full Mbed documentation can be found here. I found it to be an easy framework and with a lot of features. Developing for the blue pill is easier with Mbed than with HAL or LL.

Remember that you may use either Arduino or HAL API for the blue pill inside PlatformIO. If you have been working before with cheap blue pill boards, you know that they use a MCU supposed to have 64 kB flash (F103C8), but in reality it has 128 kB flash (F103CB). PlatformIO build options are for 64 kB flash. If you need additional space for your binary, modify ~/.platformio/platforms/ststm32/boards/bluepill_f103c8.json with a text editor (location is the same in Windows – just look in your user folder). Find "maximum_size": 65536 and replace 65536 with 131072. Do this only if OpenOCD (or ST-Link programming tool) reports 128 kB flash when burning the binary (see terminal log in VS Code and look for Info : flash size = 128kbytes).

Now that you have PlatformIO installed, go ahead and explore it. Start by programming your Arduino boards with… Arduino framework. I consider it a good alternative to default IDE.