PlatformIO
v5.0.1

Getting Started

Configuration

Instruments

Professional

Integration

Miscellaneous

platformio debug

Helper command for Debugging.

Usage

platformio debug [OPTIONS]
pio debug [OPTIONS]

# A binary shortcut for "platformio debug --interface=gdb" command
piodebuggdb [GDB OPTIONS]

Description

Prepare PlatformIO project for debugging or launch debug server.

Options

-e, --environment

Debug specified environments.

You can also specify which environments should be used for debugging by default using default_envs option from “platformio.ini” (Project Configuration File).

-d, --project-dir

Specify the path to a project directory. By default, --project-dir is equal to a current working directory (CWD).

-c, --project-conf

Process project with a custom “platformio.ini” (Project Configuration File).

--interface

PlatformIO Debugging Interface. Valid values:

  • gdb - GDB: The GNU Project Debugger

-v, --verbose

Shows detailed information when processing environments.

This option can also be set globally using force_verbose setting or by environment variable PLATFORMIO_SETTING_FORCE_VERBOSE.

Examples

  1. Prepare a project for debugging

> platformio debug

[Sun Apr 30 01:34:01 2017] Processing mzeropro (platform: atmelsam; debug_extra_cmds: b main.cpp:26; board: mzeropro; framework: arduino)
-----------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
Collected 26 compatible libraries
Looking for dependencies...
Project does not have dependencies
Compiling .pio/build/mzeropro/src/main.o
Compiling .pio/build/mzeropro/FrameworkArduinoVariant/variant.o
Compiling .pio/build/mzeropro/FrameworkArduino/IPAddress.o
Compiling .pio/build/mzeropro/FrameworkArduino/Print.o
Archiving .pio/build/mzeropro/libFrameworkArduinoVariant.a
Indexing .pio/build/mzeropro/libFrameworkArduinoVariant.a
...
Compiling .pio/build/mzeropro/FrameworkArduino/wiring_analog.o
Compiling .pio/build/mzeropro/FrameworkArduino/wiring_digital.o
Compiling .pio/build/mzeropro/FrameworkArduino/wiring_private.o
Compiling .pio/build/mzeropro/FrameworkArduino/wiring_shift.o
Archiving .pio/build/mzeropro/libFrameworkArduino.a
Indexing .pio/build/mzeropro/libFrameworkArduino.a
Linking .pio/build/mzeropro/firmware.elf
Calculating size .pio/build/mzeropro/firmware.elf
Building .pio/build/mzeropro/firmware.bin
text       data     bss     dec     hex filename
11512       256    1788   13556    34f4 .pio/build/mzeropro/firmware.elf
=========================== [SUCCESS] Took 7.82 seconds ===========================

  1. Launch GDB instance and load initial configuration per a project

> platformio debug --interface=gdb -x .pioinit

...
Loading section .text, size 0x2c98 lma 0x4000
Loading section .ramfunc, size 0x60 lma 0x6c98
Loading section .data, size 0x100 lma 0x6cf8
Start address 0x47b0, load size 11768
Transfer rate: 4 KB/sec, 3922 bytes/write.
target halted due to debug-request, current mode: Thread
xPSR: 0x81000000 pc: 0x000028f4 msp: 0x20002c00
target halted due to debug-request, current mode: Thread
xPSR: 0x81000000 pc: 0x000028f4 msp: 0x20002c00
Breakpoint 2 at 0x413a: file src/main.cpp, line 26.