Debug and observe

Debug on real hardware.

Describe the symptom. Flash prepares the debugger, serial monitor and device connections, inspects the running target and backs each conclusion with evidence from the board.

What you can use

Flash works with the probes and instruments already on your bench, and makes each one available to you and the agent.

Execution

Debugger

Attach over JTAG or SWD, halt, step, set breakpoints and read registers, memory and variables.

Logs

Serial monitor

Read UART or USB output and send commands, with several ports in tabs.

Probe output

RTT, SWO and semihosting

Firmware output through the debug probe, with no UART needed.

Network

MQTT

Publish a command and check the device’s reply, with a local broker if you need one.

Wireless

Bluetooth LE

Scan, connect and test GATT reads, writes and notifications.

Deploy

Build and flash

Build with your project’s build system and program the board with the right tool.

See Supported debug tools for every probe, server and programmer.

What Flash prepares for you

No .gdbinit, server configuration or launch file to write. When a session starts, Flash:

Identifies the build

Finds the target MCU, the firmware image, its debug symbols and the entry point.

Selects matching tools

Picks a debug server and GDB for the target and probe, using the versions your SDK recommends when it pins them, as ESP-IDF does.

Identifies the probe

Detects the connected probe and asks you to choose when there are several.

Shows the plan before connecting

Preview debug setup lists what Flash will use, or exactly what is missing. It never halts, resets or programs the board.

Prepared by /init

/init prepares connection profiles for serial, MQTT, Bluetooth LE and the debugger. Pick one to fill in the settings; nothing connects until you start it.

Choose how the debugger connects

Choose the least intrusive mode that can answer your question.

Mode	What happens	Use it when
Attach (default)	Connects to the running firmware. No reset, no programming; the core may pause briefly.	You need the current state: a hang, a fault, a value in RAM.
Restart	Resets without programming, optionally stopping at the entry point.	You want to follow startup.
Launch	Programs a fresh build, then starts debugging. Asks before writing to the board.	You want to debug a change you just made.

Preserve the evidence

A reset, a reflash or even a halt can destroy the state you are investigating. When it matters, say so: attach without resetting, do not reflash.

What the agent does in Debug mode

The agent works from evidence: it captures a baseline, tests one hypothesis at a time, makes a focused fix and checks it against the original symptom. Flash switches to Debug on its own when a request needs the board, unless you chose a mode yourself. The agent can:

Check every instrument before connecting anything.
Capture serial output for a set time and look for boot markers, resets and errors.
Attach the debugger, halt, step, set breakpoints, and read registers, memory and variables.
Publish an MQTT command and wait for the reply, or read and write a Bluetooth LE characteristic.
Program a reviewed build and confirm the new firmware starts.

Every physical action follows your tool approvals, and Plan mode never touches the target.

Ask for a debugging task

Give the symptom, what must not change and what counts as a result.

Investigate a fault

›The board hard-faults a few seconds after the sensor starts sampling. Attach the debugger without resetting or reflashing. Read the fault status registers, the program counter and the link register, and explain the likely cause.

Verify a fix on the board

›Build the fix and program the board. Capture serial output for 20 seconds after reset. Confirm that the "sensor ready" line appears and that no reset occurs.

Check a device protocol

›Connect to the project's MQTT broker. Publish {"cmd":"status"} to devices/42/cmd and wait up to 10 seconds for the matching reply on devices/42/status. Report the payload.

Where the controls are

You see the agent’s connections in the same panels, and it cannot take over a connection you opened.

Tool	Debug controls
Flash CLI	The DEBUG panel, with Serial, MQTT, GDB and BLE tabs. Open it with `/debug` or `Alt`+`D`. BUILD compiles and programs the board.
Flash IDE	The Debug workspace, with Serial, MQTT, BLE, the GDB debugger and build output.
Flash for VS Code	Flash: Open Monitor, with Debugger, Serial, MQTT, BLE and Build views.

Know the limits

Hardware stays local. Probes and ports must be on the machine where Flash runs; over SSH, that is the remote machine.
Your tools, your drivers. Flash uses what is installed there. See Prepare the machine.
Serial is not JTAG. A working serial port does not mean JTAG or SWD is reachable.
A connection is not a verdict. Compare what Flash observed with your success criterion before calling it fixed.

Continue reading

Supported debug tools

Build systems, programmers, probes, output channels and machine setup.

Debug on the board

Tutorial: flash, check serial and attach the debugger.

Tasks and verification

Understand what each result proves.