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:

Additional debug probe plugins are available as Python packages through PyPI, and can be installed with pip:

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 supporting v2.1 of the protocol and reporting target type info
• 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/Board                       Unique ID                                          Target
--------------------------------------------------------------------------------------------------------------------
  0   Arm DAPLink CMSIS-DAP             02400b0129164e4500440012706e0007f301000097969900   ✔︎ k64f
      NXP                               FRDM-K64F

  1   STLINK-V3                         002500074741500420383733                           ✖︎ stm32u585aiix
      B-U585I-IOT02A

  2   STM32 STLink                      066EFF555051897267233656                           ✔︎ stm32l475xg
      DISCO-L475VG-IOT01A

  3   Segger J-Link OB-K22-NordicSemi   960177309                                          n/a

The output is divided into columns for the probe number, probe name, unique ID, and default target type name. Probes that have additional board identification will have a second row with the board name and possibly board vendor.

The “Target” column shows the debug probe’s default target type for debug probes that support automatic target type reporting. Whether that target type is installed and available for use is shown by a check or “X” mark before the target type name (and in different colours, if colour output is enabled). If an “X” mark is displayed, see the target support documentation for information about how you can install that the target type.

For debug probes that do not support automatic target type reporting, the Target column will simply display “n/a”. This can be seen above for the “Segger J-Link OB-K22-NordicSemi” probe. The target type must be specified manually in such cases, otherwise full functionality, such as flash programming, will not be available.

In any case, whether required because the probe doesn’t have a default, or to override the default, the target type can be specified either on the command line with the -t / --target argument, or by setting the target_override session option (e.g., 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.)

If a debug probe provides both v1 and v2 interfaces, pyOCD will normally use the v2 interface. (See the cmsis_dap.prefer_v1 option described below if this needs to be changed.)

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 any debug probe supporting CMSIS-DAP v2.1 or later that reports the target type from the DAP_Info command. Automatic target type identification is also supported for the widely used DAPLink firmware using the board ID system.

DAPLink firmware updates are available on the daplink.io site and on the project’s releases page on GitHub.

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.
• cmsis_dap.prefer_v1 (bool, default False) Determines whether pyOCD will choose a CMSIS-DAP v1 interface of v2 in cases where a device provides both for backwards compatibility. There is rarely a reason to change this option, except for testing or issues. Note: This option can only be set in a default config file (e.g., pyocd.yaml in the working directory) because of how options loading is ordered in relation to debug probe enumeration.

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.

TI XDS110

XDS110 firmware version 03.00.00.25 is known to have an issue when using multiple outstanding packets (the default setting). To work around this, set the cmsis_dap.limit_packets session option, e.g. -Ocmsis_dap.limit_packets=1 on the command line. Earlier firmware versions most likely exhibit the issue; it is unknown whether it is fixed in more recent versions.

PE Micro Cyclone and Multilink

The Cyclone and Multilink debug probes from PE Micro are supported through the use of a separate probe driver plugin called pyocd-pemicro. This plugin can be installed at any time using pip:

pip install pyocd-pemicro

It can also be installed at the same time as pyOCD by adding the pemicro install extra:

pip install pyocd[pemicro]

Once the PE Micro probe driver is installed, Cyclone and Multilink probes connected by USB will immediately be available for use.

Currently, PE Micro probes connected via the network are not accessible.

STLink

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/V3J2: Allows access to banked DP registers. Usually not needed.
• V2J32/V3J2: Supports setting the AHB and AXI transfer attributes. See set hnonsec and set hprot.

STLink firmware updates on www.st.com.

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:

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.

J-Link

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

J-Link firmware and driver installer and updates on www.segger.com

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.