ESP32S3 Ubuntu vscode如何使用USB-JTAG调试

一、官方文档

• openocd-esp32的问题汇总： Troubleshooting
• esp32的官方文档：调试项目

二、配置

1. 添加 udev 规则

sudo tee /etc/udev/rules.d/99-espressif-jtag.rules > /dev/null <<EOFSUBSYSTEM==\"usb\", ATTR{idVendor}==\"303a\", ATTR{idProduct}==\"1001\", MODE=\"0666\", GROUP=\"plugdev\"EOF

然后：

sudo udevadm control --reload-rulessudo udevadm trigger

拔掉 ESP32-S3，重新插入 USB。

2. 验证 USB 设备是否识别

lsusb | grep 303a

应看到类似行：

Bus 001 Device 042: ID 303a:1001 Espressif USB JTAG/Serial Debug Unit

3. 确认当前用户在 plugdev 组

groups $USER

若无 plugdev：

sudo usermod -a -G plugdev $USERnewgrp plugdev

4. vscode开启openocd

• 重启 OpenOCD 或 ESP-IDF 监视调试：

idf.py openocd# 或：openocd -f board/esp32s3-builtin.cfg

• 左下角选择JTAG，ctrl+shift+p选择openocd manager->start openocd

• 正常情况的openocd输出：

5. vscode的launch.json

• 查询 GDB 路径find ~/.espressif -name xtensa-esp32s3-elf-gdb，然后配置miDebuggerPath
  
• 配置

{ \"version\": \"0.2.0\", \"configurations\": [ { \"name\": \"ESP32-S3 USB-JTAG Debug\", \"type\": \"cppdbg\", \"request\": \"launch\", \"cwd\": \"${workspaceFolder}\", \"program\": \"${workspaceFolder}/build/${command:espIdf.getProjectName}.elf\", \"miDebuggerPath\": \"/home/surface/.espressif/tools/xtensa-esp-elf-gdb/16.2_20250324/xtensa-esp-elf-gdb/bin/xtensa-esp32s3-elf-gdb\", \"miDebuggerServerAddress\": \"localhost:3333\", \"environment\": [], \"externalConsole\": false, \"stopAtEntry\": true, \"openOcdLaunchCommands\": [ \"init\", \"reset halt\" ], \"setupCommands\": [ { \"text\": \"-enable-pretty-printing\", \"description\": \"启用 pretty printing\", \"ignoreFailures\": true } ], \"serverStarted\": \"Info : Listening on port 3333 for gdb connections\", \"filterStderr\": true, \"logging\": { \"moduleLoad\": false, \"trace\": false, \"engineLogging\": false, \"programOutput\": true, \"exceptions\": false }, \"openOcdConfigFiles\": [ \"interface/esp_usb_jtag.cfg\", \"target/esp32s3.cfg\" ] } ]}

三、实际测试

• 点击调试按钮，正常显示断点

• 正常的log输出的如下

Open On-Chip Debugger v0.12.0-esp32-20250422 (2025-04-22-13:02)Licensed under GNU GPL v2For bug reports, readhttp://openocd.org/doc/doxygen/bugs.htmldebug_level: 2Info : only one transport option; autoselecting \'jtag\'Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001Info : esp_usb_jtag: capabilities descriptor set to 0x2000WARNING!!! OpenOCD binary version (Open On-Chip Debugger v0.12.0-esp32-20250422 (2025-04-22-13:02)) doesn\'t match the .cfg file version (v0.12.0-esp32-20240318)Info : Listening on port 6666 for tcl connectionsInfo : Listening on port 4444 for telnet connectionsInfo : esp_usb_jtag: serial (30:ED:A0:0B:1E:8C)Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255Info : clock speed 40000 kHzInfo : JTAG tap: esp32s3.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)Info : JTAG tap: esp32s3.cpu1 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)Info : [esp32s3.cpu0] Examination succeedInfo : [esp32s3.cpu1] Examination succeedInfo : [esp32s3.cpu0] starting gdb server on 3333Info : Listening on port 3333 for gdb connectionsInfo : [esp32s3.cpu0] Target halted, PC=0x4200F80E, debug_reason=00000001Info : [esp32s3.cpu0] Reset cause (1) - (Power on reset)Info : Set GDB target to \'esp32s3.cpu0\'Info : [esp32s3.cpu1] Target halted, PC=0x40379D50, debug_reason=00000000Info : [esp32s3.cpu1] Reset cause (1) - (Power on reset)Info : accepting \'gdb\' connection on tcp/3333Warn : No symbols for FreeRTOS!Info : [esp32s3.cpu0] Target halted, PC=0x4038CCA2, debug_reason=00000001Info : Flash mapping 0: 0x10020 -> 0x3c030020, 55 KBInfo : Flash mapping 1: 0x20020 -> 0x42000020, 135 KBInfo : Auto-detected flash bank \'esp32s3.cpu0.flash\' size 16384 KBInfo : Using flash bank \'esp32s3.cpu0.flash\' size 16384 KBInfo : [esp32s3.cpu0] Target halted, PC=0x4038CCA2, debug_reason=00000001Info : Flash mapping 0: 0x10020 -> 0x3c030020, 55 KBInfo : Flash mapping 1: 0x20020 -> 0x42000020, 135 KBInfo : Using flash bank \'esp32s3.cpu0.irom\' size 136 KBInfo : [esp32s3.cpu0] Target halted, PC=0x4038CCA2, debug_reason=00000001Info : Flash mapping 0: 0x10020 -> 0x3c030020, 55 KBInfo : Flash mapping 1: 0x20020 -> 0x42000020, 135 KBInfo : Using flash bank \'esp32s3.cpu0.drom\' size 56 KBInfo : New GDB Connection: 1, Target esp32s3.cpu0, state: haltedWarn : Prefer GDB command \"target extended-remote :3333\" instead of \"target remote :3333\"Info : Detected FreeRTOS version: (10.5.1)