Advanced Microcontroller Debugging using the ESP-PROG
Developing hardware projects using microcontrollers and sensors presents a host of challenges. For one, the fact that we use a personal computer to interface with connected devices already adds a layer of separation from the machine we actually write code in. A similar situation is present in building distributed applications over networks. Albeit without the particularities of sensors and often on devices with a relative wealth of computing resources. So that seems like a first world problem when compared to the former.
In the case of microcontrollers working with concurrent real time data we are often left with fairly inadequate methods of diagnosing behavior. I’m referring to going beyond the use of serial print / log statements and using true software and hardware debugging. The seasoned developers among you already use debuggers with the ability to set breakpoints and introspect memory and variables. Certainly, this form of debugging is considered modern when compared to the former approach. So perhaps I should have named this post Modern Microcontroller debugging. But to the community of makers coming from development on the Arduino platform the use of what we’ll cover in this post is most definitely advanced by comparison.
In this post we’ll look at debugging code on the ESP32 microcontroller using the ESP-PROG hardware debugger, both of which were created by Espressif Systems. We’ll also focus on the use of the PlatformIO IDE running on Visual Studio Code. While the information contained in this post will allow you to debug on other microcontrollers we’ll focus on the ESP32 for two reasons:
- We need an actual MCU for practical discussion.
- The ESP32 is the MCU I’m using in my own work. The actual board we’ll use is the Adafruit Hazzah32 which features the Espressif ESP32-WROOM-32 MCU.
All too often articles like this are written where the reader is unclear what motive the author had in sharing the post. In an earlier life, my work featured the use of X86 assembler language and hardware debuggers such as the early SoftIce in the early 90s. Along the way I’ve used C/C++ debuggers from GDB to the Microsoft C IDE version 1.x and beyond. So basically low-level debugging is what I’ve come to expect from the programming tools I’ve used. My current work focuses on IoT devices in the emerging Internet of Bodies (IoB) and Internet of Sports (IoS) platforms in the Health, Fitness and Wellness space. Also, the IoT devices I build communicate with cloud-hosted microservices. So given the overall end-to-end complexity — there’s serious incentive to go as low as one needs to while debugging. I wrote this post to share my own experience in getting this to work.
Ok, with all that out of the way let’s dive right in.
The ESP-Prog board
The ESP-Prog is a development and debugging tool which connects to your machine (PC/Laptop) and an ESP32 board to fully control it. By control, I mean that you step through program code using your laptop (running PlatformIO) and use it to send commands to the ESP-Prog board which in turn controls the execution of code running on the ESP32. This all happens over USB to the ESP-Prog and over a few wires from the ESP-Prog to the ESP32 board. We’ll take a closer look at this wiring in just a bit.
I was working with the ESP8266 and ESP32 for a few weeks before I encountered Andreas Spiess’s YouTube channel and video introducing Inline Debugging for ESP32 Andreas discussed two hardware devices for inline debugging, the Olimex ARM-USB-OCD and the Espressif ESP-Prog board. The ESP-Prog was both cheaper and specifically designed by Espressif — so it was the obvious choice. I purchased a board from Digi-Key for just $13 bucks.
Upon closer examination we can see that there are a number of interesting components on the ESP-Prog board. On the left we see that there’s a Micro USB connection where you’ll connect to your PC or Laptop. There are also buttons for manually booting and resetting the device. Just to the right of the USB connector is a USB Bridge chip. That’s the chip that converts USB to serial data. This is necessary because the interface from the ESP-Prog to the ESP32 board is over serial communication using the UART interface for transmit and receive.
On the lower right we see the JTAG 2.54 mm connector. We’ll use those pins to wire up the ESP32.
You might be wondering what this JTAG thing is anyway? JTAG is an industry standard for working with circuit boards. It’s essentially a method of interfacing hardware for the purpose of testing. JTAG itself stands for the Joint Test Action Group which created the standard that was later codified by the IEEE in 1990 in a standard entitled “Standard Test Access Port and Boundary-Scan Architecture”. You can find out more about JTAG here https://en.wikipedia.org/wiki/JTAG
If we rotate the JTAG 2.54 mm connector clockwise we can see the following pin arrangement.
We’ll only use six of the ten pins: 1, 2, 3, 4, 6, 8
Wiring
As is common for me in these sort of projects, I tend to create visual aids to ensure I get the wiring right. Despite this extra care, I’d be lying if I told you that doing this has prevented me from having fried a board or two.
This table maps pins on the Adafruit Huzzah32 to the ESP-PROG using colored wires.
On the bottom of the Huzzah32 we see the pin labelling which I’ve colored to match the wiring we’ll use.
Here is the actual wiring on a broad board. I added an OLED display as an extra debugging tool. We’ll step through the OLED display driver code later in this post.
This Fritzing diagram below should clarify the wiring. The female header on the left represents the JTAG 2.54 mm connection we discussed earlier. The labels on the Huzzah32 might seem a bit misleading but they’re correct.
Now for the software setup
Once we have the wiring complete we’ll need to ensure we have the correct USB drivers installed on our development machine.
USB drivers
The ESP-Prog features a USB Bridge Controller chip provided by FTDI. So we’ll need to install FT2232HL (VCP) Virtual COM Port driver.
TODO Summarize this section: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#321-the-working-mode-of-usb-bridge
I’m using a Mac so I had to install the Mac OS X 10.9 and above version of the driver.
* USB drivers for the ESP-Proj
* problems on Mac
sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriverPlatformIO and Visual Studio Code
I used the Arduino IDE for years despite the degree to which it’s lacking in as a modern IDE. My dislike of the Eclipse IDE kept it from ever being a viable alternative. Fortunately, I learned a while back that I could use my editor of choice, Visual Studio Code with an add-on called PlatformIO. The resulting combination forms a world class tool for working with microcontrollers! And as my best friend would say: “and the price is right — Free!”.
There are lots of getting started with Visual Studio Code tutorials so I won’t spend time on that in this article. However, you can download Visual Studio Code for free and proceed to watch some YouTube videos.
Once you have Visual Studio Code installed you can easily add the free PlatformIO add-on using the instructions provided on the PlatformIO website. Here again, you’ll find lots of great PlatformIO tutorials on YouTube.
Using PlatformIO
After installing Visual Studio Code and PlatformIO we’ll need to configure the libraries we’ll need in order to work with ESP32 boards.
TODO Add configuration screens
Debugging
With the ESP-Prog wired and connected to an ESP32 board, we’re able to load a sample program and try advanced debugging.
serial.serialutil.SerialException: [Errno 16] could not open port /dev/cu.usbserial-14100: [Errno 16] Resource busy: '/dev/cu.usbserial-14100'TODO Show stepping through code screenshots
TODO Show a cleaner version of the project using custom cables
