Debugging options¶

debug_tool¶

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.

Example

[env:debug]
platform = ...
board = ...
debug_tool = custom

debug_init_break¶

An initial breakpoint that makes your program stop whenever a certain point in the program is reached. Default value is tbreak main that means to create a temporary breakpoint at int main(...) function and automatically delete it after the first time a program stops there.

• GDB Setting Breakpoints

• GDB Breakpoint Locations

Examples

[env:debug]
platform = ...
board = ...

; Examples 1: disable initial breakpoint
debug_init_break =

; Examples 2: temporary stop at ``void loop()`` function
debug_init_break = tb loop

; Examples 3: stop in main.cpp at line 13
debug_init_break = break main.cpp:13

debug_init_cmds¶

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 remote $DEBUG_PORT
  file "$PROG_PATH"
  load "$PROG_PATH"
  monitor init
  monitor reset halt
  $INIT_BREAK

debug_extra_cmds¶

Extra commands that will be passed to back-end debugger after initialization. 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

debug_load_cmd¶

Specify a command which will be used to load program/firmware to a target device. Possible options:

• debug_load_cmd = command - pass any debugging client command (GDB, etc.)

• debug_load_cmd = load - is setup by default

• debug_load_cmd = load address - load program at specified address, where “address” should be a valid number

• debug_load_cmd = 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 to load program/firmware using development platform “upload” method (via bootloader, media disk, etc)

• debug_load_cmd = - (empty value), disables program loading at all.

debug_server¶

Allows 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

Example:

[env:debug]
platform = ...
board = ...
debug_server =
  /path/to/debugging/server
  arg1
  arg2
  ...
  argN

debug_port¶

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