pio-debug

Debug the PlatformIO project in the current directory

$ pio debug

$ pio debug [[-d|--project-dir]] [path/to/platformio_project]

$ pio debug [[-e|--environment]] [environment]

$ pio debug [[-c|--project-conf]] [path/to/platformio.ini]

$ pio debug --interface [gdb] [gdb_options]

pio debug [OPTIONS]
This command is executed within a PlatformIO project directory. It typically compiles the project in debug mode, uploads the firmware (if necessary), and then initiates a debug session, usually by launching a GDB client connected to the target.

--target <target>, -t <target>
    Specifies the debug target, e.g., debug (default), upload (program only), or test.

--environment <env_name>, -e <env_name>
    Selects a specific build environment from the platformio.ini file for the debug session.

--interface <type>, -i <type>
    Defines the debug probe interface type, such as jlink, stlink, cmsis-dap, or auto.

--exit-after-upload, -x
    Exits the debugger immediately after successfully uploading the firmware to the device.

--debugger-path <path>
    Provides the full path to the GDB executable to be used for debugging.

--init-break <func>
    Sets an initial breakpoint at the specified function name upon debugger startup.

--upload-port <port>
    Specifies the upload port for targets that require it (e.g., serial for some uploads).

--silent, -s
    Suppresses non-error output during the debug process.

--verbose, -v
    Enables verbose output, showing detailed information about the debug session and commands.

The pio debug command is a powerful utility within the PlatformIO Core, an open-source ecosystem designed for cross-platform embedded development. It provides a streamlined interface for debugging firmware directly on embedded devices, abstracting away much of the underlying complexity of debug probe configurations and GDB interactions. Developers can use pio debug to set breakpoints, inspect variables, step through code, and analyze runtime behavior for a wide range of microcontrollers. It supports various debug probes like J-Link, ST-Link, and CMSIS-DAP, and integrates seamlessly with external debuggers like GDB. This command is instrumental for identifying and resolving complex issues in embedded C/C++ applications, enhancing productivity for IoT and embedded system developers.

Debugging with pio debug requires the correct hardware setup, including a compatible debug probe connected to both the host computer and the target embedded device. The command's behavior is heavily influenced by the [env:] debug settings within the project's platformio.ini file. Debugging capabilities can vary significantly between different microcontroller architectures and debug probes, and some configurations may require specific drivers or firmware updates for the debug probe.

The platformio.ini project configuration file plays a central role in customizing pio debug sessions. Developers can specify the debug tool, port, speed, and other debug-related options under the [env:] sections. For example, debug_tool = jlink, debug_port = /dev/ttyUSB0, or custom debug_build_flags can be set here, allowing for fine-tuned control over the debugging environment without needing command-line arguments for every session.

pio debug primarily operates as a wrapper around the GNU Debugger (GDB). It automatically downloads and configures the correct GDB executable for the target architecture. When a debug session starts, pio debug launches GDB, connects it to the debug probe (often via a debug server like OpenOCD or J-Link GDB Server), and loads the compiled firmware. Users can then interact with the GDB prompt for advanced debugging commands or use an IDE's graphical debugger interface that communicates with this GDB instance.

PlatformIO's VSCode extension provides a rich graphical interface for pio debug. Within VSCode, developers can start debugging sessions with a single click, set breakpoints visually, inspect variables, view call stacks, and control program execution (step over, step into, continue). This integration significantly enhances the user experience by providing a familiar and intuitive debugging environment, making embedded debugging as accessible as debugging traditional software applications.

PlatformIO was conceived to simplify embedded development. The pio debug command was developed as a crucial component to address the inherent complexities of embedded debugging. Historically, debugging microcontrollers involved manual configuration of GDB, debug servers (like OpenOCD), and specific hardware probes, which was error-prone and time-consuming. pio debug significantly abstracted this process, integrating these tools into a seamless workflow. Its evolution has focused on expanding support for diverse hardware platforms, debugging probes, and improving user experience, especially within the PlatformIO VSCode extension.

pio(1), gdb(1), openocd(1)