Install and pinout instructions unclear: Bluepill

[vatrat]

OS: OpenSUSE Leap 20230925
Hardware: 2x bluepill (assumed legitimate), STLink V2 clone
Intended setup: bluepill A connected via microUSB to computer, bluepill B connected to bluepill A as target
Reproduction:

1. Install GNU-RM. There are no instructions given whatsoever for this, so I give my own here.
   I extracted the tar archive to /opt/arm-gnu-toolchain-12.3
   Then, I added to the end of my ~/.bashrc:

# set up ARM toolchain

export PATH="/opt/arm-gnu-toolchain-12.3/bin:$PATH"

export PATH="/opt/arm-gnu-toolchain-12.3/arm-none-eabi/bin:$PATH"

2. Clone and build blackmagic firmware
   Note: It was incredibly hard to find which probe host to use. I still can't find any one source for build instructions, only instructions in each platform's README.md. The 'stlink' readme does not mention the bluepill at all, but the 'swlink' readme does. However, the official website says that you should use 'stlink'. Neither binary seems to use the bluepill's status LED, I've confirmed the LED functions.

#insert clone procedure here
cd blackmagic
make PROBE_HOST=stlink BLUEPILL=1

3. Program the board
   I connect the STLink V2 clone (original firmware) to the 3.3v, GND, SWDIO, and SWCLK pins and plug it into my computer.
   Then I set the boot jumpers to boot0=1,boot1=0 and reset the board, just in case.

cd src
st-flash --reset write blackmagic_dfu.bin 0x8000000
# wait for it to complete, "jolly good!"
st-flash --flash=128k write blackmagic.bin 0x8002000
# wait for it to complete, "jolly good!" (all pages succeed)

I set the boot jumpers back to boot0=0,boot1=0 and reset the board.

4. Verify blackmagic firmware is connected
   I disconnect the STLink V2 clone, then connect bluepill A with a microUSB cable.
   Next, I run dmesg | tail or sudo journalctl -ke to make sure the device is registered, in my case as /dev/ttyACM0 and /dev/ttyACM1.

5. Run arm-none-eabi-gdb
   Unfortunately, this requires some setup.
   To make arm-none-eabi-gdb work, I installed the old libncurses5 package from my vendor (my system uses libncurses6) and python3.8 (my system uses python3.11)
   Next, I make a python3.8 virtual environment and a file I called start.sh in the folder ~/code/arm/, with the virtual environment in the subfolder venv:

# arm-none-eabi-gdb needs these set specifically for some reason
export PYTHONPATH=/usr/lib64/python3.8
export PYTHONHOME=/usr/bin/python3.8

To run arm-none-eabi-gdb, I execute:

source ~/code/arm/venv/bin/activate
source ~/code/arm/start.sh
arm-none-eabi-gdb

6. Connect to bluepill A with gdb

(gdb) target extended-remote /dev/ttyACM0
Remote debugging using /dev/ttyACM0
(gdb) monitor
Black Magic Probe (ST-Link/v2) v1.10.0-rc0-31-g30e9fb6d, Hardware Version 0
Copyright (C) 2022 Black Magic Debug Project
#insert GPLv3+ text here

7. Connect the newly-flashed bluepill A to bluepill B
   I have yet to find any instructions on how to actually do this, specifically what pins map to what, or even how to use any blackmagic probe hardware with flying wires instead of a connector.
   I use the pinouts from JeeLabs (site will go down soon) and blackmagic-bluepill (long out of date fork with altered pinout), since I can't find any pinout descriptions in any README.md, gpio.h, or stm32f1.c in the blackmagic code, nor anywhere on the official website, including the pinout glossary, EXCEPT in the swlink README.md, which is linked to via an old link on the JeeLabs website. Both JeeLabs and the swlink readme list the SWD pins as PA12 and PA13, so I use female<->female dupont cables to connect the SWD ports of bluepills A and B together. The power light of bluepill B comes on.
   Using gdb, I run monitor: auto_scan, swdp_scan, swd_scan. All three fail.

Target voltage: (somewhere between 3.00 and 3.33v)
SW-DP scan failed!
Failed

Next, I try to use JTAG, connecting both PB4 (JTRST) together and connecting PA15 and PB3 (JTDI, JTDO) together. I try running mon jtag_scan, it fails, and I swap PA15 and PB3 connections and try again. This also fails.

What am I doing wrong? I could build the firmware with debug enabled, but I don't know what to look for. I have tried replacing bluepill B, no change. I tried disconnecting PA15 and PB3, then connecting PB3 to PA3 on bluepill B as per the swlink readme, no change. I have connected bluepill A's 3.3v line to bluepill B's (not the ones on the SWD header), no change. I'm currently using a bluepill with stock firmware (blink) as bluepill B, what can I do to make this work?

If it wasn't clear, this issue is one of documentation, even if I am able to get this to work. It should not be closed until the documentation has been clarified, for all platforms, on how to:

• Install GNU-RM (arm toolchain)
• make arm-none-eabi-gdb work
• select a host to use for the bluepill
• find the pinout for each platform, ideally without reading a header file

[dragonmux]

This is quite a long ticket, so we'll try and address things in parts (numbered based on which sections we're answering or giving some information on):

1. With

# set up ARM toolchain
export PATH="/opt/arm-gnu-toolchain-12.3/arm-none-eabi/bin:$PATH"
export PATH="/opt/arm-gnu-toolchain-12.3/bin:$PATH"

Do not add the $toolchain/arm-none-eabi/bin to $PATH, this will screw things up if you want to use your system tools and $toolchain/bin is not just sufficient but also the complete path you should add.

In relation to a lack of instruction - we've been working on that on the website repo - at least for windows

2. Bluepill is a minefield which is why we've not yet updated the platforms. We know it's a mess, but the person who contributed the swlink platform failed to document it properly as did the person who contributed the stlink platform's BLUEPILL=1 mode. Trying to figure out accurately which exact boards each apply to has been a nightmare and until we can pin this down, the mess persists - we simply don't know what to update the README texts to.

3. Given you're running what looks to be a Blue Pill based on the STM32 Base definition, you can use the project bootloader to dispense with needing to use st-flash so you don't have to keep its SWD connection made.

5. Unfortunately, nothing we can do here.. this is an artefact of how ARM builds their GDBs - though you can run your own arm-none-eabi-gdb to avoid this problem if you wish. (There's no one-size-fits way to make it work - no instruction we can write that will cover all the distributions etc. This is a problem specifically with how ARM builds/ships GDB - most current distros don't even ship Python 3.8 to fix this against)

7. The pinout is the stlink platform's as this is the platform which you built against. The swlink platform will only lead you astray.

The ST-Link platform uses the same pinout as the official ST-Link - so this makes the pinout:

Pin	Function
PA5	SWCLK/TCK
PA6	TDO
PA7	TDI
PA14	SWDIO/TMS
PA10	SWO
PB0	nRST

[vatrat]

Didn't mean to close, I'm not sure why that button is next to "comment".

1. I removed the first path addition, it works. Not sure how I missed that.

2. Okay, so the code for bluepill just isn't current? That makes sense, I was trying to figure out why the BLUEPILL=1 check only changed the port and not the pin. If there are multiple bluepill boards, I'm not aware of the distinction, as I bought mine in bulk years ago. Do you know what swlink is for? I haven't tried to build it.

3. That stm32-base link is quite useful, I've been using my own local documentation, mostly in pictures.

• What would be a blue pill that is NOT based on those definitions?
• What do you mean by the "project bootloader"? The only instructions I was able to find for flashing were the ones from JeeLabs. Are you saying I shouldn't flash the DFU binary? I've only been using the STLink since it's a known-good programmer.

5. I know it's not your problem, but as long as it's the suggested toolchain, it would be nice to list these steps, as they're pretty simple to follow. Just knowing that there IS a known solution is incredibly helpful, as the python errors gdb gives are nonsense. It took me a while to find instructions that worked and I don't think most people would be willing to put that much work in.

7. It would be nice to include the platform.h definitions in the readme, I can do this later if I can get it to work using the correct pins.

Thank you for the quick reply! I intend to keep using this setup, so I'll try to contribute to sorting this mess out.

P.S. I'm certain this is the wrong place to ask, but how do you disable building for certain platforms? I've seen a few references to limiting which platforms are built to reduce generated binary size, but I haven't found any way to do this in the makefiles.

[dragonmux]

Okay, so the code for bluepill just isn't current? That makes sense, I was trying to figure out why the BLUEPILL=1 check only changed the port and not the pin. If there are multiple bluepill boards, I'm not aware of the distinction, as I bought mine in bulk years ago. Do you know what swlink is for? I haven't tried to build it.

The README files aren't, the code is. Unless you know absolutely otherwise (and figuring out what exactly that means has been the rub), make PROBE_HOST=stlink BLUEPILL=1 is the correct platform and build option to use. Trying to figure out what the contributor of the swlink platform means by "bluepill" in that context has been a huge part of the problem in updating this documentation for that platform.

What do you mean by the "project bootloader"? The only instructions I was able to find for flashing were the ones from JeeLabs. Are you saying I shouldn't flash the DFU binary? I've only been using the STLink since it's a known-good programmer.

When you built the ST-Link platform for Blue Pill, you will have had 4 files created in the src folder that have .bin and .elf extensions - blackmagic.{elf,bin} and blackmagic_dfu.{elf,bin} - this second set of files are the project's DFU bootloader to be loaded at 0x08000000. This is the DFU binary we recommend.

but as long as it's the suggested toolchain, it would be nice to list these steps, as they're pretty simple to follow.

The problem is they only work for distros that still make Python 3.8 available, and we get a lot of complaints when the instructions that are published do not work on, eg, current Ubuntu, Debian, or Arch. Trying to build universal instructions under these conditions is just not something we can do, and not for a lack of trying but because the packages to install just don't exist.

If we can figure out a recommendation for Linux users on how to get a working arm-none-abi-gdb GDB that is universal, then we will gladly integrate that into the instructions.

Note that we recommend the toolchain for its GCC specifically - the backdrop to this is that if you install Ubuntu's arm-none-eabi-gcc package from apt and build the firmware, it will miscompile due to a bug in their builds; This happening a significant amount over a few months is what lead to the current recommendation.

With point 7, we beat you to it slightly - see PR #1633 😅

We'd much appreciate the help sorting out this particular issue and figuring out what is meant by "bluepill" in the swlink platform. We'd also note that it was point out to us a couple of days ago that the board should specifically be referred to as the Blue Pill, not Bluepill, so that also needs updating across the documentation.

[vatrat]

Specifically for python, as far as I know installing any version of python3.8 (ex. from the python website) works. The GNU-RM installation guidelines would be helpful. Ordinarily I'd agree it's an upstream issue, but I'm not expecting arm to change anything. For the python issue, posting instructions on making a venv (or pointing to a different python installation, don't know how windows works) and which variables to set (PYTHONHOME, PYTHONPATH) would go a long way toward helping people to figure it out themselves on other platforms.

Who pointed out Blue Pill vs Bluepill? I was under the impression that was an unofficial title, with the semi-official being Shenzhen-LC stm32f103 board, Minimum System Development Board, or just calling it a clone of the original, which was from acorn(?), pine(?) or something a few years before the blue pill boards became popular.

I'm setting up my soldering equipment to turn this blue pill into a decent BMP.

[dragonmux]

Re Python 3.8: You can download a source tarball from the Python website, but you cannot download prebuilt packages. This then winds up bringing up the problem of "so where do we ask the user to install this custom build, that's outside their package manager", and so on.

It's not about venvs, because those only apply after you've installed the Python binaries themselves, but the actual Python binaries - you can't just symlink libpython3.10.so to libpython3.8.so for example, as they're binary incompatible. It requires specifically Python 3.8 packages or a custom build - hence the problem.

We can fix this for Windows easily enough as that is a prebuilt package installer (and ARM properly ships Python for Windows in that download of the toolchain), and we can sort of fix it for macOS - but that leaves Linux users out in the cold still.

The Blue Pill name comes from WeActStudio originally, from what we've been able to tell. Specifically their Blue Pill+ board. All the clones of this get called the same, and hence the STM32 Base name and spacing.

[vatrat]

I'm afraid I still can't get any results from a scan.
Connections:

• PROBE/TARGET
• A5/A14
• A14/A13
• GND/GND
• 3v3/3v3

Neither SW-DP not JTAG scan return any results. I've tried a few devices.
Enabling and connecting nRST doesn't change anything (B0->R)

[dragonmux]

Assuming a STM32F1 based processor on the target, the target's SWD interface is on pins 34 and 37 (PA13 - SWDIO, PA14 - SWCLK) so that bit's right. Looks like we transcribed the TMS/SWDIO pin wrong though - that should have been PB14. We'll update the PR accordingly if that then works - apologies.

[vatrat]

Oops! I shouldn't have trusted yet another secondhand source, next time I'll just consult platform.h. It DID seem weird to me that it was reusing PA14.

[vatrat]

Works now!

[dragonmux]

Excellent, we've updated the platform PR with that fix and a note to readers to help prevent them making the same mistake

[vatrat]

Wonderful! I'm actually just learning to do arm programming on linux. I know how to program ARM processors in two ways:

• In Thumb2(T32) assembly on Windows with Keil uVision
• In Forth over UART using mecrisp-stellaris on linux

It'll take me a while to get used to this, but I'll be glad when I get to stop using windows.

[vatrat]

I've found the official ARM instructions for installing the toolchain. They are incomplete.
Instructions

[vatrat]

ARM released a new toolchain today, version 13.2Rel1. I'll see if anything has changed when I have time.

It still requires python 3.8, but they have included instructions in the release notes.

To use GDB, Python 3.8 is required to be installed, and on Ubuntu 20.04 or later you might also need to install libncurses5 or libncursesw5. You might need to install Python 3.8 from source. The information about installing Python can be found from other sources or websites, unaffiliated to Arm, for example, from docs.python.org, or from LinuxCapable. For GDB to be able to detect the existence of an installed Python 3.8 library on the system, you might also need to set the PYTHONPATH and PYTHONHOME environment variables. Set PYTHONHOME to the location where the Python 3.8 libraries are. For example, if Python 3.8 was installed to /usr/lib or /usr/lib64, then set PYTHONHOME=/usr. In order to find the correct value for PYTHONPATH, run python3.8 -c "import sys; print(sys.path)" and look for the path ending in /python3.8. Set PYTHONPATH=<that path ending in /python3.8>.