Advanced Debug

While Espruino can be compiled and debugged on a Host PC, sometimes you'll need to be able to debug the hardware itself. You can do this using SWD pins and an ST-Link device.

We'd suggest using an STM32DISCOVERY board (not the VLDISCOVERY).

Make sure you disconnect the two ST-LINK jumpers first, then connect as detailed below. You can then use a normal debugger such as st-link on linux.

Original Espruino Board

Connect wires onto the 6 pin SWD connector as follows:

Pin No. F3/F4 Discovery Pin Espruino Pin
1 VDD Target

Espruino Pico

The Six SWD connections are available on six circular pads on the back of the Pico. Pin one is unmarked, but is nearest the USB connector.

You only actually need to connect pins 2,3 and 4 - but you can connect more if you want to.


  • You'll need to remove USE_BOOTLOADER=1 from the Makefile (under else ifdef ESPRUINO_1V3), and 'bootloader' : 1, from or
  • You'll want to make with DEBUG=1 in order to save the relevant debug info into the binary.
  • You may also want to remove USE_NET, USE_GRAPHICS, USE_FILESYSTEM and whatever you're not interested in, to ensure that the binary (with debug info) fits in available flash
  • (Non-Pico) You may also need to unsolder LED1 and LED2 (or their resistors), as these use the (usually useless!) SWD debug pins
  • (Non-Pico) You need to edit targets/stm32/jshardware.c, remove the line containing GPIO_Remap_SWJ_Disable
  • (Non-Pico) Initially won't be able to flash Espruino. This is because the SWD pins are disabled and used for status LEDs. You'll need to connect BOOT0 to 3.3v and tap reset, which stops Espruino itself booting and reclaiming the SWD pins.
  • When trying to debug, you may find that your PC doesn't recognise the Espruino as a USB device. To solve this, power the Espruino up without USB and start the debugger. Then plug into USB when the firmware is actually running.

Phew. Finally (if you have the st-link tools installed and on your path), you can flash Espruino, with:

DEBUG=1 ESPRUINO_1V3=1 make flash
# or
DEBUG=1 PICO_1V3=1 make flash

You can then debug by running:


in one window, and:

DEBUG=1 ESPRUINO_1V3=1 make gdb
DEBUG=1 PICO_1V3=1 make gdb

in the other.

There are some useful functions defined in .gdinit if you plan on debugging the interpreter - but if you're doing that we'd strongly suggest you try and debug a normal Linux executable of Espruino first, and only move onto actual hardware if you can't fix the problem there.

This page is auto-generated from GitHub. If you see any mistakes or have suggestions, please let us know.