Debugging is a very powerful tool. I was fortunate enough to get a debugger setup on the first attempt for my ESP32 project. However, it seems every time I go back to revisit ESP32 designs things have changed and or I forget what I had done to get the debugger working. I’m creating this post to save how my notes on how to setup the debugger for Platform IO.
ESP-Prog Board for debugging
You’ll need this little JTAG interface. I think there are others but this is the one I got working and I’ve stuck with it. The ESP-Prog board is a interface put together by Espressif the maker of ESP32 microcontrollers. This little board provides a JTAG interface through which you can perform inline debugging.
Link to Espressif ESP-Prog Board
You can also program your ESP32 microcontrollers through the board though I’ve not investigated how to do that yet.
Visual Code with Platform IO Plugin
Visual Code is a highly advance text editor designed for coders and distributed by Microsoft. It allows for easy searching of code. I use it to quickly find definitions and declarations in code. This makes for quick work of coding.
Platform IO links toolsets for various embedded development frameworks (e.g. processors) and various frameworks (libraries, e.g. Arduino) into the visual code editor including debugging.
I assume you’ve successfully installed Visual Code and Platform IO as well as written your first program in the tool set.
Installing ESP-Prog Drivers
For this example I’m using a PC with Windows 10 on it.
Connect the ESP-Prog to your PC via USB cable. Using the link below install the latest FTDI driver (this is the chip the board is based on) from website below. Specifically the FT2232HL Chip:
Link to FTDI Driver Page with FT2232HL
Note: It’s a little annoying but at time of install the executable installer for driver was on right hand side of table in their website. Otherwise, the other links are to perform a manual driver install.
I’m a little confused by this next step but rest assured it’s necessary. You need to download a program, linked below, called Zadig and remap the driver you just installed.
Once installed you’ll make sure you’re ESP-Prog board is plugged in.
- Launch Zadig,
- Click Options->”List all devices”
- Select “Dual RS232-HS (Interface 0)” from dropdown.
- Then click button “Replace Driver”
- Close the application
- Unplug and plug back in the ESP-Prog
Caution: if you plug the ESP-Prog into a different USB port on your computer you may need to repeat this step with Zadig.
Connecting ESP-Prog to ESP32
For this example I used a ESP32-WROOM on a SparkFun Thing Plus breakout board. These boards are AWESOME for wiring up quick prototypes.
Link to Sparkfun ThingPlus – ESP32 WROOM
ESP-Prog Jumpers: Make sure you’ve got jumper set to 3.3V by default this is how my board came.
Connecting ESP-Prog to ESP32-WROOM: You need to establish a JTAG connection from the ESP-Prog to the ESP32 chip. This requires you connect several GPIO Ports on the ESP32 to the ESP-Prog Board:
| Net | ESP-PROG | ESP32-WROOM |
| TMS | JTAG PIN2 | GPIO14 |
| TCK | JTAG PIN4 | GPIO13 |
| TDO | JTAG PIN6 | GPIO15 |
| TDI | JTAG PIN8 | GPIO12 |
| Vcc (3.3V) | JTAG Pin 1 | 3.3V |
| GND | JTAG Pin 3 | GND |
Note: Espressif was kind enough to silkscreen labels onto the PCB for above nets. Pins 5, 7, & 9 are also ground but I only connected Pin 3 to ground and it worked. Pin 10 is not connected / not used.
Troubleshooting
Platform IO is a web of various toolsets. It’s lightyears ahead of what I’ve utilized in the past but certainly not without it’s share of challenges. The software auto configures compilers, libraries, etc for your project. This is nice until it doesn’t work as expected. When it goes wrong you can spend DAYS trying to figure out what happened to no avail.
Only ONE project per workspace
Visual Code seems to provide ability to have multiple code spaces per workspace. To keep it simple stupid, make sure you only have ONE code project in your workspace. That is, you have to close visual studio and open it again for each program you’re writing. Otherwise, the auto generated files in Platoform IO get easily confused, that and or I’m getting confused.
Check all the terminal output tabs for errors
There’s multiple Next you have to be extremely diligent about checking all the tabs at the bottom of the window (Problems, Output, Debug Console, Terminal, Ports). You’ll find hidden information in there as to why the process you’re trying to execute failed. Sometimes this information will be highlighted (different color text) sometimes not. Look through it carefully.
You’re not alone
I’ve spent days searching the internet for solutions to challenges I face in Platform IO. You may copy and paste these errors you find into a search engine but in my experience it comes down to lots of trial and error. I’ve had little luck getting resolution from Forums as well.
That said, realize you’re not the only one facing these challenges. I’d like to throw my hands up and move on but then realize, what a blessing Platform IO and Visual Studio Code are. Prior to these tools it took just as long to code if not longer.
Code must reside on your local machine
I have a network attached storage where I store all my projects. It seems Platform IO has gotten confused a time or two when I create a project with that network path. To keep it simple and not push my luck, I’ve mirrored those projects on the local machine where I’m developing.
Leave a Reply