instructables

How to Use a Debugger on an ESP32

by witnessmenow

Have you ever wanted to take a peek inside your code to see why it's behaving the way it is? Traditionally in ESP32
projects, you would have had to add endless print statement to try gure out what was going on, but there is a
better way!

A debugger is a way of seeing what is happening at particular sections of your code and to try out di erent variable
values without re-compiling your code, usually this is not something available to us on embedded projects, but in
this guide I will show you how to use it on an ESP32.

In this guide I'll show you to setup the hardware, setup the software and show a simple example of using the
debugger.

Supplies:

ESP-Prog - This is the board needed for debugging

Exact one I bought*
$5 Cheaper one, but I have not tested it*

An ESP32 that breaks out pin 12,13,14,15

Adafruit Feather Huzzah32
D1 Mini ESP32*

[OPTIONAL] Debug Shield I sell on Tindie

Feather Huzzah32
D1 Mini ESP32

* = A liate Link

How to Use a Debugger on an ESP32: Page 1

Step 1: Check Out the Video!

I have a video on this topic if you want to check it out.

On my channel I usually make ESP8266 and ESP32 based videos, so if you are interested in those, please check it
out!

https://youtu.be/TivyIFF-dzw

Step 2: Hardware - Parts & Wiring

How to Use a Debugger on an ESP32: Page 2

To use the debugger you only need an ESP-Prog and Please note that you can use the JTAG pins in your
almost any ESP32 board (links to these in an earlier sketch with the debugger, for example the built-in
step) LED of the Huzzah32 board is on pin 13, so you can
not use it while debugging.
ES P- Pro g :
W iring :

The ESP-Prog is a board designed by espressif, the

makers of the ESP32 and ESP8266 chips. It connects to To connect the ESP-Prog to the ESP32, just use the
JTAG pins of the ESP32 to allow us to use the wiring guide as provided in the picture above. Check
debugger.It can also be used for programming ESP32 with the wiring diagramof your ESP32 board if you
boards, but I won't be covering that here. don't immediately see the appropriate pins as
sometimes they use a di erent naming scheme.

De bug Shie lds :

These are optional, but I sell some shields on Tindie

ES P32 B o a rd: for the Huzzah32 and the D1 Mini 32 that make
connecting the ESP-Prog really simple, it breaks out
You can use basically any ESP32 board for this once it the appropriate pins to an IDC connector that you can
breaks out the JTAG pins, which are 12, 13, 14 & 15. I've use a ribbon cable to connect directly between the
tested both an Adafruit feather Huzzah32 and a D1 shield and the ESP-Prog
Mini 32 board and they both worked ne.

Step 3: Hardware - Driver Setup

How to Use a Debugger on an ESP32: Page 3
In order to use the ESP-prog for debugging, we need to install the appropriate drivers for it. PlatformIO provides
some steps for that here, but I will go through the Windows steps in this guide.

1. Download and install the FTDI drivers for the ESP-Prog from here, scroll to the right to download the
"setup executable" version to make it easier.
2. Download and install the tool Zadig from here, this allows us to install a generic driver needed for
debugging.
3. With the ESP-Prog plugged in, open Zadig
4. In the Zadig application, under "Options", click "List All Devices"
5. The drop down in Zadig will now be populated, select the "Dual RS232-HS (Interface 0)" option. Make
sure it's interface 0 you select!
6. To the right of the green arrow, "WinUSB" should be selected, then click "Replace Driver"

When that is nished your drivers should be setup for use!

Note: If you change the USB port you are using for the ESP-Prog, you may have to repeat steps 3-6 again. If you get
an error as shown in the picture above when debugging, you need to repeat the steps.

1. Step 2: Download Zadig

1
1

1. Step 4: Make sure to select Interface 0! 1. Step 6: With "WinUSB" selected, click "Replace Driver"

How to Use a Debugger on an ESP32: Page 4

 1

1. If you see this error, repeat steps 3-6

Step 4: Software: Installing PlatformIO

PlatformIO is a IDE for developing with various di erent embedded frameworks, including the Arduino eco-system.
It is more complicated to use than something like the Arduino IDE, but it is very powerful and has some features
that the Arduino IDE sorely misses, such as auto-complete.

It is required to PlatformIO to use the debugger. If you are already familiar with PlatformIO, feel free to skip ahead
a couple of steps.

Download and install Visual Studio Code (VS Code) from the link provided on the PlatformIO.org
website
Open VS Code, and open the extensions menu, the button is highlighted in the picture above
Type "platformio" into the search, select it and click install.

How to Use a Debugger on an ESP32: Page 5

Step 5: Software: Using PlatformIO

Using PlatformIO is a little bit di erent than using the Arudino IDE, so in this step we'll just cover the basics of
getting an example running on a board.

O pe ning An Exa m ple :

1. Click the Home button on the PlatformIO toolbar (As shown in the picture)
2. Click "Project Examples" button
3. Select the "Arduino-blink" example under the Espressif 32 section

This will open a sample blink project. The layout of a PlatformIO is pretty di erent compared to an Arduino project,
so let's go through the basics.

W he re is t he co de ?

The code for your project will be stored in the "src" folder, for the blink example you will see a "blink.cpp" le, this
le is the same as your sketch le (.ino) in an Arduino project.

Ho w t o I co n g ure m y bo a rd?

Con gurations for your project are kept inside a "platformio.ini" le in your project. This is actually one of my
favorite things about PlatformIO compared to the Arduino IDE, it never made sense to me that board settings were
not tied to sketches.

The example .ini contains de nitions for multiple di erent boards, but to keep things simple let's delete the bottom
two de nitions.

W he re do I s e t m y CO M po rt ?

PlatformIO will actually automatically try to nd the correct COM port to use, so you can actually get away with not
setting anything for this. But if you have multiple COM ports, which you will when using the debugger, I think it

How to Use a Debugger on an ESP32: Page 6

makes sense to set the speci c one you need.

You can see the di erent devices you have by clicking the "Devices" section in the home tab, and you can set which
one your ESP32 is in the "platformio.ini" by adding a "upload_port" con guration.

Ho w do I uplo a d m y co de ?

Click on the Upload button (icon is an arrow pointing right) and it should compile and upload the code. You should
now have a blinking LED on your board.

1
1. This is the Home button, this will bring up the PlatformIO home screen 1. This is a list of example projects

1. This is a basic blink example for the ESP32 1. What would normally be in your Arduino sketch is stored in the "src"
folder

How to Use a Debugger on an ESP32: Page 7

 1

1. To keep things simple, delete all but the top definition. 1. Click this button to see a list of connected COM ports

1
1. This configuration in platformio.ini says which COM port your ESP32 is 1. This button uploads the code to your board
on

Step 6: Debugging: Potential Banana Skin!

This is something that caught me out when I was preparing this and will hopefully be xed by the time you try it,
but I thought it was important to leave here.

At the time of making this guide, the latest version of PlatformIO is 4.3.0 and it has a bug that relates to being able
to debug. Thankfully we can update to the latest development version pretty easily which solves the problem.

Check on the Home page the version of PlatformIO core, if it is "4.3.0", perform the following steps.

1. On the PlatformIO toolbar, click the terminal icon

2. In the terminal type: pio upg ra de - - de v
3. RestartVS code and PlatfromIO should be updated

How to Use a Debugger on an ESP32: Page 8

Step 7: Debugging: Configuration

We need edit the "PlatofrmIO.ini" le to enable de bug _init _bre a k = t bre a k s e t up

debugging, we only need to add two things to it.

de bug _t o o l = e s p- pro g This is a trick we learned from Andress Spiess' video on

debugging on the ESP32. It tells the debugger to stop
in the setup of our application.
This sets the debug tool we are using.

How to Use a Debugger on an ESP32: Page 9

Step 8: Debugging: Starting Debugging

Before we get into it, we will make a minor change to the sketch that will make it easier to demonstrate what you
can do with the debugging.

1. Create a new variable , "int delayTime = 1000;" outside of any methods, this will make it a global
variable.
2. Replace the number inside the delay calls in the loop with this new variable: de la y (de la yT im e );

Upload the code to the board once more, then to start debugging, in the toolbar, click "Run" then "Start
Debugging"

You will see the things moving in the terminal window, but even when that states that it was success, if you click on
the "Debug Console" you will see it is still working way, it will take a few seconds to nish.

If everything went as expected you will see the debugger stop at the start of the setup.

Step 9: Debugging: Basic Usage

How to Use a Debugger on an ESP32: Page 10

Let's cover some of the basics of what you can do with on the + icon, then just type in the name of the
the debugger variable. As a demo, type in the variable we added in
the previous step "delayTime"
Cre a t ing Bre a kpo int s :
Va ria ble Vie w e r:
A breakpoint is a point of your code where you want
the debugger to stop. To create a breakpoint click to You can also see all the variables and their values that
the left of the line number. As demo, add breakpoint are available at your current breakpoint. To demo this,
to the rst line in the loop method. If you look in the "Global" section you should nd the
"delayTime" variable.
Bre a kpo int Na v ig a t io n:
Edit ing t he Va lue o f Va ria ble s :
To move between breakpoint or move to the next line
of code, you can use the tools that will appear on the You can also edit the values of variables and it will
top of the screen. Press the "continue" button (looks take immediate e ect on your codes behaviour. To
like a play button) to move the breakpoint we just demonstrate this, click on the delayTime variable in
created inside the loop. the Variable Viewer section, and change the value to
"100". To show this working, disable the breakpoint
Va ria ble W a t che s : inside the loop by clicking to the left of the line
number again. Press the continue button on the
Variable watches let you monitor the value of breakpoint navigation bar. The LED on your ESP32
variables when the debugger is stopped at a should now be blinking much faster than before.
breakpoint. To add a new variable watch you can click

1. Click to the left of the line number to add a breakpoint 1. Continue to the next breakpoint

1. Click the icon to add a new variable watch

How to Use a Debugger on an ESP32: Page 11

 1

1. List of the variable categories available to look into 1. Changing the value of the variable will impact the code in real time (i.e.
without re-uploading it)

1. Disable the breakpoint by clicking on it again.

Step 10: Troubleshooting

I found during my testing, that some times I couldn't upload to the ESP32 while it was connected to the ESP-prog,
and I couldn't gure out a pattern to why this happened, because most of the time I could upload without any
problems. I found I could just disconnect the ESP32 and the ESP-Prog, upload the code to the ESP32 and then
reconnect them and it would work ne.

How to Use a Debugger on an ESP32: Page 12

Step 11: Conclussion

I think this is a really cool tool to add to toolbox to I would also like to give a huge thanks to my Github
help gure out what is going on inside your project. Sponsors who help support what I do, I really do
appreciate it. If you don’t know, Github are matching
I'd love to hear if you nd this useful!. Please let me sponsorships for the rst year, so if you make a
know in the comments below, or join me and a bunch sponsorship they will match it 100% for the next few
of other makers on my Discord server, where we can months. Thanks for reading!
discuss this topic or any other maker related one you
have, people are really helpful there so it’s a great
place to hang out.

How to Use a Debugger on an ESP32: Page 13