Using Cortex-Debug for Espressif esp32s3 devices

[SparePartsBin]

I am trying to start a VScode Cortex-Debug session using an esp32s3-DevKitC-1. In simplest terms, I need to use the Espressif version of openocd. My problem is that I want to start the Espressif openocd either in a terminal (manually works fine) and "attach" via launch.json. My problem is that Cortex-Debug ignores the attach request with the servertype openocd. It always goes to request->launch. When this happens there is no way to include configuration files (ignored as well). Cortex-Debug posts the following message, "At least one OpenOCD Configuration File must be specified." The system path to the Espressif openocd executable is correct as Cortex-Debug requires. What needs to be done that I'm overlooking?

    {
        "name": "ESP32-S3 Cortex Debug (openocd)",
        "type": "cortex-debug", //NOTE: if I change this to "cppdebug"
        "request": "attach",        // and this to launch. There are no problems.
        "servertype": "openocd",

        "executable": "${workspaceFolder}/build/ReSpeakerWifiBLE.elf",
        "gdbPath": "C:/Espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gdb.exe",
        "gdbTarget": "localhost:3333",

        "postAttachCommands": [
            "echo ATTACH_MODE_ACTIVE",
            "monitor reset halt"
        ],

        "showDevDebugOutput": "raw"
    },

The expected behaviour is to get the attach pop-up and scroll to the openocd.exe.

In Terminal:
Executing task: C:/Espressif/tools/openocd-esp32/bin/openocd.exe -f board/esp32s3-builtin.cfg

Open On-Chip Debugger v0.12.0-esp32-20260703 (2026-07-03-13:40)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : esp_usb_jtag: capabilities descriptor set to 0x2000
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : esp_usb_jtag: serial (38:44:BE:CD:61:88)
Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255
Info : clock speed 40000 kHz
Info : JTAG tap: esp32s3.tap0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32s3.tap1 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=0x40000400, debug_reason=00000001
Info : [esp32s3.cpu0] Reset cause (3) - (Software core reset)
Info : Set GDB target to 'esp32s3.cpu0'
Info : [esp32s3.cpu1] Target halted, PC=0x40000400, debug_reason=00000000
Info : [esp32s3.cpu1] Reset cause (3) - (Software core reset)
Info : [esp32s3.cpu1] Chip revision v0.2

[haneefdm]

Several issues here. You used "servertype": "openocd" which means that you want us to start openocd. That will work if you specify serverpath or one of Global/workspace setting related to openocd. If we start openocd, we don't use gdbTarget which is only used when "servertype": "external". external means you start the server and tell us via gdbTarget how to connect. They go together.

See https://github.com/Marus/cortex-debug/blob/master/debug_attributes.md

Openocd is supported natively by cortex-debug. So, you can let cortex-debug do the whole startup/shutdown for you. This is far easier and will expose more features.

You should be looking at the Debug Console which may have more information for you. I will need that as well to see what is going on. I am blind otherwise.

[SparePartsBin]

Here's the output from the debug console. I implemented the changes you recommened and I thank you. Here's where I am now. I can run GDB from the command line and echo "Hello".

Cortex-Debug: VSCode debugger extension version 1.12.1 git(652d042). Usage info: https://github.com/Marus/cortex-debug#usage
"configuration": {
"name": "ESP32-S3 Cortex Debug (openocd)",
"type": "cortex-debug",
"request": "launch",
"servertype": "external",
"executable": "C:/Users/Michael/Projects/ReSpeakerWifiBLE/build/ReSpeakerWifiBLE.elf",
"gdbPath": "C:/Espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gdb.exe",
"gdbTarget": "localhost:3333",
"showDevDebugOutput": "raw",
"__configurationTarget": 6,
"gdbServerConsolePort": 55878,
"pvtAvoidPorts": [],
"chainedConfigurations": {
"enabled": false
},
"debuggerArgs": [],
"swoConfig": {
"enabled": false,
"decoders": [],
"cpuFrequency": 0,
"swoFrequency": 0,
"source": "probe"
},
"rttConfig": {
"enabled": false,
"decoders": []
},
"graphConfig": [],
"preLaunchCommands": [],
"postLaunchCommands": [],
"preAttachCommands": [],
"postAttachCommands": [],
"preRestartCommands": [],
"postRestartCommands": [],
"preResetCommands": [],
"postResetCommands": [],
"toolchainPrefix": "arm-none-eabi",
"extensionPath": "c:/Users/Michael/.vscode/extensions/marus25.cortex-debug-1.12.1",
"registerUseNaturalFormat": true,
"variableUseNaturalFormat": true,
"cwd": "c:\Users\Michael\Projects\ReSpeakerWifiBLE",
"pvtVersion": "1.12.1",
"__sessionId": "68ab80f1-d7f2-4e9f-b81e-9c9864a2ce17",
"pvtShowDevDebugOutput": "raw"
}
Reading symbols from c:/espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-objdump.exe --syms -C -h -w C:/Users/Michael/Projects/ReSpeakerWifiBLE/build/ReSpeakerWifiBLE.elf
Reading symbols from c:/espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-nm.exe --defined-only -S -l -C -p C:/Users/Michael/Projects/ReSpeakerWifiBLE/build/ReSpeakerWifiBLE.elf
Launching GDB: "C:/Espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gdb.exe" -q --interpreter=mi2
1-gdb-version
Finished reading symbols from objdump: Time: 74 ms
Error: Unable to start GDB even after 5 seconds or it couldn't even start Make sure you can start gdb from the command-line and run any command like "echo hello".
If you cannot, it is most likely because "libncurses" or "python" is not installed. Some GDBs require these
GDB session ended unexpectedly. exit-code: 3221225477
Finished reading symbols from nm: Time: 987 ms
GDB never responded to an interrupt request. Trying to end session anyways

[haneefdm]

Error: Unable to start GDB even after 5 seconds or it couldn't even start Make sure you can start gdb from the command-line and run any command like "echo hello".

Looks like gdb did not start at all. You probably did but did you investigate the above? We didn't even get to talking to openocd, got stuck with gdb. Please attach what you see in the terminal where you started gdb.

Also, try running with the latest build to perhaps get better diagnostics

https://github.com/Marus/cortex-debug/releases

[SparePartsBin]

Here's the server side (openocd).
PS C:\Users\Michael\Projects\ReSpeakerWifiBLE> openocd -f board\esp32s3-builtin.cfg
Open On-Chip Debugger v0.12.0-esp32-20260703 (2026-07-03-13:40)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : esp_usb_jtag: capabilities descriptor set to 0x2000
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : esp_usb_jtag: serial (38:44:BE:CD:61:88)
Info : esp_usb_jtag: Device found. Base speed 40000KHz, div range 1 to 255
Info : clock speed 40000 kHz
Info : JTAG tap: esp32s3.tap0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1)
Info : JTAG tap: esp32s3.tap1 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] Debug controller was reset.
Info : [esp32s3.cpu0] Core was reset.
Info : [esp32s3.cpu1] Debug controller was reset.
Info : [esp32s3.cpu1] Core was reset.

Here's the debug console.

Cortex-Debug: VSCode debugger extension version 1.12.1 git(652d042). Usage info: https://github.com/Marus/cortex-debug#usage
"configuration": {
"name": "ESP32-S3 Cortex Debug (openocd)",
"type": "cortex-debug",
"request": "launch",
"servertype": "external",
"executable": "C:/Users/Michael/Projects/ReSpeakerWifiBLE/build/ReSpeakerWifiBLE.elf",
"gdbPath": "C:/Espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gdb.exe",
"gdbTarget": "localhost:3333",
"showDevDebugOutput": "raw",
"__configurationTarget": 6,
"gdbServerConsolePort": 55878,
"pvtAvoidPorts": [],
"chainedConfigurations": {
"enabled": false
},
"debuggerArgs": [],
"swoConfig": {
"enabled": false,
"decoders": [],
"cpuFrequency": 0,
"swoFrequency": 0,
"source": "probe"
},
"rttConfig": {
"enabled": false,
"decoders": []
},
"graphConfig": [],
"preLaunchCommands": [],
"postLaunchCommands": [],
"preAttachCommands": [],
"postAttachCommands": [],
"preRestartCommands": [],
"postRestartCommands": [],
"preResetCommands": [],
"postResetCommands": [],
"toolchainPrefix": "arm-none-eabi",
"extensionPath": "c:/Users/Michael/.vscode/extensions/marus25.cortex-debug-1.12.1",
"registerUseNaturalFormat": true,
"variableUseNaturalFormat": true,
"cwd": "c:\Users\Michael\Projects\ReSpeakerWifiBLE",
"pvtVersion": "1.12.1",
"__sessionId": "a2e58d08-2d9b-43c9-afbd-3aba9d6e1af0",
"pvtShowDevDebugOutput": "raw"
}
Reading symbols from c:/espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-objdump.exe --syms -C -h -w C:/Users/Michael/Projects/ReSpeakerWifiBLE/build/ReSpeakerWifiBLE.elf
Reading symbols from c:/espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-nm.exe --defined-only -S -l -C -p C:/Users/Michael/Projects/ReSpeakerWifiBLE/build/ReSpeakerWifiBLE.elf
Launching GDB: "C:/Espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gdb.exe" -q --interpreter=mi2
1-gdb-version
Finished reading symbols from objdump: Time: 69 ms
Error: Unable to start GDB even after 5 seconds or it couldn't even start Make sure you can start gdb from the command-line and run any command like "echo hello".
If you cannot, it is most likely because "libncurses" or "python" is not installed. Some GDBs require these
GDB session ended unexpectedly. exit-code: 3221225477
Finished reading symbols from nm: Time: 1059 ms
GDB never responded to an interrupt request. Trying to end session anyways.

Here's launch.json.
{
"name": "ESP32-S3 Cortex Debug (openocd)",
"type": "cortex-debug",
"request": "launch",
"servertype": "external",

        "executable": "${workspaceFolder}/build/ReSpeakerWifiBLE.elf",
        "gdbPath": "C:/Espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gdb.exe",
        "gdbTarget": "localhost:3333",

        "showDevDebugOutput": "raw"
    },

[haneefdm]

I was asking if you are able to run GDB from the command line? If you cannot do that, then neither can we. That is where we are getting stuck. Not openocd, that is the gdb-server. We are having basic issues with GDB and we never even gotten to openocd. GDB first, then openocd.

1. Open a terminal
2. Run the following command (use backslashes if your terminal/shell requires it)

C:/Espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gdb.exe

3. Do you see a gdb prompt? If so, can you type the command echo hello and see if it responds.

Attach the output of all of what you see in the Terminal.

I also see you have not upgraded to 1.13.x which can be found here.

https://github.com/Marus/cortex-debug/releases

The above won't resolve the problem but it may help diagnose it better.