buck50: Test and measurement firmware for "Blue Pill" STM32F103

buck50 is open-source firmware that turns a "Blue Pill" STM32F103 development board (widely available for approx. US$1.50) into a multi-purpose test and measurement instrument, including:

• 8 channel, 6+ MHz logic analyzer
  • Approx. 5K sample buffer depth
  • Samples stored only at signal edges for efficient memory usage
  • Units may be ganged for increased number of channels
  • Complex triggering via user-defined state machine supporting combinations of sequential ("A then B then C") and logical-OR ("A or B or C") conditionals
  • Output to VCD and other file formats for export to waveform viewing software ¹
• Live monitoring and logging of digital, analog, USART (sync/async), SPI (MOSI/MISO), and I2C (master/slave/TX/RX) data
• Simple dual-channel approx. 1 MHz digital storage oscilloscope, approx. 5K sample buffer depth (10K if single channel)
• 3 channel digital pulse train generator with user-defined frequency and per-channel duty cycle and polarity
• Bidirectional bridge/converter from USART/UART (async/synchro), SPI (master/slave), or I2C ... to USB ... to host terminal, UNIX socket, or UNIX pty device file
• 8-bit parallel output counter (binary or gray code)
• Host terminal ascii or binary input data to 8-bit parallel output
• Firmware written in a combination of C++ and ARM Thumb-2 assembly code, with several non-standard hacks^H^H^H^H^Htechniques of possible general interest to advanced software developers
• Python host driver program with comprehensive inline help system and usability features
• Coffee maker attachment sold separately, not included in base price ²

<br> <a name="contents"></a> Contents

• License
• Firmware installation
• Hardware connections
• buck50.py driver program
  • Python
  • Where's the GUI?
  • TL;DNR("Too Long, Did Not Read")
  • NLE;WTRSBNTMM(“Not Long Enough, Want To Read Some But Not Too Much More”)
  • OK;TSIGMTW9Y("OK, This Sounds Interesting, Give Me The Whole 9 Yards")
    • buck50.py startup and device connection
    • review license
    • help
    • usage help
    • configure command
    • logic command
    • oscope command
    • dump command
    • trigger command
    • monitor command
    • lines configuration
    • adcN configurations
    • numbers command(*)
    • gpio command
    • usart command
    • spi command
    • i2c command
    • ipc configuration
    • pty configuration
    • socket configuration
    • pulse command(*)
    • reset command
• Waveform viewing software
  • gnuplot
  • gtkwave
  • PulseView
  • Logic
• Firmware design and implementation
  • Port assignments
  • Hacks^H^H^H^H^Htechniques
    • Infinite loop
    • longjmp from interrupt handler
    • Sparse timestamped samples
  • Why so slow?
• Building from source
• Current version
• Future work
• Footnotes

<br> <a name="license"></a> License

buck50: Test and measurement firmware for "Blue Pill" STM32F103 development board

Copyright (C) 2019,2020 Mark R. Rubin aka "thanks4opensource"

This file is part of buck50.

The buck50 program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The buck50 program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the buck50 program. If not, see https://www.gnu.org/licenses/gpl.html

<br> <a name="firmware_installation"></a> Firmware installation

buck50 is provided as ready-to-flash files in ELF (buck50.elf), binary (buck50.bin), and Intel hex (buck50.hex) formats in addition to source code (see Building from source, below).

Instructions on how to flash code onto microcontrollers such as the STM32F103 are beyond the scope of this document. Briefly, the STM32F103 cannot be flashed via its USB port (except ³), so other techniques must be employed.

Probably the best method is via the "Blue Pill" SWD port (see Hardware connections, below) using either a Black Magic Probe (website, wiki) or an ST-Link (website) or clone thereof (Google search). Note that the former is used with GDB from the GNU Arm Embedded Toolchain and the latter either with GDB or stlink (GitHub repository) among other software front ends.

Alternately, the "Blue Pill" can be flashed via its USART1 serial port (RX on port PA10, TX on PA9, see below). This typically requires a USB-to-serial converter (Google search) (or, ironically, another already-flashed "buck50" ⁴) as modern host computers rarely include an RS-232 port. Instructions and software required for doing so can be found at the stm32flash SourceForge website, this tutorial web page, and/or a GitHub wiki, among other resources. If using a serial port method remember to change the BOOT0 jumper (see directly below) back to its "0" position after flashing with it set to "1".

<br> <a name="hardware_connections"></a> Hardware connections

The following is a highly simplified, edited version of the incredibly useful image created by Rasmus Friis Kjeldsen ⁵, available at http://reblag.dk/stm32/ (direct link: http://reblag.dk/wordpress/wp-content/uploads/2016/07/The-Generic-STM32F103-Pinout-Diagram.pdf). The edited and original versions are included in this repository under terms in compliance with the original's license.

WARNING! Incorrect hookups to the "Blue Pill" (or any other microcontroller's) ports may cause permanent damage. Examples: Connecting a push-pull output port directly to a positive voltage source or ground sink, or to another push-pull output on the same or different MCU set to the opposite polarity. Readers of this document and users of the firmware it describes assume all responsibility for their actions.

Pin descriptions

The buck50 firmware configures and uses the "Blue Pill" STM32F103 GPIO ports as follows. Note that many pins have multiple uses depending on which buck50.py host command is in effect, including changing roles to be either inputs, outputs, or bidirectional.

    Pin(s)    Type                              Purpose                             buck50.py commands
    ======    ==============================    =================================   ==================
    PB4-11    input   weak pull-down            digital input                       logic, monitor
    PB10,11   in/out  open-drain                I2C                                 i2c, monitor
    PA0-7     output  push-pull                 digital output                      numbers, gpio
    PA0-7     input   analog                    analog input                        oscope, monitor
    PA1-3     output  push-pull                 digital pulse outputs               pulse
    PA0       input   weak pull-up              usart CTS                           usart
    PA1       output  push-pull                 usart RTS                           usart
    PA2       output  push-pull                 usart TX                            usart
    PA3       input   weak pull-up              usart RX                            usart
    PA4       output  push-pull                 SPI select output (master)          spi, monitor
    PA4       input   floating                  SPI