New in version 3.4.
Please make sure to read PIO Unified Debugger guide first.
A name of debugging tool. This option is useful when board supports more than one debugging tool (adapter, probe) or you want to create Custom debugging configuration.
See available tools in Tools & Debug Probes.
[env:debug] platform = ... board = ... debug_tool = custom
An initial breakpoint that makes your program stop whenever a certain point in
the program is reached. Default value is set to
tbreak main and means
creating a temporary breakpoint at
int main(...) function and
automatically delete it after the first time a program stops there.
Please note that each debugging tool (adapter, probe) has limited number of hardware breakpoints.
If you need more Project Initial Breakpoints, please place them in debug_extra_cmds.
[env:debug] platform = ... board = ... ; Examples 1: disable initial breakpoint debug_init_break = ; Examples 2: temporary stop at ``void loop()`` function debug_init_break = tbreak loop ; Examples 3: stop in main.cpp at line 13 debug_init_break = break main.cpp:13 ; Examples 4: temporary stop at ``void Reset_Handler(void)`` debug_init_break = tbreak Reset_Handler
Initial commands that will be passed to back-end debugger.
PlatformIO dynamically configures back-end debugger depending on a debug environment. Highly recommended to DO NOT override this option.
For example, the custom initial commands for GDB:
[env:debug] platform = ... board = ... debug_init_cmds = target extended-remote $DEBUG_PORT $INIT_BREAK monitor reset halt $LOAD_CMD monitor init monitor reset halt
Extra commands that will be passed to back-end debugger after initialization.
For example, add custom breakpoint and load
.gdbinit from a project directory
[env:debug] platform = ... board = ... debug_extra_cmds = break main.cpp:13 break foo.cpp:100 source .gdbinit
Initial Project Breakpoints: Use
break path/to/file:LINE_NUMBER to
define initial breakpoints for debug environment. Multiple breakpoints are
To save session breakpoints, please use
save breakpoints [filename]
command in Debug Console. For example,
save breakpoints .gdbinit. Later,
this file could be loaded via
source [filename] command. See above.
Specify a command which will be used to load program/firmware to a target device. Possible options:
load- default option
some command- pass any debugging client command (GDB, etc.)
load address- load program at specified address, where “address” should be a valid number
preload- some embedded devices have locked Flash Memory (a few Freescale Kinetis and NXP LPC boards). In this case, firmware loading using debugging client is disabled.
preloadcommand instructs PlatformIO Core (CLI) to load program/firmware using development platform “upload” method (via bootloader, media disk, etc)
- (empty value,
debug_load_cmd =), disables program loading at all.
Allows one to control when PlatformIO should load debugging firmware to the end target. Possible options:
always- load for the each debugging session, default
modified- load only when firmware was modified
manual- do not load firmware automatically. You are responsible to pre-flash target with debugging firmware in this case.
Allows one to setup a custom debugging server. By default, boards are pre-configured with a debugging server that is compatible with “on-board” debugging tool (adapter, probe). Also, this option is useful for a Custom debugging tool.
Option format (multi-line):
- First line is an executable path of debugging server
- 2-nd and the next lines are arguments for executable file
[env:debug] platform = ... board = ... debug_server = /path/to/debugging/server arg1 arg2 ... argN
A debugging port of a remote target. Could be a serial device or network address. PlatformIO detects it automatically if is not specified.
/dev/ttyUSB0- Unix-based OS
COM3- Windows OS