See also
Please make sure to read Debugging guide first.
debug_tool¶Type: String | Multiple: No
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.
Example
[env:debug]
platform = ...
board = ...
debug_tool = custom
debug_build_flags¶Type: String | Multiple: Yes | Default: -Og -g2 -ggdb2
These flags/options affect the preprocessing, compilation, assembly and linking processes for C and C++ code.
Note
This option might be helpful to adjust the optimization level if firmware with debug information is too big to be uploaded to a target
Example
[env:debug]
platform = ...
board = ...
; Set optimization level and amount of debug information generated by the compiler
debug_build_flags = -O0 -ggdb3 -g3
Other possible flags that might be useful for debugging your application.
debug_init_break¶Type: String | Multiple: No | Default: tbreak main
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.
Note
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.
Examples
[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
debug_init_cmds¶Type: String | Multiple: Yes | Default: See details…
Initial commands that will be passed to back-end debugger.
PlatformIO dynamically configures back-end debugger depending on a debug environment. Here is a list with default initial commands for the popular Tools & Debug Probes.
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_CMDS
monitor init
monitor reset halt
debug_extra_cmds¶Type: String | Multiple: Yes
Extra commands that will be passed to back-end debugger after debug_init_cmds.
For example, add custom breakpoint and load .gdbinit from a project directory
for GDB:
[env:debug]
platform = ...
board = ...
debug_extra_cmds =
break main.cpp:13
break foo.cpp:100
source .gdbinit
Note
Initial Project Breakpoints: Use break path/to/file:LINE_NUMBER to
define initial breakpoints for debug environment. Multiple breakpoints are
allowed.
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.
debug_load_cmds¶Type: String | Multiple: Yes | Default: load
Specify a command which will be used to load program/firmware to a target device. Possible options:
load - default option
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. preload command instructs
PlatformIO Core (CLI) to load program/firmware using development platform “upload”
method (via bootloader, media disk, etc)
(empty value, debug_load_cmds =), disables program loading at all.
custom commands - pass any debugging client command (GDB, etc.)
Sometimes you need to run extra monitor commands (on debug server side) before program/firmware loading, such as flash unlocking or erasing. In this case we can combine service commands with loading and run them before. See example:
[env:debug]
platform = ...
board = ...
debug_load_cmds =
monitor flash erase_sector 0 0 11
load
debug_load_mode¶Type: String | Multiple: No | Default: always
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.
debug_server¶Type: String | Multiline Arguments: Yes
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
Examples:
[env:debug]
platform = ...
board = ...
debug_server =
/path/to/debugging/server
arg1
arg2
...
argN
[env:debug_openocd]
platform = ...
board = ...
debug_tool = custom
debug_server =
${platformio.packages_dir}/tool-openocd/openocd
-f
${platformio.packages_dir}/tool-openocd/scripts/board/stm32f103zet6_warship.cfg
debug_port¶Type: String | Multiple: No
A debugging port of a remote target. Could be a serial device or network address. PlatformIO detects it automatically if is not specified.
For example:
/dev/ttyUSB0 - Unix-based OS
COM3 - Windows OS
localhost:3333
debug_speed¶Type: Number | String | Multiple: No
The debug adapter speed. The value format depends on the type of Tools & Debug Probes.
Note
Please note that this option takes effect only if Development Platforms implement it.
Examples:
[env:custom_debug_speed_examples]
...
; fixed speed in kHz
debug_speed = 500
; automatic speed (only J-Link)
debug_speed = auto
; adaptive clocking instead of fixed JTAG speed (only J-Link)
debug_speed = adaptive
debug_svd_path¶Type: FilePath | Multiple: No
A custom path to SVD file which contains information about device peripherals.
debug_server_ready_pattern¶Type: String | Multiple: No
A pattern to determine when debugging server is ready for an incoming connection. The pattern applies tool debugging server process’s STDOUT and STDERR outputs.
A regular expression (RegExp) is allowed if the pattern starts with ^ character.
See Python regular expression operations
for syntax and details.
Examples:
[env:custom_debug_server_ready_pattern]
...
; match by string
debug_server_ready_pattern = Waiting for GDB connection
; match by regular expression
debug_server_ready_pattern = ^.*Listening on port \d+ for gdb connections
debug_test¶Type: String | Multiple: No
A name of a unit test to be debugged. See Unit Testing for further details.
If a source file of a test is located in the root of test_dir,
the debug_test option should be set to *.
Examples:
[env:debug_a_test]
...
debug_test = test_calculator