Skip to content

Commit f4887bf

Browse files
jpeletierjpeletier
authored
JTAG debugging quick guide for Linux (#3088)
1 parent b8e8ffa commit f4887bf

File tree

3 files changed

+139
-0
lines changed

3 files changed

+139
-0
lines changed

‎docs/debug.md

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Configuring JTAG debugging in Linux
2+
3+
See Espressif's [JTAG debugging guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html#introduction).
4+
5+
## Required hardware
6+
7+
You will need a JTAG adapter to connect to the ESP32 debugging interface.
8+
9+
I was successful setting up JTAG debugging using this adapter, cjmcu-232h, which can be found cheaply in many online stores
10+
11+
![cjmcu-232h](img/cjmcu-232h.png "cjmcu-232h")
12+
13+
It is based in the FT232H chip. Other adapters with this chip should also work.
14+
15+
### FT232H pin mapping
16+
17+
JTAG in the ESP32 uses GPIO pins 12, 13, 14 and 15 so make sure you are not using them in your application.
18+
19+
Connect your ESP32 to the JTAG adapter this way:
20+
21+
* GPIO12 — AD1 (TDI)
22+
* GPIO13 — AD0 (TCK)
23+
* GPIO14 — AD3 (TMS)
24+
* GPIO15 — AD2 (TDO)
25+
* GND — GND
26+
27+
### Enabling the adapter in your system
28+
29+
Download `https://github.com/espressif/openocd-esp32/blob/master/contrib/60-openocd.rules`, place it in your `/etc/udev/rules.d` directory and reboot.
30+
31+
## Installing ESP-IDF SDK instance
32+
33+
Follow the [ESP32 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) to install an SDK instance in your system. We will use this SDK instance only for the debugging tools, not for building NodeMCU.
34+
35+
This will install the openocd version for NodeMCU (`openocd`) and the debugger (`xtensa-esp32-elf-gdb`)
36+
37+
## Debugging
38+
39+
OpenOCD needs to handle communication with the JTAG adapter and offer an interface that can be used by GDB. Thus, OpenOCD needs to always be running in the background, whether you use GDB directly, gdbui, Visual Studio Code, Eclipse or any other tool.
40+
41+
### Launching OpenOCD
42+
43+
Open a terminal, change to the SDK installation directory and execute:
44+
45+
`. export.sh`
46+
47+
Then, run `openocd`:
48+
49+
`openocd -f board/esp32-wrover-kit-3.3v.cfg`
50+
51+
If the JTAG connection with your device is successful, it will sit there listening for a connection from GDB.
52+
53+
### Debugging with gdbui
54+
55+
#### Preparation
56+
57+
In the NodeMCU repository root, create a `gdbinit` file with this content:
58+
59+
```
60+
target remote :3333
61+
set remote hardware-watchpoint-limit 2
62+
mon reset halt
63+
flushregs
64+
thb app_main
65+
c
66+
```
67+
68+
#### Starting a debug session with gdbui
69+
70+
Open another terminal, change to the SDK installation directory and execute:
71+
72+
`. export.sh`
73+
74+
Then, change to de NodeMCU repository root and run:
75+
76+
`gdbgui --gdb xtensa-esp32-elf-gdb --gdb-args="-x gdbinit"`
77+
78+
A browser window will open, showing the debugger
79+
80+
### Configuring Visual Studio Code
81+
82+
Use the below as a template, replacing the `miDebuggerPath` key to the path to the downloaded SDK gdb debugger `xtensa-esp32-elf-gdb`, usually something like `$HOME/.espressif/tools/xtensa-esp32-elf/esp-2020r1-8.2.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb`
83+
84+
```json
85+
{
86+
// Use IntelliSense to learn about possible attributes.
87+
// Hover to view descriptions of existing attributes.
88+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
89+
"version": "0.2.0",
90+
"configurations": [
91+
{
92+
"name": "OpenOCD Debug",
93+
"type": "cppdbg",
94+
"request": "launch",
95+
"miDebuggerPath": "PATH TO xtensa-esp32-elf-gdb IN SDK",
96+
"program": "${workspaceFolder}/build/NodeMCU.elf",
97+
"setupCommands": [
98+
{
99+
"description": "enable pretty printing for gdb",
100+
"text": "-enable-pretty-printing",
101+
"ignoreFailures": true
102+
},
103+
{
104+
"text": "file '${workspaceFolder}/build/NodeMCU.elf'"
105+
},
106+
{
107+
"text": "target remote :3333"
108+
},
109+
{
110+
"text": "set remote hardware-watchpoint-limit 2",
111+
},
112+
{
113+
"text": "flushregs"
114+
},
115+
{
116+
"text": "monitor reset halt"
117+
},
118+
{
119+
"text": "thb app_main"
120+
}
121+
],
122+
"cwd": "${workspaceFolder}",
123+
"externalConsole": false
124+
}
125+
]
126+
}
127+
128+
```
129+
130+
You can then launch this configuration and debug as normal.
131+
132+
Sometimes, the session does not connect. Usually works if you try again.
133+
134+
## Other useful links:
135+
136+
https://medium.com/@manuel.bl/low-cost-esp32-in-circuit-debugging-dbbee39e508b
137+
138+
https://dzone.com/articles/jtag-debugging-the-esp32-with-ft2232-and-openocd

‎docs/img/cjmcu-232h.png

368 KB
Loading

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ pages:
2525
- Building the firmware: 'build.md'
2626
- Flashing the firmware: 'flash.md'
2727
- Uploading code: 'upload.md'
28+
- JTAG debugging: 'debug.md'
2829
- Support: 'support.md'
2930
- FAQs:
3031
- Lua Developer FAQ: 'lua-developer-faq.md'

0 commit comments

Comments
 (0)