ESP32 Debugging with JLINK

Introduction

Hello friends, I want to share with you my experience in debugging ESP32 using debuggers that implement the JTAG interface. This task seems trivial (and it is) when thinking about programming microcontrollers. But when I started working with ESP32 microcontrollers, I ran into a number of problems that I want to talk about and from which I want to save you.

Why, why, for whom is this article written?

• For whom? This article is written for those who want to get to know the ESP32 microcontrollers in depth, and for a deeper acquaintance, debugging through the terminal is definitely not enough for you.

• Why and why? I decided to write this article because I did not find a ready-made solution on the Internet, which would describe how to connect JLINK with ESP32.

  After reading documentation of the official manufacturer on the topic of debugging at the link, I proceeded to perform all the steps described, and ran into a problem – debugging refused to work. I spent a whole day and a lot of nerves before I figured out the problem. So I want to save your time.

Let’s start from the beginning

I decided to go through my journey with you from the very beginning, so that no one would have any questions. Let’s start with setting the task, I have an ESP32 DEVKITV1 debugging chamber and I want to start mastering this MK. To do this, I need a debugger and a loader. There is already a bootloader on this chip, this is the simplest USB-UART СP2102. As a debugger (it can also act as a loader) I will use JLINK, you can choose any of these list of supported programmers from the website of the official manufacturer.

Below I attach a photo of the debug board and the programmer.

Installing the IDE and the necessary software, debugging through the terminal, the first hello world

The manufacturer provides us with several ways to work with their microcontrollers, based on Arduino IDE, based on Eclipse and based on Visual Studio Code. I chose Eclipse because often worked there. Next, we have two options, install the IDE as an Eclipse plugin or use the installer. I tried to install the IDE as a plugin for Eclipse, but I couldn’t build OpenOCD (Open On-Chip Debugger) is an open source software for programming and debugging various hardware. It needs to be assembled via the command line, according to clumsy instructions, in general I do not recommend it (either my hands are crooked, or the documentation is not detailed enough). So, let’s go the simple way, we will use a ready-made installer.

Link to manufacturer’s documentation

Select the GetStardet->Introduction dialog and find link to installer. At the time of writing, this is an up-to-date link.

We select the item where we are offered to install an IDE with everything you need

Next, I recommend immediately creating a directory on your hard drive where the IDE and your workspace for projects will be located.

Personally, I created a directory in this way

C:/Soft

С:/Soft/workspace

Further, after downloading the installer, open it and select the directory we need for installation, namely C: / Soft and agree with everything (at the time of this writing, you could agree with everything 😊)

Further, our screen will look something like this, this is the IDE command line through which you can build the project, but we will use the graphical environment.

Go to the directory below (the version may differ) and find the file espressif-ide.exe

 C:\Soft\Espressif\tools\espressif-ide\2.8.1 

Next, we need to select the location of our workspace, select the pre-created directory

С:/Soft/workspace

Next, the IDE interface itself opens, let’s create a test project, or rather copy it, select File-> New-> Esspresife IDF Project

Let’s give a name to our project, for example Example, and click next

We tick the box that we want to use one of the examples and select hello world.

Next, we build the project by clicking on the build button and wait until the project is built.

Don’t be alarmed if Eclipse throws some errors after building, they are related to indexing, or the “r-code” of the example. After building the project, it’s a good idea to check if the controller and the project are working at all. We connect the board to the computer, select launch target: esp32, and select the desired COM port.

Let’s set up the terminal right away

Let’s take a closer look at the code in the example

void app_main(void)
{
    printf("Hello world!\n");

    /* Print chip information */
    esp_chip_info_t chip_info;
    uint32_t flash_size;
    esp_chip_info(&chip_info);
    printf("This is %s chip with %d CPU core(s), WiFi%s%s, ",
           CONFIG_IDF_TARGET,
           chip_info.cores,
           (chip_info.features & CHIP_FEATURE_BT) ? "/BT" : "",
           (chip_info.features & CHIP_FEATURE_BLE) ? "/BLE" : "");

    unsigned major_rev = chip_info.revision / 100;
    unsigned minor_rev = chip_info.revision % 100;
    printf("silicon revision v%d.%d, ", major_rev, minor_rev);
    if(esp_flash_get_size(NULL, &flash_size) != ESP_OK) {
        printf("Get flash size failed");
        return;
    }

    printf("%uMB %s flash\n", flash_size / (1024 * 1024),
           (chip_info.features & CHIP_FEATURE_EMB_FLASH) ? "embedded" : "external");

    printf("Minimum free heap size: %d bytes\n", esp_get_minimum_free_heap_size());

    for (int i = 10; i >= 0; i--) {
        printf("Restarting in %d seconds...\n", i);
        vTaskDelay(1000 / portTICK_PERIOD_MS);
    }
    printf("Restarting now.\n");
    fflush(stdout);
    esp_restart();
}

From the example, it is intuitively clear that the program should display information about its parameters and then reboot after 10 seconds.

Great, now we flash the controller, press RUN and open Terminal, there we should see the following

Now we have an understanding that the controller is operational. From the example, we learned that using the function printf() and term windows, you can debug the project. But what about step-by-step debugging, with breakpoints and the ability to monitor registers and variable values?

Debugging with JLINK

First you need to connect the debug board to the programmer, for this we find the right board on the manufacturer’s website

https://www.espressif.com/en/support/documents/technical-documents

and find the description of the pins, below is the connection diagram of the ESP32-WROOM-32 board

Next, we connect the corresponding pins on the board to the pins on JLINK.

ESP32	JLINK
3.3	VTref
GND	GND
D12	TDI
D14	TMS
D13	TCK
D15	TDO

Final result

Next, we need to tell the IDE that we want to work with the project in debug mode, for this we go to the launch configuration tab, and create a new configuration like ESP-IDF GDB OpenOCD Debugging

Next, we agree with the standard settings. Now let’s take a closer look at the config, for this we will go to the settings of the newly created config

We are interested in the Debug tab, commands are registered in the Config options dialog box, by default such commands are registered there

-s ${openocd_path}/share/openocd/scripts -f board/esp32-wrover-kit-1.8v.cfg

-s ${openocd_path}/share/openocd/scripts – directory path

-f board/esp32-wrover-kit-1.8v.cfg – script path

Now let’s see what the script does, go to the directory below (it may differ for you, because versions change)

C:\Soft\Espressif\tools\openocd-esp32\v0.11.0-esp32-20221026\openocd-esp32\share\openocd\scripts\board  

And find the file esp32-wrover-kit-1.8v.cfg

Inside it, the paths to the scripts are written, inside these scripts, the settings for the debugger from Expressive, you can find all these scripts and see what’s inside them. If you want to use a different sender, then you need to remove the default scripts and prescribe the ones you need, following the example from the standard ones. I will give an example for the JLINK debugger.

Here we see that the FTDI interest is selected by default, most likely it is the interface of their own programmer, we will comment out this line and add two commands instead, which will tell you that debugging will be done via the JTAG interface, the speed will be 1kHz. The configuration file should look like this:

# SPDX-License-Identifier: GPL-2.0-or-later
#
# Example OpenOCD configuration file for ESP32-WROVER-KIT board.
#
# For example, OpenOCD can be started for ESP32 debugging on
#
#   openocd -f board/esp32-wrover-kit-1.8v.cfg
#

transport select jtag
adapter speed 1000

# Source the JTAG interface configuration file
#source [find interface/ftdi/esp32_devkitj_v1.cfg]
set ESP32_FLASH_VOLTAGE 1.8
# Source the ESP32 configuration file
source [find target/esp32.cfg]

It remains only to add the type of debugger, for this we return one step back to Debug-> Config options, there instead of the line

s ${openocd_path}/share/openocd/scripts -f board/esp32-wrover-kit-1.8v.cfg

Let’s write

-s ${openocd_path}/share/openocd/scripts -c 'set ESP32_FLASH_VOLTAGE 1.8' -f interface/jlink.cfg -f board/esp32-wrover-kit-1.8v.cfg

This selects the debugging interface, JLINK.

The last step remains, download the UsbDriverTool program

https://visualgdb.com/UsbDriverTool/

Install it and with the JLINK adapter connected, change the JLINK drivers to (WinUsb)

Now everything is ready)

We press the DEBUG button, set a breakpoint and press Start, everything should work