PlatformIO IDE for Atom

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

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

    • 350+ embedded boards
    • 20+ development platforms
    • 10+ frameworks

  • 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 and CLI tool (pio, platformio)

PlatformIO IDE is based on GitHub’s Atom source code editor that’s modern, approachable, yet hackable to the core; a tool you can customize to do anything but also use productively without ever touching a config file.

../_images/ide-atom-platformio.png

Installation

PlatformIO IDE is the next-generation integrated development environment for IoT. It’s built on top of GitHub’s Atom “hackable” text editor. If you have already Atom installed, please install PlatformIO IDE for Atom package.

Note

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

Also, PlatformIO IDE allows to install PlatformIO Core Shell Commands (pio, platformio) globally to your system via Menu: PlatformIO > Install Shell Commands.

1. Python Interpreter

PlatformIO IDE is based on PlatformIO Core which is written in Python. Python is installed by default on the all popular OS except Windows.

Windows Users, please Download the latest Python 2.7.x and install it. DON’T FORGET to select Add python.exe to Path feature on the “Customize” stage, otherwise python command will not be available.

../_images/python-installer-add-path.png

2. Clang for Intelligent Code Completion

PlatformIO IDE uses Clang for the Intelligent Code Completion. To check that clang is available in your system, please open Terminal and run clang --version. If clang is not installed, then install it and restart Atom:

  • Mac OS X: Install the latest Xcode along with the latest Command Line Tools (they are installed automatically when you run clang in Terminal for the first time, or manually by running xcode-select --install

  • Windows: Download the latest Clang for Windows. Please select “Add LLVM to the system PATH” option on the installation step.

    ../_images/clang-installer-add-path.png

    Warning

    If you see Failed to find MSBuild toolsets directory error in the installation console, please ignore it and press any key to close this window. PlatformIO IDE uses only Clang completion engine that should work after it without any problems.

  • Linux: Using package managers: apt-get install clang or yum install clang.

  • Other Systems: Download the latest Clang for the other systems.

Warning

If some libraries are not visible in PlatformIO IDE for Atom and Code Completion or Code Linting does not work properly, please perform Menu: PlatformIO > Rebuild C/C++ Project Index (Autocomplete, Linter)

3. IDE Installation

  • Download and install official GitHub’s Atom text editor, PlatformIO IDE is built on top of it
  • Open Atom Package Manager and Install platformio-ide package (auto installer)
    • Mac OS X, Menu: Atom > Preferences > Install
    • Windows, Menu: File > Settings > Install
    • Linux, Menu: Edit > Preferences > Install
../_images/ide-atom-platformio-install.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.

Launch

After installation, you launch PlatformIO IDE by opening Atom. Once Atom is open, PlatformIO IDE auto installer will continue to install dependent packages and PlatformIO Core. Please be patient and let the installation complete. In the final result PlatformIO IDE will ask you to reload Atom window to apply installed components. Please click on Reload Now. After it PlatformIO IDE is ready for using. Happy coding!

Setting Up the Project

  1. To create a new project choose Menu: PlatformIO > Initialize new Project or update existing or press the corresponding icon in the PlatformIO toolbar as shown in the image below:
../_images/ide-atom-platformio-quick-start-1.png
  1. In the “New Project Menu” choose desired boards (more than one board is allowed) and select a project directory. Then press “Initialize” button:
../_images/ide-atom-platformio-quick-start-2.png
  1. If everything is fine, you should see the success message and project tree in the left panel:
../_images/ide-atom-platformio-quick-start-3.png
  1. Now, let’s create the first project source file: right-click on the folder src and choose New File:
../_images/ide-atom-platformio-quick-start-4.png

Enter filename main.cpp:

../_images/ide-atom-platformio-quick-start-5.png

Copy the next source code to the just created file main.cpp:

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

#ifndef LED_BUILTIN
#define LED_BUILTIN 13
#endif

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

Process Project

PlatformIO IDE proposes different ways to process project (build, clean, upload firmware, run other targets) using:

../_images/ide-atom-platformio-quick-start-6.png
  1. Run Build and you should see green “success” result in the building panel:
../_images/ide-atom-platformio-quick-start-7.png

To upload firmware to the board run Upload.

  1. What is more, you can run specific target or process project environment using Menu: PlatformIO > Run other target... or call targets list from the status bar (bottom, left corner):
../_images/ide-atom-platformio-quick-start-8.png

And select desired target:

../_images/ide-atom-platformio-quick-start-9.png
  1. To run built-in terminal interface choose Menu: PlatformIO > Terminal or press the corresponding icon in the PlatformIO toolbar:
../_images/ide-atom-platformio-quick-start-10.png

It provides you fast access to all set of powerful PlatformIO Core CLI commands:

../_images/ide-atom-platformio-quick-start-11.png
  1. To run built-in “Serial Monitor” choose Menu: PlatformIO > Serial Monitor or press the corresponding icon in the PlatformIO toolbar:
../_images/ide-atom-platformio-quick-start-12.png

It has several settings to adjust your connection:

../_images/ide-atom-platformio-quick-start-13.png

And allows you to communicate with your board in an easy way:

../_images/ide-atom-platformio-quick-start-14.png

User Guide

PlatformIO Toolbar

PlatformIO IDE Toolbar contains the quick access button to the popular commands. Each button contains hint (delay mouse on it).

../_images/ide-atom-platformio-toolbar.png
  • PlatformIO: Build
  • PlatformIO: Upload
  • PlatformIO: Clean
  • ||
  • Initialize new PlatformIO Project or update existing...
  • Add/Open Project Folder...
  • Find in Project...
  • ||
  • Terminal
  • Library Manager
  • Serial Monitor
  • ||
  • Settings
  • PlatformIO Documentation

Building / Uploading / Targets

  • cmd-alt-b / ctrl-alt-b / f9 builds project without auto-uploading.
  • cmd-alt-u / ctrl-alt-u builds and uploads (if no errors).
  • cmd-alt-c / ctrl-alt-c cleans compiled objects.
  • cmd-alt-t / ctrl-alt-t / f7 run other targets (Upload using Programmer, Upload SPIFFS image, Update platforms and libraries).
  • cmd-alt-g / ctrl-alt-g / f4 cycles through causes of build error.
  • cmd-alt-h / ctrl-alt-h / shift-f4 goes to the first build error.
  • cmd-alt-v / ctrl-alt-v / f8 toggles the build panel.
  • escape terminates build / closes the build window.

More options Menu: PlatformIO > Settings > Build.

Intelligent Code Completion

PlatformIO IDE uses clang for the Intelligent Code Completion. To install it or check if it is already installed, please follow to step 2. Clang for Intelligent Code Completion from Installation guide.

Warning

The libraries which are added/installed after initializing process will not be reflected in code linter. You need Menu: PlatformIO > Rebuild C/C++ Project Index (Autocomplete, Linter).

Smart Code Linter

PlatformIO IDE uses PlatformIO’s pre-built GCC toolchains for Smart Code Linter and rapid professional development. The configuration data are located in .gcc-flags.json. This file will be automatically created and preconfigured when you initialize project using Menu: PlatformIO > Initialize new PlatformIO Project or update existing....

Warning

If some libraries are not visible in PlatformIO IDE for Atom and Code Completion or Code Linting does not work properly, please perform Menu: PlatformIO > Rebuild C/C++ Project Index (Autocomplete, Linter)

Error

If you have error like linter-gcc: Executable not found and "***/.platformio/packages/toolchain-atmelavr/bin/avr-g++" not found please Menu: PlatformIO > Initialize new PlatformIO Project or update existing....

Install Shell Commands

To install platformio and pio shell commands please use Menu: PlatformIO > Install Shell Commands. It will allow you to call PlatformIO from other process, terminal and etc.

Known issues

Smart Code Linter is disabled for Arduino files

Smart Code Linter is disabled by default for Arduino files (*.ino and .pde) because they are not valid C/C++ based source files:

  1. Missing includes such as #include <Arduino.h>
  2. Function declarations are omitted.

There are two solutions:

Convert Arduino file to C++ manually

For example, we have the next Demo.ino file:

void setup () {
    someFunction(13);
}

void loop() {
    delay(1000);
}

void someFunction(int num) {
}

Let’s convert it to Demo.cpp:

  1. Add #include <Arduino.h> at the top of the source file
  2. Declare each custom function (excluding built-in, such as setup and loop) before it will be called.

The final Demo.cpp:

#include <Arduino.h>

void someFunction(int num);

void setup () {
    someFunction(13);
}

void loop() {
    delay(1000);
}

void someFunction(int num) {
}

Force Arduino file as C++

To force Smart Code Linter to use Arduino files as C++ please

  1. Open .gcc-flags.json file from the Initialized/Imported project and add -x c++ flag at the beginning of the value of gccDefaultCppFlags field:
{
  "execPath": "...",
  "gccDefaultCFlags": "...",
  "gccDefaultCppFlags": "-x c++ -fsyntax-only ...",
  "gccErrorLimit": 15,
  "gccIncludePaths": "...",
  "gccSuppressWarnings": false
}
  1. Perform all steps from Convert Arduino file to C++ manually (without renaming to .cpp).

Frequently Asked Questions

Keep build panel visible

PlatformIO IDE hides build panel on success by default. Nevertheless, you can keep it visible all time. Please follow to Menu: PlatformIO > Settings > Build and set Panel Visibility to Keep Visible.

Key-bindings (toggle panel):

  • cmd+alt+v - Mac OS X
  • ctrl+alt+v - Windows/Linux

Automatically save on build

If you want automatically save all edited files when triggering a build, please follow to Menu: PlatformIO > Settings > Build and check Automatically save on build.

Jump to Declaration

Click on a function/include, press F3 and you will be taken directly to the declaration for that function.

Uninstall Atom with PlatformIO IDE

Here’s how to uninstall the PlatformIO IDE for multiple OS.

Windows

  1. Uninstall Atom using “Start > Control Panel > Programs and Features > Uninstall”
  2. Remove C:\Users\<user name>\.atom folder (settings, packages, etc...)
  3. Remove C:\Users\<user name>\AppData\Local\atom folder (application itself)
  4. Remove C:\Users\<user name>\AppData\Roaming\Atom folder (cache, etc.)

macOS

Run these commands in system Terminal

rm -rf ~/.atom
rm /usr/local/bin/atom
rm /usr/local/bin/apm
rm -rf /Applications/Atom.app
rm ~/Library/Preferences/com.github.atom.plist
rm ~/Library/Application\ Support/com.github.atom.ShipIt
rm -rf ~/Library/Application\ Support/Atom
rm -rf ~/Library/Saved\ Application\ State/com.github.atom.savedState
rm -rf ~/Library/Caches/com.github.atom
rm -rf ~/Library/Caches/Atom

Linux

Run these commands in system Terminal

rm /usr/local/bin/atom
rm /usr/local/bin/apm
rm -rf ~/atom
rm -rf ~/.atom
rm -rf ~/.config/Atom-Shell
rm -rf /usr/local/share/atom/

Articles / Manuals

See a full list with Articles about us.