I was planning to use the PlatformIO Debugger for quite some time:

I wanted to use it both with OS/X and Linux: Most tutorials however describe Windows and therefore were not helpful to resolve my issues.

It took me quite some time to have a working solution. Therefore I would like to document some additional steps and recommendation:

  • Please make sure that you start with the simplest example possible. I wanted to debug quite a complex big application and that’s a bad way to start!
  • Then set up and test the example w/o debugger first as a clean starting point. This was giving me e.g. the following platformio.ini on my PI
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 119200
upload_port = /dev/ttyUSB0


Here is the overview of my hardware

  • AI Thinker AudioKit (board with ESP32)
  • Raspberry PI – to run PlatformIO (Alternative 1)
  • McBook with OS/X – to run PlatformIO (Alternative 2)
  • ESP32-Prog (JTAG debugging device)

ESP32 / AI Thinker AudioKit

You can debug any ESP32 baord which has the JTAG pins available. The AudioKit has the advantage that it provides labelled JTAG pins. So connecting the device to the ESP Prog is straight forward. I also added the regular ESP32 Pin names in the table below if you want to use a regular EP32 board instead.

ESP Prog DevKit ESP32 JTAG Pin

Please double check your wiring since is one of the most frequent source of issues. I also recommend to keep the wires as short as possible.

The following AudioKit DIP switch settings were working for me

  • 1: OFF
  • 2: OFF
  • 3: OFF
  • 4: ON (MTCK)
  • 5: ON (MTDO)

Linux / Raspberry PI

In Linux you must install the udev-rules!
Therefore I was executing the following steps:

curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/master/scripts/99-platformio-udev.rules | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
sudo usermod -a -G dialout $USER
sudo usermod -a -G plugdev $USER
sudo reboot

Here is my final working platformio.ini with debugging support

platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 119200
upload_port = /dev/ttyUSB0

debug_tool = esp-prog
debug_init_break = tbreak setup

The debug_init_break makes sure that the debugger stops at the setup method. After this the debugger was working for me.


It seems that the OS/X FTDIUSBSerialDriver is causing that the debugging device is considered as two serial interfaces but this is not what we want. You can check this by executing ls /dev/tty.usbserial*. If you get additional ports with the ESP32-Prog plugged in, you have an issue.

Usually you will find the instruction to unload the driver:

  • Unloading the driver
sudo kextunload -v -c  com.apple.driver.AppleUSBFTDI
  • Checking that the driver has been unloaded
sudo kextstat | grep FTDI

I suggest to plug in the ESP32-Prog several times and then double check that the driver is still unloaded: However this was not working for me!

After some searching I found that ftdichip.com is providing a D2xxHelper which prevents the AppleUSBFTDI from loading: On the site just search for D2xxHelper.

So I installed the D2xxHelper driver and restarted the system: and indeed this resolved my issue.

Here is my final working platformio.ini with debugging support

platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
upload_port = /dev/tty.SLAB_USBtoUART

debug_tool = esp-prog
debug_init_break = tbreak setup

Adding additional Complexity

  • Now after having the basic debugging working I can start to deal with my complex main program for which I added my additional libraries and build flags to the platformio.ini:
lib_deps =  https://github.com/pschatzmann/arduino-audio-tools, https://github.com/pschatzmann/arduino-fdk-aac.git, https://github.com/pschatzmann/arduino-audiokit
lib_ldf_mode = deep+
  • Now my program was getting too big to fit into the available memory. So I needed to define a partition scheme:
board_build.partitions = huge_app.csv
  • But the debugger is failing now.
  • After some further research I found that my application was using some buttons which conflict with the Debug Pins. This functionality needs to be deactivated.
  • And finally the debugging is working successfully with my complex program as well…


Leave a Reply

Avatar placeholder

Your email address will not be published.