These instructions are for more advanced debugging methods with external hardware and software and not routine CircuitPython code issues.

Print Debugging

The easiest way to debug is by adding print statements into the CircuitPython C code and viewing the output over UART. UART is a serial connection that is available earlier than serial over USB and tends to be more reliable as well.

#include "runtime.h"


// Acts like printf.
mp_printf(&mp_plat_print, "hello %d\n", 10);

The broadcom builds have the DEBUG UART enabled by default on the default RX and TX pins in the 40 pin header. Connect a USB to Serial converter to view the debug output.

One can also send serial input to CircuitPython over this connection.


It is also possible to connect to the CPUs over GDB via openocd. See the GDB guide for installation and usage details.

The broadcom-peripherals library includes configuration files for openocd. Here is an example command to run from ports/broadcom from within the CircuitPython repo that uses a JLink to talk to the Pi.

openocd -d -f interface/jlink.cfg -f peripherals/openocd/bcm2835.cfg

Then, within GDB do this to connect to OpenOCD:

tar ext :3333

This guide was first published on Jan 12, 2022. It was last updated on Mar 08, 2024.

This page (Debug) was last updated on Mar 08, 2024.

Text editor powered by tinymce.