Introduction: ESP32 - Cheap Solution for in Circruit Debug

Hello, In this instructable is described how to set up cheap JTAG adapter based on FTDI 2232HL chip, with visual code and arduino addon.

- FTDI 2232HL module with USB connector starting at 8$ on ebay and no paid software is required. This is great solution for hobbyist who don't want to spend 50$+ on profesionall JTAG adapter.

- This adapter could be used for debugging of other platforms like ESP8266, ARM, AVR and many others. Some configuration depends on target platform, this instruction covers only setup for ESP32.

- If you already own some JTAG adapter, you can use it when it is supported by openOCD, just start openocd with different configuration file based on type of your jtag adapter.

- platform.io can make setup easier for you, but debug is supported only in paid professional version.

- Works with most of ESP32 modules. (for example cheap wemos lolin 32)

- this jtag adapter should works with linux too, but I personally did not test it.

Step 1: Software Perquisites

  • Arduino IDE version 1.8 or newer. Windows store version is not supported. You have to use classic installer version which can be downloaded from official Arduino page https://www.arduino.cc
  • Microsoft visual studio code

These addons for visual studio code are mandatory

I also recommend to install this addon which enables intelisense for C/C++

In this manual I will use 2 working folders:

D:\devel\ESP32\tools\ - here I have placed all tools

C:\Users\xxxxx\Documents\Arduino\YourProject\ - this is folder with sketch

you can place your files anywhere else if you want, just please do not forgot to update all referencies with your actual path.

Step 2: Driver Install and Configuration

Even if windows automaticly detect FT2232 by default, windows default drivers is not enough for all advance features and it is necessary to download and install driver from FTDI site https://www.ftdichip.com/Drivers/VCP.htm

When correct driver is installed, you should see your FT2232 module in device manager not only as 2 serial ports but also as "USB serial converter A" and "USB serial converter B"

Second step is change driver for one channel of our converter. Download zadig tool from http://zadig.akeo.ie/. If I understand correcly this tool link winUSB driver to FTDI device which enables low level comunication between openOCD and USB device.

In zadig tool, in menu "Options" check "Show all Devices", then you should see your adapter in list of available devices. Select "Dual RS232-HS (Interface 0)“ then select replacement driver "WinUSB v6.1.xxxx" and finaly click on replace driver button.

When you connect your adapter to different USB port of your computer, it is necesary to change driver settings via zadig tool again, otehwise openOCD will not find your adapter.

Step 3: OpenOCD, Toolchain and Gdb

1. Open OCD is tool for in circruit debuging, on one side it talks to chip on the other side it provides gdb server where debugger(client) can connect. Download openOCD for ESP32 from https://github.com/espressif/openocd-esp32/releases and unpack it to folder D:\devel\ESP32\tools\

2. edit openOCD configuration files:

esp-wroom-32.cfg

Full path to this file is:

D:\devel\ESP32\tools\openocd-esp32\share\openocd\scripts\board\esp-wroom-32.cfg

In this file you can set communication speed by change parameter "adapter_khz". For example "adapter_khz 8000" means 8Mhz.

Default is 20MHz and it might be too high if you are using longer jumper wires or breadboard. I recommend to start at 1Mhz and if everything is OK, go to higher speed, for me 8Mhz works reliably.

minimodule.cfg

Full path to this file is:
D:\devel\ESP32\tools\openocd-esp32\share\openocd\scripts\interface\ftdi\minimodule.cfg

If I understand correctly, genuine minimodule is overpriced brakeout board with FT 2232 manufactured by FTDI and only difference between genuine minimodule and cheap module or bare chip available on market is default USB description. open OCD is looking for jtag adapter based on device description, also layout init needs to be adjusted.

Cheap module have description "Dual RS232-HS". If you are not sure about description of your device, you can check it in device manager -> device properties -> tab details -> value of property "Bus reported device description"

Content of minimodule.cfg should look like example below, lines begins with # can be deleted.

interface ftdi
#ftdi_device_desc "FT2232H MiniModule"
ftdi_device_desc "Dual RS232-HS"
ftdi_vid_pid 0x0403 0x6010
#ftdi_layout_init 0x0018 0x05fb
ftdi_layout_init 0x0008 0x000b
ftdi_layout_signal nSRST -data 0x0020

esp32.cfg

Full path to this file is:

D:\devel\ESP32\tools\openocd-esp32\share\openocd\scripts\target\esp32.cfg

Append following 2 lines to end of esp32.cfg. Without this modification, adding brakepoints will not work.

#Force hw breakpoints. Once we have a memory map, we can also allow software bps.
gdb_breakpoint_override hard

3. Download and install xtensa-esp32-elf toolchain - this toolchain contains command line debugger (gdb client) which is vital to have working debug from any graphical IDE. Bare toolchain can be downloaded from espressif site, section "Alternative setup" https://docs.espressif.com/projects/esp-idf/en/latest/get-started/windows-setup-scratch.html

Step 4: Wiring and First Test

Connect FT2322 module with ESP. I recomend to use as short wires as possible.If you are new to JTAG, do not forget that TDI of adapter will go to TDI of chip, also TDO of adapter will go to TDO of chip. JTAG data lines are NOT CROSSED like Rx/Tx on uart!

For following test I recomend upload blink example sketch or some other sketch which can indicate when CPU is running or not by blinking LED or beeping or writing to serial console.

Start openOCD by following command 

D:\devel\ESP32\tools\openocd-esp32\bin\openocd.exe<br>-s D:\devel\ESP32\tools\openocd-esp32\share\openocd\scripts 
-f interface/ftdi/minimodule.cfg -f board/esp-wroom-32.cfg

This will start openOCD and if everthing is allright you should see in command line output contains following lines:

Info : clock speed 8000 kHz<br>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)

Also openocd process will listen on TCP port 3333

Open new terminal and start command line gdb client by following comand

D:\devel\ESP32\tools\xtensa-esp32-elf\bin\xtensa-esp32-elf-gdb.exe

Wait a second and when gdb terminal will be ready write following commands one by one

target remote :3333<br>mon reset halt
continue

first command opens connection to openocd debug server, second will stop program execution on ESP and LED should stop blinking, continue restore program execution and LED sshould start blinking again.

Step 5: Add Debug Configuration to Visual Studio Code

I asume at that point you already have configured visual studio code and arduino addon correcly and you can verify and upload your sketch to the board. If not, please check some instruction how to configure visual studio code and arduino, for example on this page https://medium.com/home-wireless/use-visual-studio-code-for-arduino-2d0cf4c1760b

To get debug working its necesary to specify build output folder. Under your sketch folder there is (hidden) folder .vscode, where is file arduino.json. add to this file following line:

"output": "BuildOutput/"

run verify or upload and check your sketch folder again, there should be new BuildOutput folder and inside it file with .elf extensition. elf file is vital for debug.

Debugger settings is in file launch.json. Create this file with following content, or you can copy this file from attached example project. Do not forget adjust line 26 and define correct path to your project .elf file.

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit:  https://go.microsoft.com/fwlink/?linkid=830387

    "version": "0.2.0",
    "configurations": [
    {
        "name": "Arduino-GDB-openOCD",
        "type": "cppdbg",
        "request": "launch",
        "program": "${file}",
        "cwd": "${workspaceRoot}/BuildOutput/",
        "MIMode": "gdb",
        "targetArchitecture": "arm",
        "miDebuggerPath": "D:/devel/ESP32/tools/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb.exe",
        "debugServerArgs": "",
        "customLaunchSetupCommands": [
            {
                "text": "target remote :3333"
            },
            {
                "text": "mon reset halt"
            },
            {
                //dynamic variant
                "text": "file c:/Users/xxxxx/Documents/Arduino/${workspaceFolderBasename}/BuildOutput/${fileBasename}.elf"
                //static variant
                //"text": "file c:/Users/xxxxx/Documents/Arduino/YourProject/BuildOutput/YourProject.ino.elf"
            },
            {
                "text": "flushregs"
            },
            {
                "text": "thb app_main"
            },
            {
                "text": "c", "ignoreFailures": true
            }
        ],
        "stopAtEntry": true,
        "serverStarted": "Info\\ :\\ [\\w\\d\\.]*:\\ hardware",
        "launchCompleteCommand": "exec-continue",
        "filterStderr": true,
        "args": []
    }
    ]
}

How to start debuging:

  1. Complie and upload your sketch to board
  2. Start openOCD with parameters
  3. Set brakepoints in code where you want
  4. After setting all brakepoints, make sure that you have open your project main .ino file. (or hardcode path to .elf file in launch.json)
  5. Open debug panel in vs code (Ctrl + Shift + D)
  6. Select "Arduino-GDB-openOCD" debugger, should be only available.
  7. Hit F5 to start debug

Attachments