Debugging Embedded Targets with pyOCD and Eclipse

If doing embedded development, then the debugging solution is probably the most important single tool in the development chain. Because very debugging probe has its pros and cons, I usually have at least three different debug probes on my desk, simply to get the job done in all aspects.

What is true for the hardware debugging probes, is true for the gdb client and server side. I’m using mostly the P&E, SEGGER and CMSIS-DAP plugins (e.g. NXP LinkServer) and OpenOCD from the Eclipse IDE side. But there are more choices, for example pyOCD.

pyOCD and Python

So far I ave, I avoided to use pyOCD for several reasons, mostly because it is centered around ARM only I had issues to get it working because of the Python dependency. But as my usual Triumvirate of debugging solutions failed on something around semihosting, I wanted to give pyOCD another chance.

pyOCD is a Python based debugging tool for ARM Cortex microcontroller. pyOCD comes with many useful features, like command line flash programming , semihosting and ARM ITM SWO printing.

pyOCD (Source:

While Python is getting more popular, Python as an environment can be tricky, as experienced in classroom environments with students and on my machine too. I recommend to try with a ‘clean’ python environment: just one version installed or clearly isolated. My earlier attempts to get it working on Windows with Eclipse failed, so I tried to get it working with the latest release, and finally: it worked with using Python v3.10.9 with pip v23.0 and pyOCD v0.34.3 :-).

As Eclipse I used the MCUXpresso IDE v11.7.0, but the steps should work for any recent Eclipse version.

pyOCD Installation

On a command line shell, install it with the pip package manager:

python3 -m pip install -U pyocd

Now the important part is the message at the end of the installation:

warning about Scripts folder not in PATH

I really don’t like cluttering my PATH environment variable, so adding this to my PATH is not an option. Instead: remember (copy-paste) that above path to the Scripts folder, we need that one later.

PEMICRO Debug Probes

PyOCD supports CMSIS-DAP (e.g. NXP Linkserver) and SEGGER J-Link based probes. To have support added for P&E debug probes (Multilink, etc), you need to install another package (see

python3 -m pip install pyocd_pemicro

If not using a P&E debug probe, this step can be skipped.

Eclipse Embedded CDT Plugin

Eclipse Embedded CDT has integrated the GNU ARM Eclipse plugins, developed by the famous Liviu Ionescu. The easiest way to get them installed into Eclipse is using the Eclipse Marketplace (menu Help > Eclipse Marketplace).

Eclipse Marketplace menu

Then install the Eclipse Embedded C/C++ plugin:

Eclipse Embedded C/C++ Plugin

After that, restart the IDE as asked at the end of the installation.

pyOCD Eclipse Settings

Remember that PATH thing earlier during pyOCD installation? I have to tell Eclipse where pyOCD is installed, because I did not want to clutter the global PATH. I recommend to set this up in the IDE using the global settings (Menu Window > Preferences):

pyOCD path and folder setting

If needed, this can be configured on a project or workspace level too. I prefer the above way to set it on an IDE level.

Eclipse Debug Launch Configuration

To debug a project in Eclipse, I need a launch configuration. As precondition, I have a project and built the binary (ELF/Dwarf) file successfully.

Below the steps to create a launch configuration for pyOCD in Eclipse.

First, select the project int the project explorer view and use the menu Run > Debug Configurations:

Select project and use Debug Configurations

Then double-click on the GDB PyOCD Debugging group:

double-click on GDB PyOCD Debugging

This creates a launch configuration with most fields correctly filled out, because I had selected that project in the first step:

I recommend saving the launch configuration file and settings in the project: That way it easily can be stored in a version control system like git.

Saving launch configuration as shared file

The most important settings are in the ‘Debugger’ Tab:

pyOCD Eclipse CDT Launch Configuration Settings

In the debug probe drop-down I can select any attached debug probe (P&E, CMSIS-DAP or J-Link):

Selection of debug probes

Tick ‘Override Target’ and select the target used (in my case the FRDM-K22F board):

Target Device Selection

Finally, press ‘Debug’.


The nice thing with pyOCD is, that without any special settings, it recognizes FreeRTOS.

Overall, debugging seems to work pretty well. With using semihosting there is some lagging.


I’m really glad that finally I have pyOCD working. This gives me yet another angle and debugging view in Eclipse. Compared to OpenOCD it is easier to setup, but comes with the dependency on Python and is ARM only. The pyOCD web site lists 70 ARM Cortex-M devices supported, far less what solutions support. Comparing pyOCD with OpenOCD: OpenOCD supports far more different devices and non-ARM ones, but is more complex and slower in my view, with OpenOCD as a ‘large open source community project’. pyOCD (driven by Chris Reed) on the other side seems to have more frequent updates and features added, for example RTT support added recently in v0.33.0.

But at the end, the best thing is that there are choices: pick what fits best your needs! And have at least three different hardware debug probes on your desk πŸ˜‰

Happy debugging πŸ™‚



19 thoughts on “Debugging Embedded Targets with pyOCD and Eclipse

  1. I’m wondering why you got the FreeRTOS view and I don’t… Does this view really has something to do with pyOCD or some CMSIS pack you installed? Or is it some lack of support for my RP2040? (BTW: multicore support for the RP2040 of gdb with pyOCD 034.3 or OpenOCD 0.12 is really bad).

    Something to add: instead of specifying the complete path of pyocd it should be enough if you are using “python -m pyocd”. python should know its way through its own configuration.


What do you think?

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.