Is a python module for debugging microcontrollers with SWD using ST-Link/V2 (/V2-1) or V3 debugger.

This package also contain small command line tool.

Is to create python module for access debugging interface on MCU with SWD interface.

Main purpose of python module is to create automated functional and hardware tests from simple python scripts and without special firmware for microcontroller.

PYSWD will work on Linux, Mac and Windows.

Python 3.7+

• pyusb - prefer latest version from github, especially on Windows platgorm
• libusb

pip3 install .

pip3 install --upgrade .

pip3 install --editable .

pip3 uninstall pyswd

make test
make install
make editable
make uninstall

swd.Swd(swd_frequency=4000000, logger=None, serial_no='')

• swd_frequency: SWD communication frequency
• logger: logging interface (optional)
• serial_no: serial number of connected USB ST-Link debugger (optional). Serial number can be also part from begin or end, if more devices are detected then it stops with error

>>> import swd
>>> dev = swd.Swd()

property with ST-Link version

instance of StlinkVersion

>>> dev.get_version().str
'ST-Link/V2 V2J27S6'

Get target voltage measured by ST-Link

float target voltage in volts

>>> dev.get_target_voltage()
3.21

Get MCU ID code

32bit unsigned with ID code

>>> hex(dev.get_idcode())
'0xbb11477'

get_mem32(address)

• address: address in memory, must be aligned to 32bits

32bit unsigned data from memory

>>> hex(dev.get_mem32(0x08000000))
'0x20001000'

set_mem32(address, data)

• address: address in memory, must be aligned to 32bits
• data: 32bit unsigned data

>>> dev.set_mem32(0x20000200, 0x12345678)
>>> hex(dev.get_mem32(0x20000200))
'0x12345678'

• read_mem(address, size) - automatically select read access
• read_mem8(address, size) - read using 8 bit access
• read_mem16(address, size) - read using 16 bit access
• read_mem32(address, size) - read using 32 bit access

• address: address in memory
• size: number of bytes to read from memory

iterable of read data

>>> data = dev.read_mem(0x08000000, 16)
>>> ' '.join(['%02x' % d for d in data])
'00 10 00 20 45 00 00 08 41 00 00 08 41 00 00 08'

• write_mem(address, data) - automatically select write access
• write_mem8(address, data) - write using 8 bit access
• write_mem16(address, data) - write using 16 bit access
• write_mem32(address, data) - write using 32 bit access

• address: address in memory
• data: list or iterable of bytes whic will be stored into memory

>>> dev.write_mem(0x20000100, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
>>> data = dev.read_mem(0x20000100, 15)
>>> ' '.join(['%02x' % d for d in data])
'01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f'

• fill_mem(address, pattern, size) - automatically select fill access
• fill_mem8(address, pattern, size) - fill using 8 bit access
• fill_mem16(address, pattern, size) - fill using 16 bit access
• fill_mem32(address, pattern, size) - fill using 32 bit access

• address: address in memory
• pattern: list or iterable of bytes whic will be stored into memory
• size: number of bytes to fill memory

>>> dev.fill_mem(0x20000300, [5, 6, 7], 20)
>>> data = dev.read_mem(0x20000300, 20)
>>> ' '.join(['%02x' % d for d in data])
'05 06 07 05 06 07 05 06 07 05 06 07 05 06 07 05 06 07 05 06'

get_reg(register) On CortexM platform this will work only if program is halted

• register: is numeric coded register (e.g. 0: R0, 1: R1, ...)

32bit unsigned data

>>> hex(dev.get_reg(1))
'0x0800012e'

get_reg_all() On CortexM platform this will work only if program is halted

list of 32bit unsigned data for all registers

>>> dev.get_reg_all()
[0,  0,  16942,  10,  100,  0,  0,  0,  0,  0,  0,  0,  10,  604502776,  134288075,  134284002,  1627389952,  604502776,  0,  0,  67125248]

get_reg(register) On CortexM platform this will work only if program is halted

• register: is numeric coded register (e.g. 0: R0, 1: R1, ...)
• data: 32bit unsigned data

>>> dev.set_reg(1, 0x12345678)

swd.CortexM(swd)

• swd: instance of Swd

>>> import swd
>>> dev = swd.Swd()
>>> cm = swd.CortexM(dev)

get_reg(register) On CortexM platform this will work only if program is halted

• register: name of register (e.g.: 'R0', 'R1', 'SP', 'PC', ...)

32bit unsigned data

>>> hex(cm.get_reg('PC'))
'0x0800012e'

set_reg(register) On CortexM platform this will work only if program is halted

• register: name of register (e.g.: 'R0', 'R1', 'SP', 'PC', ...)
• data: 32bit unsigned data

>>> cm.set_reg('R2', 0x12345678)

get_reg_all() On CortexM platform this will work only if program is halted

dictionary with register name as key and as value 32bit unsigned data for each register

>>> cm.get_reg_all()
{'LR': 134288075,
 'MSP': 604502776,
 'PC': 134284002,
 'PSP': 0,
 'PSR': 1627389952,
 'R0': 0,
 'R1': 0,
 'R10': 0,
 'R11': 0,
 'R12': 10,
 'R2': 16942,
 'R3': 10,
 'R4': 100,
 'R5': 0,
 'R6': 0,
 'R7': 0,
 'R8': 0,
 'R9': 0,
 'SP': 604502776}

reset()

>>> cm.reset()

reset_halt()

>>> cm.reset_halt()

halt()

>>> cm.halt()

step()

>>> cm.step()

run()

>>> cm.run()

nodebug()

>>> cm.nodebug()

is_halted()

True if MCU is halted, or False if is running

>>> cm.is_halted()
True

Some MCUs (with STM32H5 series as an example) could have multiple independent APs (debug access ports). In such cases, you will need to specify which AP debugger should use:

swd.open_ap(1)
swd.default_ap = 1

# continue using as usual:
cm = CortexM(swd)
print(cm.get_reg_all())

Note that you should use only CortexM high-level functions, as these functions will dynamically select between ST-Link native implementation (which is faster, but supports only AP0) and software emulation via memory accesses. SWD class exposes ST-Link native implementation directly, regardless of default AP selected.

To dynamically detect which MCU is attached, you could use IDCODE and DBGMCU registers. Both methods are AP-independent, as DBGMCU register block is available on AP0 as well.

Simple tool for access MCU debugging features from command line. Is installed together with python module.

$ pyswd --help

pyswd [-h] [-V] [-q] [-d] [-i] [-v] [-f FREQ] [action [action ...]]

action                actions will be processed sequentially

-h, --help            show this help message and exit
-V, --version         show program's version number and exit
-q, --quite           quite output
-d, --debug           increase debug output
-i, --info            increase info output
-v, --verbose         increase verbose output
-f FREQ, --freq FREQ  set SWD frequency
-s SERIAL, --serial SERIAL
                        select ST-Link by serial number (enough is part of serial number: begin or end

  dump8:{addr}[:{size}]     print content of memory 8 bit register or dump
  dump16:{addr}[:{size}]    print content of memory 16 bit register or dump
  dump32:{addr}[:{size}]    print content of memory 32 bit register or dump
  dump:{addr}[:{size}]      print content of memory 32 bit register or 8 bit dump

  set8:{addr}:{data}[:{data}..]     set 8 bit memory
  set16:{addr}:{data}[:{data}..]    set 16 bit memory
  set32:{addr}:{data}[:{data}..]    set 32 bit memory
  set:{addr}:{data}[:{data}..]      set 32 bit memory register or 8 bit memory area

  fill8:{addr}:{size}:{pattern}     fill memory with 8 bit pattern

  reg:all                   print all core register
  reg:{reg}                 print content of core register
  reg:{reg}:{data}          set core register

  reset[:halt]              reset core or halt after reset
  run[:nodebug]             run core
  step[:{n}]                step core (n-times)
  halt                      halt core

  sleep:{seconds}           sleep (float) - insert delay between commands

(numerical values can be in different formats, like: 42, 0x2a, 0o52, 0b101010, 32K, 1M, ..)

Whole project is under MIT license