Eclipse JTAG Debugging the ESP32 with a SEGGER J-Link

When Espressif released in 2014 their first WiFi ESP8266 transceiver, they took over at least the hobby market with their inexpensive wireless devices. Yet again, the successor ESP32 device is used in many projects. Rightfully there are many other industrial Wi-Fi solutions, but Espressif opened up the door for Wi-Fi in many low cost projects. Many projects use the ESP devices in an Arduino environment which basically means decent debugging except using printf() style which is … hmmm … better than nothing.

What is maybe not known to many ESP32 users: there *is* actually a way to use JTAG with the ESP32 devices :-). It requires some extra tools and setup, but with I have a decent Eclipse based way to debug the code. And this is what this article is about: how to use a SEGGER J-Link with Eclipse and OpenOCD for JTAG debugging the ESP32.

Roboter with ESP32 and JTAG Debug Port

Robot with ESP32 and JTAG Debug Port

Using that approach, I have the power of Eclipse and can debug my NXP Kinetis in real-time together with the Wi-Fi part, even with multiple cores and FreeRTOS :-).

ESP32 debugging with FreeRTOS

ESP32 debugging with FreeRTOS

J-Link

I’m using in this article the SEGGER J-Link for debugging. Simply because the J-Link probes are available on most developers desk and I’m using them in many of my projects, and their EDU line is affordable for students or hobbyists. Otherwise there are other solutions available using FT2232 USB-2-Serial breakout boards, for example the http://dangerousprototypes.com/docs/FT2232_breakout_board.

JTAG Connection

You have to consult the data sheet of your ESP32 device or module to identify the JTAG pins. For the ESP32 Pico-D4 which is on the TTGO Micro-32 module (see “Programming the ESP32 with an ARM Cortex-M USB CDC Gateway“) it is on the following pins:

  • IO12: JTAG TDI
  • IO13: JTAG TCK
  • IO14: JTAG TMS
  • IO15: JTAG TDO
  • RST/EN: JTAG Reset
  • 3.3V: VTref

Below the needed pins available on the TTGO breakout module:

esp32_jtag

esp32_jtag

The needed pins are available on a 2×15 JTAG header:

2x10 JTAG Pins

2×10 JTAG Pins (adapted from SEGGER.com)

One way is to use jumper wires to connect the probe with the board:

Debugging ESP32 with J-Link

Debugging ESP32 with J-Link

Below with the wires annotated:

JTAG Signals to ESP32

JTAG Signals to ESP32

A good idea is to use a JTAG Adapter board, e.g. the one from Adafruit. That way I can connect with the smaller 2×5 pin standard JTAG/SWD cable:

Debug Connection with Adafruit JTAG Adapter Board

Debug Connection with Adafruit JTAG Adapter Board

💡 The ESP32 is *not* officially supported by SEGGER. It is important to mention that in my setup it worked very well using a J-Link EDU or a J-Link Pro (the ‘big’ probe in the plastic enclosure). It did *not* work with a J-Link EDU mini (not really sure why?).

Using jumper wires is working (but painful): I recommend when designing a ESP32 board to route the JTAG pins to a standard 2×5 header: that way connection with a debug probe is much easier: this is what we did for our ESP32 board which is used on our robot in combination with a NXP K22FX512 microcontroller:

Roboter with ESP32 and JTAG Debug Port

Robot with ESP32 and JTAG Debug Port

Below is how make a debug connection with the TTGO Micro-32 ESP32 module:

TTGO Micro-32 JTAG Connection

TTGO Micro-32 JTAG Connection

Software and Tools

I recommend using OpenOCD with Eclipse/GDB for debugging: this is free of charge and easy to set up. If you already have setup the toolchain for the ESP32, it already comes with GDB and OpenOCD. Otherwise see https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html#setup-of-openocd

You should be able to use any Eclipse distribution. I’m using in this article the NXP MCUXpresso IDE because the ESP32 is used in combination with the NXP K22FX512 microcontroller.

USB Driver Tool

Dealing with USB drivers for OpenOCD can be a pain, especially on Windows. The SysProgs USB Driver Tool from simplifies this a lot:

  • Download the tool from https://visualgdb.com/UsbDriverTool/ and install it (actually it simply unzips the files to a folder of your choice)
  • Run the tool

    usb driver tool

    usb driver tool

  • With the J-Link connected to the system, you should see a J-Link Driver
  • Install the WinUSB driver for it:Install WinUSB

💡 Keep in mind that with this it is not a ‘normal’ J-Link anymore, so cannot be used as such. To restore the original J-Link driver, use the restore menu:restore original driver

OpenOCD Configuration

I’m going to use the esp-wroom-32.cfg board configuration file.

esp-wroom-32.cfg

esp-wroom-32.cfg

The default OpenOCD configuration uses a JTAG speed too high. Edit the configuration file and change the speed to 1000 kHz:

adapter_khz 1000
esp-wroom-32.cfg

esp-wroom-32.cfg

Flashing with OpenOCD

Instead using the serial bootloader (see “Programming the ESP32 with an ARM Cortex-M USB CDC Gateway“), I can use OpenOCD to program the ESP32 through JTAG:

c:\esp\openocd-esp32\bin\openocd.exe -f interface/jlink.cfg -f board/esp-wroom-32.cfg -c "program_esp32 build/hello-world.bin 0x10000 verify exit"

This flashes the given binary (note the forward slashes!) at the given offset, performs a verify and then exits OpenOCD. Below an example output:

Open On-Chip Debugger  v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
adapter speed: 1000 kHz
Info : Configured 2 cores
esp32 interrupt mask on
Info : J-Link V9 compiled Oct 25 2018 11:46:07
Info : Hardware version: 9.10
Info : VTarget = 3.293 V
Info : clock speed 1000 kHz
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : Target halted. PRO_CPU: PC=0x40000400 (active)    APP_CPU: PC=0x40000400
Info : Listening on port 3333 for gdb connections
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32: Debug controller 0 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core 0 was reset (pwrstat=0x5F, after clear 0x0F).
Info : Target halted. PRO_CPU: PC=0x5000004B (active)    APP_CPU: PC=0x00000000
Info : esp32: Core 0 was reset (pwrstat=0x1F, after clear 0x0F).
Info : esp32: Debug controller 1 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core 1 was reset (pwrstat=0x5F, after clear 0x0F).
Info : Target halted. PRO_CPU: PC=0x40000400 (active)    APP_CPU: PC=0x40000400
** Programming Started **
auto erase enabled
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40000400
Info : Flash mapping 0: 0x10020 -> 0x3f400020, 84 KB
Info : Flash mapping 1: 0x30018 -> 0x400d0018, 422 KB
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40000400
Info : Auto-detected flash size 4096 KB
Info : Using flash size 4096 KB
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40000400
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40000400
wrote 602112 bytes from file build/hello-world.bin in 23.465628s (25.058 KiB/s)
** Programming Finished **
** Verify Started **
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40000400
read 599168 bytes from file build/hello-world.bin and flash bank 0 at offset 0x00010000 in 16.135042s (36.264 KiB/s)
contents match
** Verified OK **
shutdown command invoked
Warn : Flash driver of esp32.flash does not support free_driver_priv()
Warn : Flash driver of irom does not support free_driver_priv()
Warn : Flash driver of drom does not support free_driver_priv()

OpenOCD GDB Server

We are going to use a GDB client-server connection with the server already running.

From a DOS prompt launch OpenOCD with the following command:

c:\esp\openocd-esp32\bin\openocd.exe -f interface/jlink.cfg -f board/esp-wroom-32.cfg

The output should be something like this:

Working ESP32 J-Link Connection

Working ESP32 J-Link Connection

Open On-Chip Debugger  v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
adapter speed: 4000 kHz
Info : Configured 2 cores
esp32 interrupt mask on
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : J-Link V9 compiled Oct 25 2018 11:46:07
Info : Hardware version: 9.10
Info : VTarget = 3.303 V
Info : clock speed 4000 kHz
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32: Debug controller 0 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core 0 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Debug controller 1 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core 1 was reset (pwrstat=0x5F, after clear 0x0F).
Info : Detected debug stubs @ 3ffb39c0 on core0 of target 'esp32'
Info : Listening on port 3333 for gdb connections

The server is now waiting for connections on port 3333 which we are going to use from Eclipse in a next step.

Eclipse Launch Configuration

In Eclipse, create a new ‘GDB Hardware Debugging’ launch configuration.

In the ‘Main’ tab specify the project and the binary to be used:

Main Launch Configuration Settings

Main Launch Configuration Settings

In the ‘Debugger’ tab, specify the path to gdb:

C:/esp/toolchain/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb.exe

💡 Note the forward slashes (/) for the path!

GDB Debugger Connection Settings

GDB Debugger Connection Settings

In the ‘Startup’ tab use the following settings and enter the following commands:

set mem inaccessible-by-default off
mon reset halt
flushregs
set remote hardware-watchpoint-limit 2
Debugger Startup Settings

Debugger Startup Settings

The above settings are for debugging an already flashed application on the ESP32. To program the binary, add the following after the ‘mon reset halt’:

mon program_esp32 "build/hello-world.bin" 0x10000 verify

Note that with the above notation it requires that the OpenOCD server has been started just above that ‘build’ folder location (means: with the current directory of the project).

IMPORTANT: Ideally, I would use something like this:

mon program_esp32 "${project_loc:idf_hello_world}/build/hello-world.bin" 0x10000 verify

But this does *not* work (at least in the current Eclipse version, as the path gets passed in a wrong way to OpenOCD with the slashes removed 😦 :

** Programming Started **
auto erase enabled
Error: couldn't open H:VorlesungADISgitProjectsMCUXpressoIDEidf_hello_world/build/hello-world.bin
embedded:startup.tcl:480: Error: ** Programming Failed **

The alternative (and ugly) way is to use an absolute path instead, e.g.

mon program_esp32 "H:/Vorlesung/ADIS/git/Projects/MCUXpressoIDE/idf_hello_world/build/hello-world.bin" 0x10000 verify

To save the configuration as .launch file in the project (see “Sharing Debug Configuration with Eclipse“), use the following setting:

Common Settings

Common Settings

That’s it for the Eclipse launch configuration.

Debugging with Eclipse

Now I can use the launch configuration to debug my target:

Debugging and using the Launch Configuration

Debugging and using the Launch Configuration

In the running GDB server (DOS command prompt) I should see now that it accepts my connection request from Eclipse:

C:\esp\openocd-esp32\bin>openocd.exe -f interface/jlink.cfg -f board/esp-wroom-32.cfg
Open On-Chip Debugger  v0.10.0-esp32-20190708 (2019-07-08-11:04)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
adapter speed: 4000 kHz
Info : Configured 2 cores
esp32 interrupt mask on
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : J-Link V9 compiled Oct 25 2018 11:46:07
Info : Hardware version: 9.30
Info : VTarget = 3.335 V
Info : clock speed 4000 kHz
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : Listening on port 3333 for gdb connections
Info : accepting 'gdb' connection on tcp/3333
Error: No symbols for FreeRTOS
Info : Target halted. PRO_CPU: PC=0x40148F12 (active)    APP_CPU: PC=0x40148F12
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40148F12
Info : Flash mapping 0: 0x10020 -> 0x3f400020, 105 KB
Info : Flash mapping 1: 0x30018 -> 0x400d0018, 490 KB
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40148F12
Info : Auto-detected flash size 4096 KB
Info : Using flash size 4096 KB
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40148F12
Info : Flash mapping 0: 0x10020 -> 0x3f400020, 105 KB
Info : Flash mapping 1: 0x30018 -> 0x400d0018, 490 KB
Info : Using flash size 492 KB
Info : Target halted. PRO_CPU: PC=0x400916EE (active)    APP_CPU: PC=0x40148F12
Info : Flash mapping 0: 0x10020 -> 0x3f400020, 105 KB
Info : Flash mapping 1: 0x30018 -> 0x400d0018, 490 KB
Info : Using flash size 108 KB
Warn : negative reply, retrying
Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : esp32: Debug controller 0 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core 0 was reset (pwrstat=0x5F, after clear 0x0F).
Info : Target halted. PRO_CPU: PC=0x5000004B (active)    APP_CPU: PC=0x00000000
Info : esp32: Core 0 was reset (pwrstat=0x1F, after clear 0x0F).
Info : esp32: Debug controller 1 was reset (pwrstat=0x5F, after clear 0x0F).
Info : esp32: Core 1 was reset (pwrstat=0x5F, after clear 0x0F).
Info : Target halted. PRO_CPU: PC=0x40000400 (active)    APP_CPU: PC=0x40000400
Info : Detected debug stubs @ 3ffb3a30 on core0 of target 'esp32'
Info : Target halted. PRO_CPU: PC=0x400D5650 (active)    APP_CPU: PC=0x40148F12

Note: It does *not* work with a J-Link EDU mini (https://www.segger.com/products/debug-probes/j-link/models/j-link-edu-mini/), probably because it is not fast enough? Lowering the JTAG frequency did help, OpenOCD reports LIBUSB_ERROR_TIMEOUT errors

Info : accepting 'gdb' connection on tcp/3333
Error: No symbols for FreeRTOS
Warn : Failed to send data to device: LIBUSB_ERROR_TIMEOUT.
Warn : Failed to send data to device: LIBUSB_ERROR_TIMEOUT.
Error: Sending data to device timed out.
Error: transport_write() failed: timeout occurred.
Error: jaylink_jtag_io() failed: timeout occurred.
Error: Failed to fetch AR regs!

Warn : Last read operation left 579 bytes.
Info : Target halted. PRO_CPU: PC=0x00000000 (active)    APP_CPU: PC=0x00000000
Warn : Failed to send data to device: LIBUSB_ERROR_TIMEOUT.
Warn : Failed to send data to device: LIBUSB_ERROR_TIMEOUT.
Error: Sending data to device timed out.
Error: transport_write() failed: timeout occurred.
Error: jaylink_jtag_io() failed: timeout occurred.
Warn : Last read operation left 2048 bytes.
Warn : Failed to send data to device: LIBUSB_ERROR_TIMEOUT.
Warn : Failed to send data to device: LIBUSB_ERROR_TIMEOUT.
Error: Sending data to device timed out.
Error: transport_write() failed: timeout occurred.
Error: jaylink_jtag_io() failed: timeout occurred.
Warn : Last read operation left 2048 bytes.

With this, I’m using the power of Eclipse to debug the ESP32 and can see all the FreeRTOS threads 🙂

Debugging ESP32 with Eclipse

Debugging ESP32 with Eclipse

Summary

While most people are ‘debugging’ the ESP32 in ‘Arduino printf()’ style, I prefer to use a real debugger to inspect the target state and step through the code. Eclipse with GDB is a great tool helping me to understand the code execution on the ESP32. It requires a JTAG debug probe as the SEGGER J-Link and the needed JTAG pins available on a debug header. While this is some effort, the benefits of it are priceless in my view.

Happy JTAGing 🙂

Links

9 thoughts on “Eclipse JTAG Debugging the ESP32 with a SEGGER J-Link

  1. Erich,
    great article. I wanted to get JTAG debugging going on my ESP32 for a while now. So today I tried to hook up two JTAG adapters (generic and j-link) up to the JTAG port of my ESP-WROVER. Ran into trouble right away (with both of them!). Could not get the JTAG interface to respond at all. Had to add a pull-up resistor on IO14: JTAG TMS to make it work. Maybe this is the same issue you had with your smaller J-Link EDU mini?

    Like

      • So far my projects centered around Kinetis uC’s, So, most of the time I use the on-board SWD debug interfaces when dealing with our assortment of EVKs.

        But to get the single-step debug going with the ESP32 I tried using the Altera/Intel USB Blaster, and an old Amontec JTAGkey2 we have at the office. At home I tried it with my J-Link Edu. Did not get very far with either.

        Looking at the JTAG interface pins on the ESP32: only two have either a pull-up or pull-down resistor built in (MTDO and MTDI), while neither the MTCK nor the MTMS have any. In my opinion, those should be pulled to safe and steady levels just to avoid floating inputs.

        Seems that on my board (which has the standard ESP32 USB-UART upload port as well) the state of that interface may prevent the JTAG from working… need to hook up my trusty LogicPro16 and investigate.

        Like

        • Me too: my projects are mostly around Kinetis.
          I tried adding 10k pull-ups to the JTAG lines as you suggested. But adding a pull-up to the TDI does not let the ESP32 boot. I can add pull-ups to the TDO and TMS, and that still works with the ‘big’ J-Link EDU.
          But it does not work with the J-Link EDU, still the same error message from OpenOCD:

          Warn : Failed to send data to device: LIBUSB_ERROR_TIMEOUT.
          Warn : Failed to send data to device: LIBUSB_ERROR_TIMEOUT.
          Error: Sending data to device timed out.
          Error: transport_write() failed: timeout occurred.
          Error: jaylink_jtag_io() failed: timeout occurred.
          Error: Failed to fetch AR regs!

          So the J-Link EDU Mini does not work, and I think this might be a problem of OpenOCD.
          To my understanding and reading the information on the web, the ESP32 has internal pull-ups and pull-downs, so no external resistors should be needed. The Espressif boards with JTAG interface do not have pull resistors too.
          Anyway, thanks for the idea!

          Like

  2. The ESP32 Series Datasheet Version 3.1 (covers ESP32-D0WD, ESP32-D0WDQ6, ESP32-D2WD and ESP32-S0WD) states in section 2.4:

    “… During the chip’s system reset release (power-on-reset, RTC watchdog reset and brownout reset), the latches of the strapping pins sample the voltage level as strapping bits of ”0” or ”1”, and hold these bits until the chip is powered down or shut down. The strapping bits configure the device’s boot mode, the operating voltage of VDD_SDIO and other initial system settings. …”

    The important part here is that this happens during specific reset cycles, namely power-on-reset/watchdog reset or brownout reset. During these reset cycles it latches the state of the MTDI pin (GPIO12):


    Voltage of Internal LDO (VDD_SDIO)

    Pin Default 3.3V 1.8V
    MTDI Pull-down 0 1

    So, depending on the ESP32 board or module you are using, you need to determine what kind of SPI FLASH ROM is in use. For my ESP-WROVER this happens to be 3.3V SPI FLASH. The pin therefore needs to see a LOW level during those reset cycles to operate at all.

    To throw another wrinkle in there, the ESP32 contains an EFUSE block that allows overriding some of the strapping pin settings:

    “… • Firmware can configure register bits to change the settings of ”Voltage of Internal LDO (VDD_SDIO)” and ”Timing of SDIO Slave”, after booting. …”

    Just to show that MTDI adds a bit of complexity, the manual goes on to state:

    “… • For ESP32 chips that contain an embedded flash, users need to note the logic level of MTDI. For example, ESP32-D2WD contains an embedded flash that operates at 1.8 V, therefore, the MTDI should be pulled high. …”

    In Appendix A.4.IO_MUX, MTDI is listed as having an internal weak pull-down.

    Of note are the equally important MTCK and MTMS pins, which do not come with any internal pull-up or pull-down resistors at all. Which is probably why ESPRESSIF has (jumper configurable) external 10K pull-down resistor on MTCK, and an external 10K pull-up resitor on MTMS on their ESP-WROVER-KIT board (schematics see JTAG section ESP-WROVER-KIT_V4_1.pdf).

    Like

    • Thank you so much for all the detailed information!
      But none of these allowed me to use the SEGGER J-Link, I tried pull resistors in different combinations. Independently, SEGGER has contacted me and I’m exchanging information with them, and potentially we might be able to identify the isse. SEGGER is getting an ESP32 hardware so they could try it out on their side. An early indication could be that the issue is within OpenOCD not using the correct way to get the data through USB. Once I know more, I plan to post an update.

      Like

  3. Pingback: JTAG Debugging the ESP32 with FT2232 and OpenOCD | MCU on Eclipse

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.