Roll Your Own Flash & Debug Tools
Scripting OpenOCD, GDB, pyOCD, pylink & bootloaders

# --- probe: ST-Link v2/v3 (Nucleo/Discovery on-board or standalone) ---
source [find interface/stlink.cfg]
# stlink.cfg defaults to SWD via the high-level adapter (hla_swd).
# For a v3 in DAP mode use: source [find interface/stlink-dap.cfg]

# --- target: STM32L4 family (covers L4R5) ---
source [find target/stm32l4x.cfg]

adapter speed 1800          # kHz; drop to 480 for long/flaky wiring
reset_config srst_nogate    # use SRST for reliable reset-halt

# One-shot: full-chip erase, program ELF, verify, run, then quit OpenOCD.
proc flash_run {image} {
    reset init                       # halt + init clocks for the flash loader
    stm32l4x mass_erase 0            # erase bank 0 (use 1 for bank 2)
    flash write_image erase "$image" 0 elf
    verify_image "$image"
    reset run
    shutdown                         # exit with code 0 on success
}

# Program a raw binary at a chosen offset (default main flash).
proc flash_bin {image {offset 0x08000000}} {
    program "$image" verify reset exit "$offset"
}

# Read a 32-bit word / poke memory from a script.
proc peek {addr}       { mem2array v 32 $addr 1; return $v(0) }
proc poke {addr val}   { mww $addr $val }

# ELF: verify + reset + exit in one line, no separate GDB needed
openocd -f stm32l4r5.cfg -c "flash_run build/app.elf"

# Built-in helper (equivalent for most cases)
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg \
        -c "program build/app.elf verify reset exit"

# Raw binary at the flash base
openocd -f stm32l4r5.cfg -c "flash_bin build/app.bin 0x08000000"

# Chain arbitrary commands with -c; each is one Tcl line
openocd -f stm32l4r5.cfg \
  -c "init" -c "reset halt" \
  -c "stm32l4x mass_erase 0" \
  -c "flash write_image erase build/app.bin 0x08000000 bin" \
  -c "reset run" -c "shutdown"

# Assumes a gdbserver (OpenOCD/pyOCD) is already listening on :3333
target extended-remote :3333
monitor reset halt          # "monitor" forwards to OpenOCD/pyOCD
load                        # download the ELF sections into flash
compare-sections            # read-back verify every loadable section
monitor reset run
detach
quit

# 1) Start the gdbserver in the background
openocd -f stm32l4r5.cfg &
OCD_PID=$!

# 2) Run the command file in batch mode (exit code propagates)
arm-none-eabi-gdb --batch -x flash.gdb build/app.elf

# 3) Clean up the server
kill $OCD_PID

# --- or: everything inline, no .gdb file needed ---
arm-none-eabi-gdb --batch \
  -ex "target extended-remote :3333" \
  -ex "monitor reset halt" \
  -ex "load" \
  -ex "compare-sections" \
  -ex "monitor reset run" \
  -ex "detach" -ex "quit" \
  build/app.elf

pip install pyocd

pyocd pack update                      # refresh the pack index
pyocd pack find stm32l4r5              # show matching devices
pyocd pack install stm32l4r5          # download + register the DFP

# Confirm the precise target type (e.g. stm32l4r5xg / stm32l4r5xi)
pyocd list --targets | grep -i l4r5
pyocd list --probes                    # show connected probes + unique IDs

TGT=stm32l4r5xi        # use the string printed by "pyocd list --targets"

# ELF/HEX carry their own addresses; program + verify are automatic
pyocd flash -t $TGT build/app.elf

# Raw .bin needs an explicit base address
pyocd flash -t $TGT --base-address 0x08000000 build/app.bin

pyocd erase -t $TGT --chip              # full mass erase (or --sector A B)
pyocd reset -t $TGT                      # hardware reset the target

# GDB server on :3333; --persist survives client disconnects (CI reuse)
pyocd gdbserver -t $TGT --persist --frequency 4000000

# Pick a specific probe when several are attached
pyocd flash -t $TGT -u 066EFF... build/app.elf

#!/usr/bin/env python3
# pip install pyocd ; requires the L4R5 pack installed (see above)
from pyocd.core.helpers import ConnectHelper
from pyocd.flash.file_programmer import FileProgrammer

TARGET = "stm32l4r5xi"
FLASH_BASE = 0x08000000

# session_with_chosen_probe picks the only probe, or prompts / honours -u
with ConnectHelper.session_with_chosen_probe(
        target_override=TARGET,
        options={"frequency": 4_000_000}) as session:

    target = session.target

    # Program a file (chip_erase: "sector" | "chip" | "auto")
    prog = FileProgrammer(session, chip_erase="sector")
    prog.program("build/app.hex")          # .elf/.hex/.bin all supported
    # For .bin: prog.program("app.bin", base_address=FLASH_BASE, file_format="bin")

    # Inspect / poke memory directly over SWD
    target.reset_and_halt()
    sp    = target.read32(FLASH_BASE)      # initial stack pointer
    reset = target.read32(FLASH_BASE + 4)  # reset handler address
    print(f"SP=0x{sp:08x}  Reset=0x{reset:08x}")

    target.write32(0x20000000, 0xDEADBEEF) # scribble RAM for a test
    assert target.read32(0x20000000) == 0xDEADBEEF

    target.reset_and_halt()
    target.resume()                        # let the app run

pip install pylink-square          # import name is still "pylink"
# Requires SEGGER J-Link Software & Documentation Pack (provides the DLL)

#!/usr/bin/env python3
import pylink

DEVICE = "STM32L4R5ZI"             # SEGGER device string (case-insensitive)
FLASH_BASE = 0x08000000

jlink = pylink.JLink()
jlink.open()                       # or JLink().open(serial_no=504302020)
jlink.set_tif(pylink.enums.JLinkInterfaces.SWD)
jlink.connect(DEVICE, speed="auto", verbose=True)

print("Core ID: 0x%08x" % jlink.core_id())

# flash_file() erases the needed sectors, programs, and verifies
jlink.reset(halt=True)
jlink.flash_file("build/app.bin", FLASH_BASE)

# Direct memory access mirrors pyOCD
sp = jlink.memory_read32(FLASH_BASE, 1)[0]
print("Initial SP: 0x%08x" % sp)
jlink.memory_write32(0x20000000, [0xDEADBEEF])

jlink.reset(halt=False)            # reset and let the app run
jlink.close()

# Probe: reads chip PID + bootloader version (confirms wiring/BOOT0)
stm32flash /dev/ttyUSB0

# Write + verify + jump to the app at the flash base
stm32flash -w build/app.bin -v -g 0x08000000 /dev/ttyUSB0

# Faster link (bootloader auto-bauds), .hex also accepted
stm32flash -b 115200 -w build/app.hex -v /dev/ttyUSB0

stm32flash -o /dev/ttyUSB0        # mass erase only
stm32flash -r backup.bin -S 0x08000000:0x1000 /dev/ttyUSB0  # read back 4 KB

# Auto-toggle BOOT0/RESET via DTR/RTS, then reset out via RTS after write
stm32flash -R -i '-dtr,rts,:dtr,-rts' -w build/app.bin -v /dev/ttyUSB0

# With BOOT0 high + reset, the L4R5 appears as 0483:df11
dfu-util -l                        # list DFU devices + alt settings

# Program raw binary at the flash base, then leave DFU and run
dfu-util -a 0 -d 0483:df11 -s 0x08000000:leave -D build/app.bin

# DFU wants a .bin (or DfuSe .dfu): convert from ELF first
arm-none-eabi-objcopy -O binary build/app.elf build/app.bin

#!/usr/bin/env python3
# pip install pyserial ; usage: boot_probe.py /dev/ttyUSB0
import serial, sys

INIT, ACK, NACK = 0x7F, 0x79, 0x1F

port = serial.Serial(sys.argv[1], 57600,
                     parity=serial.PARITY_EVEN,   # 8e1 — required
                     stopbits=serial.STOPBITS_ONE,
                     timeout=1)

# 1) Auto-baud + enter: single 0x7F, expect ACK
port.write(bytes([INIT]))
if port.read(1) != bytes([ACK]):
    sys.exit("no ACK - is BOOT0 high and the part in bootloader mode?")

# 2) Get command: 0x00 + its complement 0xFF (every cmd is checksummed)
port.write(bytes([0x00, 0xFF]))
if port.read(1) != bytes([ACK]):
    sys.exit("Get command rejected")

n    = port.read(1)[0]              # number of bytes that follow (minus 1)
body = port.read(n + 1)            # [bootloader_version, cmd0, cmd1, ...]
port.read(1)                        # trailing ACK

print("Bootloader version: 0x%02x" % body[0])
print("Supported cmds:", body[1:].hex())

#!/usr/bin/env python3
# pip install pyusb   (needs libusb backend)
import usb.core, usb.util

dev = usb.core.find(idVendor=0x0483, idProduct=0xDF11)
if dev is None:
    raise SystemExit("STM32 DFU device not found (BOOT0 high + reset?)")

print("Found STM32 bootloader:", usb.util.get_string(dev, dev.iProduct))
for cfg in dev:
    for intf in cfg:
        s = usb.util.get_string(dev, intf.iInterface)
        print(f"  alt {intf.bAlternateSetting}: {s}")   # e.g. "@Internal Flash /0x08000000/..."

#!/usr/bin/env bash
# flash.sh <firmware.elf|.bin> [method]   method: openocd|pyocd|dfu|serial
set -euo pipefail

FW="${1:?usage: flash.sh <firmware> [openocd|pyocd|dfu|serial]}"
METHOD="${2:-${FLASH_METHOD:-openocd}}"
FLASH_ADDR="${FLASH_ADDR:-0x08000000}"
CFG="${OOCD_CFG:-stm32l4r5.cfg}"
PORT="${PORT:-/dev/ttyUSB0}"
TGT="${PYOCD_TARGET:-stm32l4r5xi}"

# Return a .bin path (objcopy if the input is an ELF)
to_bin() {
  case "$1" in
    *.bin) printf '%s' "$1" ;;
    *) arm-none-eabi-objcopy -O binary "$1" /tmp/fw.bin; printf '%s' /tmp/fw.bin ;;
  esac
}

echo "==> flashing $FW via $METHOD"
case "$METHOD" in
  openocd)
    openocd -f "$CFG" -c "program $FW verify reset exit" ;;
  pyocd)
    pyocd flash -t "$TGT" "$FW"
    pyocd reset -t "$TGT" ;;
  dfu)
    BIN="$(to_bin "$FW")"
    dfu-util -a 0 -d 0483:df11 -s "${FLASH_ADDR}:leave" -D "$BIN" ;;
  serial)
    BIN="$(to_bin "$FW")"
    stm32flash -w "$BIN" -v -g "$FLASH_ADDR" "$PORT" ;;
  *)
    echo "unknown method: $METHOD" >&2; exit 2 ;;
esac
echo "==> done"

chmod +x flash.sh
./flash.sh build/app.elf                 # default: openocd
./flash.sh build/app.elf pyocd
FLASH_METHOD=serial PORT=/dev/ttyUSB0 ./flash.sh build/app.bin
./flash.sh build/app.elf dfu             # auto-objcopy to .bin

name: hil-flash
on: [push]

jobs:
  flash:
    runs-on: [self-hosted, stm32l4r5]      # runner with a probe attached
    steps:
      - uses: actions/checkout@v4

      - name: Build firmware
        run: make -j$(nproc)

      - name: Flash + verify
        env:
          OOCD_CFG: ci/stm32l4r5.cfg
          PROBE_SERIAL: ${{ secrets.PROBE_SERIAL }}
        run: ./flash.sh build/app.elf openocd

      - name: Smoke test over UART
        run: ./scripts/smoke_test.py --port /dev/ttyACM0 --timeout 10

      - name: Save flash log
        if: ${{ always() }}
        uses: actions/upload-artifact@v4
        with:
          name: flash-log
          path: build/flash.log