diary at Telent Netowrks

A Kind of Magic#

Sun, 19 Dec 2021 11:52:12 +0000

Lately my greatest programming success is a Lua program that flashes the backlight on my PineTime smartwatch - or, more accurately, creating the conditions that make it possible to flash the backlight on my smartwatch using Lua. By which I mean, installing Lua on it and writing some bindings for GPIO control.

But this post isn't about PineTime per se, this is about setting up a development environment for it: specifically, about installing Black Magic Probe on the WeAct STM32F411 board commonly known as "Black Pill"

Black Magic Probe is an "in-application debugging tool for embedded microprocessors". You connect one end of it to a USB port on a PC, and the other end to some debug pins (SWDIO, SWCLCK, V+ and GND) on the target device. It appears on the PC as two serial ports, and one of them speaks the GDB remote protocol so you can run programs, set breakpoints, single-step and all that cool stuff on your target device. You can buy the BMP as a hardware device (which I would definitely recommend doing to support the developers, except that it's currently sold out) or you can buy a cheap microcontroller and build and install it yourself.

BMP supports a bunch of different microcontrollers. I read on the Internet(sic) that I should use a "Blue Pill", and I would like to summarise the learning experience that ensued:

  1. Blue Pill is the nickname of a small blue PCB based on the STM32F103 Arm Cortex M3 MCU designed by WeAct Studios, and a zillion clones and variants based on it. You can program it using the Arduino IDE, if that's your idea of a good time, or you can use a "grown up" Arm toolchain. As far as I can tell from reading, to flash it for the first time you need to attach a programmer like the ST-Link (I'm guessing you may also be able to use a Pi with OpenOCD) to its debug pins, but if you flash a program with USB support you can do subsequent uploads over USB.
  2. Some of the Blue Pill clone devices are printed on black PCBs, and therefore known as Black Pill. Same MCU, slightly different board layout.
  3. There is also another device (or range of devices) informally known as the Black Pill, but these use the STM32F401 or STM32F411 - that 4 is significantly not a 1 there. The difference is it's an ARM Cortex M4 rather than M3. There are other changes as well: the USB connector is C rather than micro, they can be USB flashed out of the box, and there are actual buttons instead of jumpers to reset and to enter the bootloader.

The lesson here is: if you want a blue pill, don't assume as I did that something described as "Black Pill [...] better than Blue" is going to do the same job in the same way. Check the MCU model number.

BMP can be built for the F4 MCU, but the documentation isn't very clear on how. Instead of swlink you use the f4discovery target, and you have to pass BLACKPILL=1 to make. And that is alleged to work, but on my Black Pill clone board it didn't until I made a bunch of random changes that shouldn't have made a difference, and then suddenly it did - gory details are in the link. But at least programming the board is simpler: you can do it over USB with dfu-util instead of messing around with serial pins.

For extra credit, and this is a great reason to run BMP instead of using an ST-Link device with OpenOCD, you can enable RTT which gives the target a way to print messages on the host so you can do "printf debugging". At the time of writing this doesn't exist in BMP mainline but there's a PR (see #954) which "just works" and I strongly endorse.

In the next installment, maybe some actual PineTime programming.