Start free

Debug in your IDE

ct gdb-server serves a board over the GDB remote protocol, like a probe's GDB server. Your IDE loads, breaks, steps and reads memory as it would on hardware.

Set up the IDE once

From your project directory, point ct at the ELF your build produces:

terminal
ct ide setup cubeide --elf Debug/app.elf --board nucleo-f767zi
ct ide setup vscode  --elf build/app.elf --board nucleo-f767zi
ct ide setup all     --elf build/app.elf          # both
IDEWhat ct ide setup writes
STM32CubeIDECircuitTwin <elf>.launch, a GDB hardware debugging configuration for localhost:3333 that loads, resets, halts and stops at main, plus an external tool configuration that starts the server.
VS Code (Cortex-Debug)Launch and attach entries in .vscode/launch.json with the ELF and the device SVD, and a task in .vscode/tasks.json that starts the server. Existing configurations are kept.

Options: --port (default 3333), --svd (default: found in CT_SVD_DIR by part number), --gdb for VS Code (default: CT_ARM_GDB, else the STM32CubeIDE toolchain), and --session to debug a hosted session instead.

Run the GDB server yourself

terminal
ct gdb-server --board nucleo-f767zi --elf build/app.elf --catch-faults
# listening on 127.0.0.1:3333; the board console streams to stdout
  • --elf: program this image before the first debugger connects (otherwise use the debugger’s load).
  • --scenario: drive the board’s sensors from a telemetry scenario while you debug.
  • --stop-on TEXT: stop the firmware when a console line appears; --catch-faults stops on HardFault, MemManage, BusFault and UsageFault entry.
  • --once: exit when the debugger disconnects. --port 0 picks a free port.

Debug a session on the hosted service

A board running on the hosted service can be debugged from your local IDE. In the app, open a system from a project, choose Debug and then Start a debug session (or use ct cloud session). The Debug panel writes the STM32CubeIDE or VS Code files for you. Or bridge the session to a local port yourself:

terminal
ct gdb-bridge --session <SESSION_ID>
ct ide setup vscode --elf build/app.elf --session <SESSION_ID>

The bridge uses your ct login sign-in (or CT_SERVER and CT_TOKEN); the token needs the gdb scope. See Access tokens.