Debug probes

The debug probe is the interface between pyOCD and the target, and it drives the SWD or JTAG signals that control the target. By way of the connection between the debug probe and target, selecting the debug probe implicitly controls which target pyOCD debugs.

There are two major flavours of debug probe:

  • On-board probes. Many evaluation boards include an on-board debug probe, so you can plug it in and start using it without needing any other devices.
  • Standalone probes. For debugging custom hardware you typically need a standalone probe that connects via an SWD/JTAG cable. Most commercially available debug probes, such as the SEGGER J-Link or Arm ULINKplus, are standalone.

PyOCD uses debug probe driver plug-ins to enable support for different kinds of debug probes. It comes with plug-ins for these types of debug probes:

Plug-in Name Debug Probe Type
cmsisdap CMSIS-DAP
pemicro PE Micro Cyclone and Multilink
picoprobe Raspberry Pi Picoprobe
jlink SEGGER J-Link
stlink STMicro STLinkV2 and STLinkV3
remote pyOCD remote debug probe client

Unique IDs

Every debug probe has a unique ID. For debug probes that connect with USB, this is nominally the same as its USB serial number. However, every debug probe plugin determines for itself what the unique ID means. Some debug probes types are not connected with USB but are accessed across the network. In this case, the unique ID is the probe’s network address.

The unique ID parameter is actually a simple form of URL. It can be prefixed with the name of a debug probe plugin followed by a colon, e.g. cmsisdap:, to restrict the type of debug probe that will match. This form is also a requirement for certain probe types, such as the remote probe client, where the unique ID is a host address rather than serial number.

Auto target type identification

Certain types of on-board debug probes can report the type of the target to which they are connected.

Debug probes that support automatic target type reporting:

  • CMSIS-DAP probes based on the DAPLink firmware
  • STLinkV2-1 and STLinkV3

Listing available debug probes

To view the connected probes and their unique IDs, run pyocd list. This command will produce output looking like this:

  #   Probe                             Unique ID
------------------------------------------------------------------------------------------
  0   Arm LPC55xx DAPLink CMSIS-DAP     000000803f7099a85fdf51158d5dfcaa6102ef474c504355
  1   Arm Musca-B1 [musca_b1]           500700001c16fcd400000000000000000000000097969902

For those debug probes that support automatic target type reporting, the default target type is visible in brackets next to the probe’s name. In addition, the name of the board is printed instead of the type of debug probe. This can be seen in the example output above for the “Arm Musca-B1” board, which has a default target type of musca_b1.

If no target type appears in brackets, as can be seen above for the “Arm LPC55xx DAPLink CMSIS-DAP” probe (because it is a standalone probe), it means the debug probe does not report the type of its connected target. In this case, the target type must be manually specified either on the command line with the -t / --target argument, or by setting the target_override session option (possibly in a config file).

Note that the printed list includes only those probes that pyOCD can actively query for, which currently means only USB based probes.

Selecting the debug probe

All of the pyOCD subcommands that communicate with a target require the user to either implicitly or explicitly specify a debug probe.

There are three ways the debug probe is selected:

  1. Implicitly, if only one probe is connected to the host, pyOCD can use it automatically without further configuration.

  2. If there is more than one probe connected and pyOCD is not told which to use, it will ask on the console. It presents the same list of probes reported by pyocd list, plus this question:

     Enter the number of the debug probe or 'q' to quit>
    

    and waits until a probe index is entered.

  3. Explicitly, with the use of -u UID / --uid=UID / --probe=UID command line arguments. These arguments accept either a whole or partial unique ID.

If no probes are currently connected and pyOCD is executed without explicitly specifying the probe to use, it will by default print a message asking for a probe to be connected and wait. If the -W / --no-wait argument is passed, pyOCD will exit with an error instead.

Probe driver plug-in notes

This section contains notes on the use of different types of debug probes and the corresponding driver plug-ins.

CMSIS-DAP

CMSIS-DAP is a debug probe protocol designed by Arm and released as open source as part of the CMSIS project. There are two major versions of CMSIS-DAP, which use different USB classes:

  • v1: USB HID. This version is slower than v2. Still the most commonly seen version, although it is now deprecated by Arm.
  • v2: USB vendor-specific using bulk pipes, permitting higher performance than v1. WinUSB-enabled to allow driverless usage on Windows 8 and above. (Can be used with Windows 7 if device installation settings are set to automatically download and install drivers for new devices from the Internet.)

These are some of the commercial probes by silicon vendors using the CMSIS-DAP protocol, both standalone and on-board:

  • Microchip EDBG and variants
  • Microchip Atmel-ICE
  • Cypress KitProg3
  • Cypress MiniProg4
  • Keil ULINKplus
  • NXP LPC-LinkII
  • NXP MCU-Link
  • NXP MCU-Link Pro
  • NXP OpenSDA

In addition, there are numerous other commercial and open source debug probes utilising the CMSIS-DAP protocol.

PyOCD supports automatic target type identification for debug probes built with the widely used DAPLink firmware.

DAPLink firmware updates

Session options

  • cmsis_dap.deferred_transfers (bool, default True) Whether to use deferred transfers in the CMSIS-DAP probe backend. By disabling deferred transfers, all writes take effect immediately. However, performance is negatively affected.
  • cmsis_dap.limit_packets (bool, default False) Restrict CMSIS-DAP backend to using a single in-flight command at a time. This is useful on some systems where USB is problematic, in particular virtual machines.

Microchip EDBG

The Microchip (previously Atmel) EDBG probe firmware, at the time of this writing, provides a CMSIS-DAP v1 interface. On macOS, reading command responses always times out. The probe works on other OSes, however.

Recent STLink firmware versions will only allow access to STM32 targets. If you are using a target from a silicon vendor other than ST Micro, please use a different debug probe.

No host resident drivers need to be installed to use STLink probes; only libusb is required.

The minimum supported STLink firmware version is V2J24, or any V3 version. However, upgrading to the latest version is strongly recommended. Numerous bugs have been fixed, and new commands added for feature and performance improvements.

  • V2J26: Adds 16-bit transfer support. If not supported, pyOCD will fall back to 8-bit transfers—it is possible this will produce unexpected behaviour if used to access Device memory (e.g. memory mapped registers).
  • V2J28: Minimum version for multicore target support.
  • V2J32/V3J6: Allows access to banked DP registers. Usually not needed.

Firmware updates

PyOCD supports automatic target type identification for on-board STLink probes that report a board ID.

STLinkV3 SWD/JTAG frequencies

The STLinkV3 has an internal clock frequency control for its HCLK prescaler that allows access to different SWD/JTAG frequencies. The prescaler can be set from pyOCD with the stlink.v3_prescaler session option to 1, 2, or 4. In addition to changing the available SWD/JTAG frequencies, modifying the prescaler also affects UART baud rates and frequencies of the serial I/O bridge interfaces.

These are the SWD/JTAG frequencies available with different values of stlink.v3_prescaler:

prescaler=1 (default) prescaler=2 prescaler=4
24.0 MHz 12.0 MHz 6.0 MHz
8.0 MHz 4.0 MHz 2.0 MHz
3.3 MHz 1.6 MHz 850 kHz
1.0 MHz 1.0 MHz 520 kHz
200 kHz 200 kHz 200 kHz
50 kHz 50 kHz 50 kHz

Session options

  • stlink.v3_prescaler (int, must be 1, 2, or 4, default 1) Configures the HCLK prescaler of an STLinkV3 to modify the range of available SWD/JTAG frequencies, as described above. Affects available frequencies of other peripherals, such as UART, as well.

To use a Segger J-Link probe, the driver package must be installed. Segger makes drivers available for Linux, macOS, and Windows.

Firmware and driver installer and updates

On macOS, you can install the segger-jlink cask with Homebrew to get managed driver updates.

Please note that flash programming performance using a J-Link through pyOCD is currently slower than using the J-Link software directly (or compared to CMSIS-DAP). This is because pyOCD uses the low-level DAP commands provided by J-Link, which are inherently slower than higher level commands (which are less flexible and more difficult and complex to integrate).

Serial numbers

The USB serial number for J-Link probes will have leading zeroes. However, the J-Link driver and applications do not use leading zeroes. PyOCD also does not use leading zeroes, as it interfaces with the J-Link through its driver.

Session options

  • jlink.device (str, no default) If this option is set to a supported J-Link device name, then the J-Link will be asked connect using this name. Otherwise, the J-Link is configured for only the low-level CoreSight operations required by pyOCD. Ordinarily, it does not need to be set.
  • jlink.power (bool, default True) Enable target power when connecting via a J-Link probe, and disable power when disconnecting.
  • jlink.non_interactive (bool, default True) Controls whether the J-Link DLL is allowed to present UI dialog boxes and its control panel. Note that dialog boxes will actually still be visible, but the default option will be chosen automatically after 5 seconds.