VSCode

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

• Cross-platform build system without external dependencies to the OS software:

  • 800+ Boards

  • 35+ Development Platforms

  • 20+ Frameworks

• PIO Unified Debugger

• PIO Remote

• PIO Unit Testing

• C/C++ Intelligent Code Completion

• C/C++ Smart Code Linter for rapid professional development

• Library Manager for the hundreds popular libraries

• Multi-projects workflow with multiple panes

• Themes support with dark and light colors

• Serial Port Monitor

• Built-in Terminal with PlatformIO Core (CLI) and CLI tool (pio, platformio)

• Built-in PlatformIO Home.

---

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)

Installation

Note

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

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

1. Open VSCode Package Manager

2. Search for the official platformio ide extension

3. Install PlatformIO IDE.

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

2. Click on “New Project”, select a board and create new PlatformIO Project

3. 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);
}

4. 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

---

Further for reading:

• Tutorials and Examples (step-by-step tutorials with debugging and unit testing)

• Learn more about PlatformIO Toolbar and other commands (Upload, Clean, Serial Monitor) below.

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).

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

Custom Build Task

You can override default “PlatformIO: Build” task for “Build” command which is used by “Build” button in PlatformIO Toolbar and Key Bindings. See platformio-ide.buildTask setting in Settings for more details.

Built-in PlatformIO tasks are available in “Menu > Terminal > Run Task…” list.

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 the build process of the environments declared in “platformio.ini” (Project Configuration File). Project Task Explorer is located in the VSCode Activity Bar under the branded PlatformIO icon. You can also access it via “VSCode Menu > Open View… > PlatformIO”.

Task Runner

PlatformIO IDE provides built-in tasks through the menu Terminal > Run Task... (Build, Upload, Clean, Monitor, etc) and custom tasks per “platformio.ini” (Project Configuration File) environment ([env:***]). The default behavior is to use Terminal Panels for presentation, one panel dedicated to each unique task.

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

You can override existing tasks with your own presentation options. For example, let’s configure PlatformIO Task Runner to use a NEW Terminal panel for each “Build” command:

1. The menu item Terminal > Run Task... opens up a list of VSCode tasks for PlatformIO. In the line PlatformIO: Build, press the gear icon on the far right side of the list. This creates or opens the file .vscode/tasks.json with some template code.

2. Replace the 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 the official VSCode documentation.

Custom Tasks

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

This simple example demonstrates a custom monitor task which echoes input locally. 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": [
                "device",
                "monitor",
                "--echo"
            ],
            "problemMatcher": [
                "$platformio"
            ],
            "label": "PlatformIO: Monitor (local echo)"
        }
    ]
}

If the platformio executable file is not in your system environment “PATH”, you can provide the full path to the binary folder using the options field for the task. For example, if the platformio binary is located in the home folder “~/.platformio/penv/bin”:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "shell",
            "command": "platformio",
            "args": [
                "device",
                "monitor",
                "--echo"
            ],
            "problemMatcher": [
                "$platformio"
            ],
            "label": "PlatformIO: Monitor (local echo)",
            "options": {
                "env": {"PATH": "${env:HOME}/.platformio/penv/bin"}
            }
        }
    ]
}

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 the same time. Read more in the documentation Multi-root Workspaces.

Serial Port Monitor

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

• monitor_port

• monitor_speed

• monitor_rts

• monitor_dtr

• monitor_flags

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” (accessed by the bug icon on the left toolbar). PIO Unified Debugger extends it with more 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 two pre-configured debugging configurations:

PIO Debug

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

PIO Debug (skip Pre-Debug)

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

This configuration is very useful for quick debug session. It is super fast by skipping several checks, letting you control project changes manually.

Note

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

Variable Format

Currently, VSCode does not provide an UI or API to change the variable format. See the related VSCode Issue #28025.

A temporary solution is to set the default numerical base in which the debugger displays numeric output in the Debug Console. (The Debug Console is visible during active debugging sessions). For example, to show variables in hexadecimal format, copy the code below and paste it into “Debug Console”:

set output-radix 16

Possible values, listed in decimal base, are: 8, 10, 16.

Watchpoints

Please read GDB: Setting Watchpoints first.

Currently, VSCode does not provide an API to change the value format of watchpoints. You can manually cast watchpoint expressions to display the value as specific pointer types:

• $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 refer to PIO Core Install Shell Commands.

Proxy Server Support

There are two options how to configure a proxy server:

1. Declare the HTTP_PROXY and HTTPS_PROXY system environment variables (for example HTTP_PROXY=http://user:pass@10.10.1.10:3128/, etc.)

2. Open VSCode Settings and search for “Proxy”. Please set “Http: Proxy” and disable “Http: Proxy Strict SSL”.

Settings

How to configure VSCode settings?

platformio-ide.activateOnlyOnPlatformIOProject

If true, activate the platformio ide extension only when a PlatformIO-based project (that has a “platformio.ini” (Project Configuration File)) is open in the workspace. The default value is false.

platformio-ide.autoCloseSerialMonitor

If true, automatically close platformio device monitor before uploading/testing. The default value is true.

platformio-ide.autoRebuildAutocompleteIndex

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

platformio-ide.buildTask

The build task (label) that is launched by the “Build” button in the PlatformIO Toolbar and Key Bindings. The default is PlatformIO: Build.

You can create custom Custom Tasks and assign one of them to platformio-ide.buildTask.

platformio-ide.customPATH

Custom PATH for the 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 a custom version of PlatformIO Core (CLI). The default value is null, meaning PlatformIO looks for the platformio command in the system path.

platformio-ide.disableToolbar

Disable the PlatformIO toolbar. The default value is false.

platformio-ide.forceUploadAndMonitor

If true, the Upload (platformio-ide.upload) command is changed to use the “Upload and Monitor” task. The default value is false.

platformio-ide.reopenSerialMonitorDelay

Configure the time in milliseconds before reopening the Serial Port Monitor. The default value is 0, which means to reopen instantly.

platformio-ide.updateTerminalPathConfiguration

If true, use a patched PATH environment for the Terminal configuration. The default value is true.

platformio-ide.useBuiltinPIOCore

If true, use the built-in PlatformIO Core (CLI). The default value is true.

platformio-ide.useDevelopmentPIOCore

If true, use the development version of PlatformIO Core (CLI). The default value is false.

platformio-ide.disablePIOHomeStartup

Disable showing PIO Home at startup. The default value is false.

platformio-ide.pioHomeServerHttpPort

PIO Home server HTTP port. The default value 0 automatically assigns a free port in the range [8010..8100]).

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. Afterwards, go back to using the VSCode Terminal.

Changelog

Please visit the releases page.