PlatformIO & Remote Debugging

Introduction

This post covers getting PlatformIO remote debugging working, without using their remote debugging feature.

Recently while working on a customer project containing a GPS module and satellite modem I suddenly had the need to be working outside. Rather than relocating my desk to the garden, I decided to look for a means of remotely flashing, debugging and monitoring the board I was working on.

The PlatformIO ecosystem includes a neat feature, supporting working with devices remotely. PlatformIO Remote Development Solution supports remote firmware upload and remote serial monitoring. Making use of a small cross-platform agent to interface a development board with the internet and your IDE in a secure manner.

I setup the agent on a Wi-Fi connected Raspberry Pi, signed up for a free account and gave it a try. Like most things PlatformIO related it worked without any major drama. One thing it was missing though, which I was ideally after is remote debugging. While a remote serial monitor is a start, single stepping, breakpoints and variable inspection was the goal.

Remote GDB

My first thought was under the hood when debugging with PlatformIO I’m interacting with GDB. GDB supports remote debugging and the GDB server in use by PlatformIO, OpenOCD also supports remote debugging. Rather than run both processes locally, I should be able to have PlatformIO run GDB locally, while running OpenOCD on a remote machine. In this case the Raspberry Pi I already have hooked up on the garden.

Combining this with my previous work on getting a trace output working via ARM’s ITM and SWO modules I should be in business.

Turns out it’s pretty straightforward to configure PlatformIO for remote debugging by adding the following to platformio.ini on the local machine:

# IP of remote machine hosting OpenOCD
board_build.opencocd_host = 192.168.1.42

# Remote debugging
debug_tool = custom
debug_port = ${this.board_build.opencocd_host}:3333
debug_server =

# Remote trace output (via ITM)
monitor_port = socket://${this.board_build.opencocd_host}:6464

On the remote machine, with an ST-Link programmer connected, its then a case of installing and launching an instance of OpenOCD.

For this I installed a binary distribution of OpenOCD from xPack, having had a few issues with the Debian version and my programmer.

With xPack’s OpenOCD installed in “~/.local/xPacks/openocd”, as suggested by their install guide we can launch an OpenOCD session.

Assuming the version of OpenOCD installed is “0.11.0-5”:

~/.local/xPacks/openocd/xpack-openocd-0.11.0-5/bin/openocd -s ~/.local/xPacks/openocd/xpack-openocd-0.11.0-5/scripts -c "bindto 0.0.0.0" -f interface/stlink.cfg -c "transport select hla_swd" -f target/stm32f1x.cfg -c "reset_config none"

Note the above command line is specific to an STM32F1x MCU being debugged by an ST-Link debug probe and will need adapting for other combinations of probe / microcontroller.

Once OpenOCD is up and running, it becomes a simple case of starting a debug session followed by a monitoring session in PlatformIO as usual.

The updates described above have been applied to the PlatformIO project I developed for my previous post PlatformIO & ARM’s ITM/SWO (Serial Wire Viewer). These can be found on the branch “remote_debug” within the repository on GitHub.