PlatformIO IDE for VSCode¶

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:

/**
 * 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!

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.

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

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": [
                "device",
                "monitor",
                "--echo"
            ],
            "problemMatcher": [
                "$platformio"
            ],
            "label": "PlatformIO: Monitor (local echo)"
        }
    ]
}

If platformio executable file is not in your system environment “PATH”, you can provide a full path to binary folder using options field for task. For example, platformio binary is located in 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"}
            }
        }
    ]
}

Variable Format¶

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

Temporary solution is to set the default numeric base in which the debugger displays numeric output using Debug Console (you will see it during active debugging session). For example, show variables in hexadecimal format (copy below and paste into “Debug Console”):

set output-radix 16

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

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

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.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.buildTask¶

A build task (label) which is used by “Build” button in the PlatformIO Toolbar and Key Bindings. Default is set to PlatformIO: Build.

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

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.forceUploadAndMonitor¶

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

platformio-ide.reopenSerialMonitorDelay¶

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

platformio-ide.updateTerminalPathConfiguration¶

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

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.

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.