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

• Serial Port Monitor

• “platformio.ini” (Project Configuration File) (change upload_port, configure build_flags, add library dependencies lib_deps, etc.)

Happy coding with PlatformIO!

Task Explorer¶

PlatformIO provides access to “Project Task” 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¶

Please declare Custom Targets and refresh Task Explorer:

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

platformio-ide.activateProjectOnTextEditorChange¶

Automatically activate project depending on an active opened text editor. The default value is false.

platformio-ide.autoOpenPlatformIOIniFile¶

Automatically open the “platformio.ini” (Project Configuration File) file from a project when no other editors are opened. The default value is true.

platformio-ide.autoCloseSerialMonitor¶

If true, automatically close pio 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.showEditorTitleShortcuts¶

Show Build, Upload, Clean, and other buttons in the editor title bar. The default value is true.

platformio-ide.autoPreloadEnvTasks¶

Automatically preload ALL project environment tasks. The default value is false.

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

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

platformio-ide.useBuiltinPython¶

Use a portable Python 3 Interpreter if available. 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 PlatformIO Home at startup. The default value is false.

platformio-ide.pioHomeServerHttpHost¶

PlatformIO Home server HTTP host.The default is 127.0.0.1, but in case of dockerized environments 0.0.0.0.

platformio-ide.pioHomeServerHttpPort¶

PlatformIO Home server HTTP port. The default value 0 automatically assigns a free port in the range [45000..45999]).

platformio-ide.customPyPiIndexUrl¶

Custom base URL of the Python Package Index (default https://pypi.org/simple).

platformio-ide.toolbar¶

Configure your own PlatformIO Toolbar with your own buttons and attach commands to them. There is no limitation to command scope. You can use Built-in VSCode Commands or commands from your 3rd party favorite extensions.

The button can be text, an icon, or a mix of them. The list of supported icons is documented in VSCode Icon Listing. You can have different toolbars per workspace thanks to the User and Workspace Settings.

Example

{
  "platformio-ide.toolbar": [
    {
      "text": "$(arrow-right)",
      "tooltip": "Upload and Monitor the active environment",
      "commands": "platformio-ide.uploadAndMonitor"
    },
    {
      "text": "Outdated",
      "tooltip": "List outdated packages for the activate environment",
      "commands": [
        {
          "id": "workbench.action.tasks.runTask",
          "args": "PlatformIO: Outdated (${command:platformio-ide.activeEnvironment})"
        }
      ]
    },
    {
      "text": "$(list-selection)",
      "tooltip": "List devices",
      "commands": [
        {
          "id": "platformio-ide.runPIOCoreCommand",
          "args": "pio device list"
        }
      ]
    },
    {
      "text": "$(plug)",
      "commands": [
        {
          "id": "platformio-ide.runPIOCoreCommand",
          "args": "pio device monitor --filter time"
        }
      ]
    },
    {
      "text": "$(terminal)",
      "commands": [
        {
          "id": "workbench.action.terminal.sendSequence",
          "args": {
            "text": "echo 1\n"
          }
        }
      ]
    }
  ]
}

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.