Debug and observe
Supported debug tools
The build systems, programmers, debug probes and connections Flash works with, and what the machine connected to your board needs.
Flash detects what your project uses and picks a compatible tool for each step. Tool support is not a guarantee for every board and probe combination: check your target in the hardware catalog.
Build systems
Flash uses your project’s own build system and configuration; it never converts the project.
| Build system | Debugger setup |
|---|---|
| ESP-IDF | Automatic, using the project’s SDK version and the OpenOCD and GDB it recommends. |
| PlatformIO | Automatic from the selected environment and board, using the project’s installed packages. Select an environment when there are several. |
| Arduino CLI | Automatic from the board (FQBN) and installed core, when the core provides debug settings. |
| Zephyr (west) | From the ELF and the target in the hardware catalog. |
| CMake and Make | From the ELF and the target in the hardware catalog. CMake configure and build presets are respected. |
| STM32CubeIDE projects | From the ELF and the target in the hardware catalog. |
Programming tools
Flash picks the tool that matches the target and connection. When several fit, you choose.
| Targets | Tools |
|---|---|
| Espressif | esptool, OpenOCD |
| STMicroelectronics STM32 | STM32CubeProgrammer, st-flash, OpenOCD, ST-LINK mass storage |
| Nordic Semiconductor | nRF Util, nrfjprog |
| Raspberry Pi RP2040 and RP2350 | picotool, UF2 drag and drop |
| Microchip AVR | avrdude |
| Texas Instruments | UniFlash DSLite |
| WCH RISC-V | WCH-Link (wlink) |
| Probe-based targets | SEGGER J-Link, probe-rs, OpenOCD, DAPLink mass storage |
| USB DFU bootloaders | dfu-util |
Erase and verify
Erasing first (whole chip or an address range) and read-back verification are available when the tool supports them. Both are shown in the approval before anything is written.
Debug probes and servers
Flash starts the GDB server for your probe and a GDB client for your target’s architecture.
| Debug server | Probes |
|---|---|
| OpenOCD | ST-LINK, J-Link, CMSIS-DAP, TI XDS110 and the built-in USB-JTAG of Espressif chips |
| SEGGER J-Link GDB Server | J-Link |
| probe-rs | ST-LINK, J-Link, CMSIS-DAP |
| pyOCD | CMSIS-DAP, including DAPLink |
Espressif USB-JTAG
Chips with built-in USB-JTAG, such as the ESP32-C6, give you serial and JTAG over one USB cable. A board with only a USB-to-UART bridge needs an external JTAG probe.
Debugger features
- Session modes: attach to running firmware, restart without programming, or launch a fresh build. See Choose how the debugger connects.
- Run control: continue, halt, step over, step into and step out.
- Breakpoints: by file and line.
- Inspection: registers, memory, variables and expressions. Flash for VS Code also shows stack frames and watches.
The agent can use every operation. In Flash CLI and Flash IDE, ask the agent to add or remove breakpoints; the panels list them.
Firmware output channels
| Channel | Through | What you get |
|---|---|---|
| UART and USB CDC | Any serial port | Baud rate and line ending control, several ports in tabs, text or binary input and log export. |
| SEGGER RTT | J-Link, or probe-rs with ST-LINK, J-Link or CMSIS-DAP | Logging channels read through the debug probe, without a UART. |
| SWO / ITM | J-Link | Cortex-M trace output at the SWO frequency you set. |
| Semihosting | J-Link or probe-rs | Output from firmware built with semihosting. Flash does not give firmware access to files on your computer. |
For J-Link, turn on RTT and SWO in FLASH.md, outside the section /init generates:
FLASH.md
<COMMANDS>rtt_enabled = trueswo_enabled = trueswo_frequency_hz = 2000000swo_itm_port = 0</COMMANDS>Device protocols
| Protocol | Supported operations |
|---|---|
| MQTT | Connect with saved profiles, subscribe, publish and wait for the matching reply. Flash can run a local Mosquitto broker that devices on your network can reach. Credentials are never shown to the agent. |
| Bluetooth LE | Scan, connect, browse GATT services, read, write and subscribe to notifications. |
Prepare the machine
Install these on the computer the board is connected to. Flash reports anything missing before it connects.
- SDK and toolchain for your build system. Flash can guide or run the install where a supported installer exists.
- A debug server and GDB for your probe: OpenOCD (the Espressif build for ESP chips), SEGGER J-Link Software, probe-rs or pyOCD.
- The programming tool for your target, from the table above.
- Probe drivers. udev rules on Linux; the WinUSB driver for Espressif USB-JTAG on Windows; the SEGGER driver for J-Link.
- Mosquitto, only for a local MQTT broker. Flash shows how to install it.
Troubleshooting
| Symptom | What to check |
|---|---|
| The debug preview finds no probe | Connect the probe before starting, check its driver or udev rules, and select it explicitly when several are connected. |
| Serial works but the debugger cannot connect | A USB-to-UART bridge does not provide JTAG or SWD. Connect a debug probe, or use the chip’s built-in USB-JTAG port if it has one. |
| The preview asks you to choose a build | Select the environment, build directory or ELF. Flash does not guess between several candidates. |
| Variables show as optimized out | Build with debug-friendly optimisation, such as -Og, and keep debug symbols. |
| The board resets when the debugger connects | Use Attach instead of Restart or Launch, and tell the agent not to reset the target. |
| Launch refuses to program the board | Build again. Flash only programs a build it made from the current sources. |
| No RTT or SWO output | Enable the channel in FLASH.md, check the SWO frequency and confirm that the firmware writes to that channel. |
| The device cannot reach the local MQTT broker | Configure the device with the computer’s LAN address that Flash shows; localhost on the device is not your computer. Both must be on the same network. |