PlatformIO IDE for VSCode

PlatformIO IDE is the next-generation integrated development environment for IoT.


Visual Studio Code is a lightweight but powerful source code editor which runs on your desktop and is available for Windows, macOS and Linux. It comes with built-in support for JavaScript, TypeScript and Node.js and has a rich ecosystem of extensions for other languages (such as C++, C#, Python, PHP, Go) and runtimes (such as .NET and Unity)

../../_images/platformio-ide-vscode.png

Installation

Note

Please note that you do not need to install PlatformIO Core (CLI) separately if you are going to use PlatformIO IDE for VSCode. PlatformIO Core (CLI) is built into PlatformIO IDE and you will be able to use it within PlatformIO IDE Terminal.

  1. Download and install official Microsoft Visual Studio Code. PlatformIO IDE is built on top of it

  2. Open VSCode Package Manager

  3. Search for official platformio-ide extension

  4. Install PlatformIO IDE.

../../_images/platformio-ide-vscode-pkg-installer.png

Quick Start

This tutorial introduces you to the basics of PlatformIO IDE workflow and shows you a creation process of a simple “Blink” example. After finishing you will have a general understanding of how to work with projects in the IDE.

Setting Up the Project

  1. Click on “PlatformIO Home” button on the bottom PlatformIO Toolbar

../../_images/platformio-ide-vscode-welcome.png
  1. Click on “New Project”, select a board and create new PlatformIO Project

../../_images/platformio-ide-vscode-new-project.png
  1. Open main.cpp file form src folder and replace its contents with the next:

Warning

The code below works only in pair with Arduino-based boards. Please follow to PlatformIO Project Examples repository for other pre-configured projects.

/**
 * Blink
 *
 * Turns on an LED on for one second,
 * then off for one second, repeatedly.
 */
#include "Arduino.h"

// Set LED_BUILTIN if it is not defined by Arduino framework
// #define LED_BUILTIN 13

void setup()
{
  // initialize LED digital pin as an output.
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop()
{
  // turn the LED on (HIGH is the voltage level)
  digitalWrite(LED_BUILTIN, HIGH);

  // wait for a second
  delay(1000);

  // turn the LED off by making the voltage LOW
  digitalWrite(LED_BUILTIN, LOW);

   // wait for a second
  delay(1000);
}
../../_images/platformio-ide-vscode-blink-project.png
  1. Build your project with ctrl+alt+b hotkey (see all Key Bindings in “User Guide” section below) or using “Build” button on the PlatformIO Toolbar

../../_images/platformio-ide-vscode-build-project.png

Further for reading:

Happy coding with PlatformIO!

PlatformIO Toolbar

PlatformIO IDE Toolbar is located in VSCode Status Bar (left corner) and contains quick access buttons for the popular commands. Each button contains hint (delay mouse on it).

../../_images/platformio-ide-vscode-toolbar.png
  1. PlatformIO Home

  2. PlatformIO: Build

  3. PlatformIO: Upload

  4. PIO Remote

  5. PlatformIO: Clean

  6. PIO Unit Testing

  7. Run a task… (See “Task Runner” below)

  8. Serial Port Monitor

  9. PIO Terminal

Key Bindings

  • ctrl+alt+b / cmd-shift-b / ctrl-shift-b Build Project

  • cmd-shift-d / ctrl-shift-d Debug project

  • ctrl+alt+u Upload Firmware

  • ctrl+alt+s Open Serial Port Monitor

You can override existing key bindings or add a new in VSCode. See official documentation Key Bindings for Visual Studio Code.

Project Tasks

Task Explorer

PlatformIO provides access to “Project Task Explorer” where you can control build process of declared environments in “platformio.ini” (Project Configuration File). Project Task Explorer is located in VSCode Activity Bar under branded PlatformIO icon. You can also access it via “VSCode Menu > Open View… > PlatformIO”.

../../_images/platformio-ide-vscode-task-explorer.png

Task Runner

PlatformIO IDE provides base tasks Menu > Termina > Run Task... (Build, Upload, Clean, Monitor, etc) and custom tasks per “platformio.ini” (Project Configuration File) environment ([env:***]). A default behavior is to use Terminal Panel for presentation. Also, we use dedicated panel per unique task.

PlatformIO IDE provides own Problems Matcher named $platformio. You can use it later if decide to change base task settings.

You can override existing task with own presentation options. For example, let configure PlatformIO Task Runner to use NEW Terminal panel per each “Build” command:

  1. Please click on “gear” icon near “Build” task in Menu > Tasks

  2. Replace template in tasks.json with this code

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "PlatformIO",
            "task": "Monitor",
            "problemMatcher": [
                "$platformio"
            ],
            "presentation": {
                "panel": "new"
            }
        }
    ]
}

See more options in official VSCode documentation.

Custom Tasks

Custom tasks can be added to tasks.json file located in .vscode folder in the root of project. Please read official documentation Tasks in VSCode.

This simple example demonstrates a custom build process in verbose mode. There are a lot of other commands, please read more about PlatformIO Core (CLI) and its commands (CLI Guide).

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "shell",
            "command": "platformio",
            "args": [
                "run",
                "--verbose"
            ],
            "problemMatcher": [
                "$platformio"
            ],
            "label": "PlatformIO: Verbose Build"
        }
    ]
}

Multi-project Workspaces

You can work with multiple project folders in Visual Studio Code with multi-root workspaces. This can be very helpful when you are working on several related projects at one time. Read more in documentation Multi-root Workspaces.

Serial Port Monitor

You can customize Serial Port Monitor using Monitor options in “platformio.ini” (Project Configuration File):

Example:

[env:esp32dev]
platform = espressif32
framework = arduino
board = esp32dev

; Custom Serial Monitor port
monitor_port = /dev/ttyUSB1

; Custom Serial Monitor speed (baud rate)
monitor_speed = 115200

Debugging

Debugging in VSCode works in combination with PIO Unified Debugger. You should have PIO Account to work with it.

VSCode has a separate activity view named “Debug” (bug icon on the left toolbar). PIO Unified Debugger extends it with the next advanced debugging instruments and features:

  • Local, Global, and Static Variable Explorer

  • Conditional Breakpoints

  • Expressions and Watchpoints

  • Generic Registers

  • Peripheral Registers

  • Memory Viewer

  • Disassembly

  • Multi-thread support

  • A hot restart of an active debugging session.

There are 2 pre-configured debugging configurations:

PIO Debug:

Default configuration. PlatformIO runs Pre-Debug task and builds project using Debug Configuration. Also, it checks for project changes.

PIO Debug (skip Pre-Debug):

PlatformIO skips Pre-Debug stage and DOES NOT build or check project changes. If you do changes in project source files, they will not be reflected in a debug session until you switch back to “PIO Debug” configuration or manually run “Pre-Debug” task.

This configuration is very useful for quick debug session. It is super fast and skips different checks. You manually control project changes.

Note

Please note that PIO Unified Debugger will use the first declared build environment in “platformio.ini” (Project Configuration File) if env_default option is not specified.

../../_images/platformio-ide-vscode-debug.png

Watchpoints

Please read GDB: Setting Watchpoints before.

Currently, VSCode does not provide an API to change value format of watch points. You can manually cast output setting it as a watch of a pointer:

  • $pc, default decimal integer format

  • *0x10012000, an address, default decimal integer format

  • (void*)$pc, $pc register, hexadecimal format

  • *(void**)0x10012000, an address, hexadecimal format

Install Shell Commands

Please navigate to PIO Core Install Shell Commands.

Settings

How to configure VSCode settings?

platformio-ide.useBuiltinPIOCore

Use built-in PlatformIO Core (CLI), default value is true.

platformio-ide.useDevelopmentPIOCore

Use development version of PlatformIO Core (CLI), default value is false.

platformio-ide.autoRebuildAutocompleteIndex

Automatically rebuild C/C++ Project Index when “platformio.ini” (Project Configuration File) is changed or when new libraries are installed, default value is true.

platformio-ide.forceUploadAndMonitor

Force “Upload and Monitor” task for Upload (platformio-ide.upload) command, default value is false.

platformio-ide.customPATH

Custom PATH for platformio command. Paste here the result of echo $PATH (Unix) / echo %PATH% (Windows) command by typing into your system terminal if you prefer to use custom version of PlatformIO Core (CLI), default value is null.

platformio-ide.updateTerminalPathConfiguration

Update Terminal configuration with patched PATH environment, default value is true.

platformio-ide.activateOnlyOnPlatformIOProject

Activate extension only when PlatformIO-based project (with “platformio.ini” (Project Configuration File)) is opened in workspace, default value is false.

platformio-ide.autoCloseSerialMonitor

Automatically close platformio device monitor before uploading/testing, default value is true.

platformio-ide.reopenSerialMonitorDelay

Configure time in milliseconds after which reopen Serial Port Monitor, default value is 0, which means reopen instantly.

Known issues

PackageManager is unable to install tool

This is a known bug in VSCode Terminal issue #61.

A temporary solution is to install packages using a system terminal (not VSCode Terminal). Please use “Solution 3: Run from Terminal” in FAQ > Package Manager > [Error 5] Access is denied.

Now, back to VSCode.

Changelog

Please visit releases page.