PIO Unified Debugger


It Just Works. Easier than ever before!

  • 100+ boards (list grows)
  • Multiple architectures and development platforms
  • Zero Configuration
  • Compatibility with the popular IDEs: Eclipse, Atom, VSCode, Sublime Text, etc
  • Windows, MacOS, Linux (+ARMv6-8)

We have started a big work on the PIO Unified Debugger, a tool which supports multiple debugging interfaces, IDEs, development platforms, architectures and works with ZERO-Configuration. Yes, the simple click on “Debug” button in your favorite IDE and you are ready to debug PlatformIO Project.

The project can contain multiple environments with different boards/architectures. Also, you can debug simultaneously the same project with multiple debug environments.

Documentation: http://docs.platformio.org/page/plus/debugging.html

(See screenshots below…)

Supported Interfaces/Protocols

Supported IDE / Text Editors

!!! No need to install extra software, prepare firmware for debugging or spend time on debug tool configuration. All should work without extra steps, PIO resolves this complicated work automatically “on-the-fly” !!!

My board is not supported yet

Please reply to this thread with all details:

  • Board name (URL)
  • If it doesn’t have On-Board debug link and you have own JTAG/SWD adapter, please post here all information.

PIO Unified Debugger for Atom

Demo: mbed blink debugging

PIO Unified Debugger for VSCode

PIO Unified Debugger for Eclipse

PIO Unified Debugger for Sublime Text

The PIO Plus Team

Debugger setup and usage


Atom 1.15.0, IDE 2.0.0beta2.3, Core 3.4.0a4, macOS sierra
I tried debugging with a STM32 Nucleo303k8 board, but I did not have real luck with it.
When starting debugging the debugger stops at main(), this is ok.
With the “>” button I start the debugger again an he stops at the breakpoint as expected.
When doing the next “>” the program run thru the while loop and doesn’t stop again, I think the debugger must stop every time when reaching the break point, or did I miss understood something?
Also, there a not all variables displayed (in my example int counter), sometimes I get an error
message, sometimes not. Here the screenshot:

Here is another screenshot, the variable is not shown but no error message from gdb

The next problem is the setting of the breakpoint, it is a big problem to Clear the breakpoint, sometimes you need a dozen of mouse clicks to delete a breakpoint. Sometimes the breakpoint symbol is dimmed so you see it a little bit, but it is not set, it seems it is an graphic artefact.

Debugging feature

Error: Currently, PlatformIO does not support debug for nucleo_l476rg.



Did you install https://github.com/platformio/platform-ststm32.git ?


No … now I did:

platformio platform install https://github.com/platformio/platform-ststm32.git


ststm32 @ b31bc3b has been successfully installed!
PackageManager: Installing toolchain-gccarmnoneeabi @ >=1.40803.0,<1.40805.0
toolchain-gccarmnoneeabi @ 1.40804.0 is already installed
The platform ‘https://github.com/platformio/platform-ststm32.git’ has been successfully installed!
The rest of packages will be installed automatically depending on your build environment.

But still the same message

PlatformIO Plus (https://pioplus.com) v0.7.3
Error: Currently, PlatformIO does not support debug for nucleo_l476rg.

I used default project settings only and “PIO Debug” as target. Only added “upload_protocol = stlink” in the platformio.ini (BTW: should be default for Nucleo boards, trap for young players)

I’m new hobbyist and new to A) SMT32 and B) Platform IO. I really like your IDE. I really love your approach to intergrate a ton of different toolchains into one IDE. Using one modern IDE for Atmel, ESPs and STMs and … is great.
Moved to STMs32 because of the in circuit debugging feature but was not willing to mess around with IDEs more complicated to install than the effort the complete project takes.
Thank you for your contribution.




New PlatformIO Debugging front-end is out! Please update PIO IDE to 2.0.0-beta.2.4 (just restart Atom)

Also, don’t forget to update development platforms via pio update command.

Would be thankful for any feedback!

/cc @sstaub @Krishna_Chaitanya @HarpieC


The new frontend is amazing @ivankravets :slight_smile:

It is allowing me to probe the variables, constants, even mcu registers!!! :smiley: while single stepping!!

I have been playing with it for the last hour or so and it is brilliant!!!

Of course, I would like to point out that any probing into the pin values is dependant on the framework being used.
I spent most of my time trying to understand how to read the value of a pin while debugging.
Got it finally, but it is mostly dependant on the registers and pin declarations in the framework.A little poking around will reveal the details anyway!!!

here is a screenshot of what I am talking about

The gpioc.regs.ODR shown in the top right side is the libmaple definition of the Output Data Register. This definition varies from framework to framework. It still reflects the status of the pin while stepping.

Of course, its not a complaint with the debugging feature, more of a headsup for the others. It might seem daunting for some people.

Extremely satisfied and happy!! :smiley:


The new frontend looks fine :slight_smile: . Variable watching is very cool :slight_smile: . Some suggestion:

  • it would nice when the debugging information (breakpoints, variables watch etc.) are stored in the project, so that we need not to do all that things again after restarting.
  • support for cmsis-dap for mbed boards with nxp and other ucontrollers
  • register watch


+1 on storing the debugging information in the project space!! :slight_smile:

One of those things where you dont realise you absolutely want it until someone else points it out!! :slight_smile:


@ivankravets works perfect, thank you! :slight_smile:

Could you tell me which “.gdbinit” is loaded at startup?
(wanted also to store breakpoints and autoload them, but $HOME/.gdbinit does not work,
maybe the project directory would be a good place)


@Krishna_Chaitanya , @sstaub , @Robert_Walli , thanks a lot for the feedback! Very good that you liked it.

Each board’s configuration contains “debug” information. For example,

I’ve not documented it yet, but you can specify different GDB init commands per different debug configurations (envs). Just use

board = ...
debug_extra_cmds = 
    b main.cpp:13    


Is there any support for debugging on ESP8266 -/+ ESP32. I know the gdb is supported in the Arduino 8266…


This is a “stub”, not hardware debug. It is good only for a catching fatal exception.

We are working on it, the support will be announced later. Stay tuned with us https://twitter.com/PlatformIO_Org


does that mean that there is not ESP8266 debug support planned?
just curious:)


There are no pins for hardware debug


ah ok! thanks for that


@Krishna_Chaitanya , @sstaub , @Robert_Walli , the new version of PIO IDE is out!

  • The PIO Unified Debugger for the popular IDEs, development platforms with Zero-configuration. Whole information will be announced later.
  • Improved debugging front-end (changes)
  • Support for 100+ different embedded board now. See “Board Explorer” in IDE and sort by :bug: icon.
  • New configuration option for platformio.ini
    • debug_init_cmds - custom init commands
    • debug_extra_cmds - extra commands for debugger. Is useful to add permanent breakpoints. For example, debug_extra_cmds = b main.cpp:13 (debugger will start with hardware breakpoint in main.cpp at 13 line)

Don’t forget to update development platforms to the latest GIT which you are going to use for debugging.

Would be thankful for any feedback!


I’d only time for a quick view, will continue testing later.

The new version works as expected.

  1. debug_extra_cmds is a very useful command and works perfect!

    (btw. is there a way in platformio.ini to specify the project directory?
    e.g.: debug_extra_cmds = source ${env:PROJECT_DIR}/gdb_sourct.txt )

2.) If something went wrong with debugging, some processes keep hanging around.
maybe you could check before starting the debugger.
(“killall openocd arm-none-eabi-gdb pioplus” did it for me)

3.) env_default does not care about debugging.
If I hit the debugging button the first entry in platformio.ini is used for debugging configuration not the environment specified by env_default

4.) On my screen there is some space left beside the debugger buttons.
Would it make sense to add a button with a user defined gdb command?
The user can define the command in “debug_extra_cmds” and the button will execute it.


Thanks a lot for the quick feedback!

A project directory is added to GDB’s PATH. You need pioplus v0.8.2 (pio update)

Fixed. Please update PIO IDE Debugger package in Atom to v1.1.1

Fixed in PIO Plus v0.8.3

PIO loads debug_extra_cmds automatically after a successfull intialization.