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

一、官方文档

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

二、配置

1. 添加 udev 规则

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

然后：

sudo udevadm control --reload-rules
sudo 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 $USER
newgrp 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 v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
debug_level: 2
Info : only one transport option; autoselecting 'jtag'
Info : esp_usb_jtag: VID set to 0x303a and PID to 0x1001
Info : esp_usb_jtag: capabilities descriptor set to 0x2000

WARNING!!! 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 connections
Info : Listening on port 4444 for telnet connections

Info : esp_usb_jtag: serial (30:ED:A0:0B:1E:8C)

Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255
Info : clock speed 40000 kHz

Info : 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 succeed

Info : [esp32s3.cpu1] Examination succeed

Info : [esp32s3.cpu0] starting gdb server on 3333
Info : Listening on port 3333 for gdb connections

Info : [esp32s3.cpu0] Target halted, PC=0x4200F80E, debug_reason=00000001

Info : [esp32s3.cpu0] Reset cause (1) - (Power on reset)

Info : Set GDB target to 'esp32s3.cpu0'

Info : [esp32s3.cpu1] Target halted, PC=0x40379D50, debug_reason=00000000

Info : [esp32s3.cpu1] Reset cause (1) - (Power on reset)

Info : accepting 'gdb' connection on tcp/3333

Warn : No symbols for FreeRTOS!

Info : [esp32s3.cpu0] Target halted, PC=0x4038CCA2, debug_reason=00000001

Info : Flash mapping 0: 0x10020 -> 0x3c030020, 55 KB
Info : Flash mapping 1: 0x20020 -> 0x42000020, 135 KB
Info : Auto-detected flash bank 'esp32s3.cpu0.flash' size 16384 KB
Info : Using flash bank 'esp32s3.cpu0.flash' size 16384 KB

Info : [esp32s3.cpu0] Target halted, PC=0x4038CCA2, debug_reason=00000001

Info : Flash mapping 0: 0x10020 -> 0x3c030020, 55 KB
Info : Flash mapping 1: 0x20020 -> 0x42000020, 135 KB
Info : Using flash bank 'esp32s3.cpu0.irom' size 136 KB

Info : [esp32s3.cpu0] Target halted, PC=0x4038CCA2, debug_reason=00000001

Info : Flash mapping 0: 0x10020 -> 0x3c030020, 55 KB
Info : Flash mapping 1: 0x20020 -> 0x42000020, 135 KB
Info : Using flash bank 'esp32s3.cpu0.drom' size 56 KB
Info : New GDB Connection: 1, Target esp32s3.cpu0, state: halted

Warn : Prefer GDB command "target extended-remote :3333" instead of "target remote :3333"

Info : Detected FreeRTOS version: (10.5.1)