Frequently Asked Questions¶

Note

We have a big database with Frequently Asked Questions in our Community Forums. Please have a look at it.

General ¶

What is `.pioenvs` directory ¶

Please refer to envs_dir.

Command completion in Terminal ¶

Bash completion ¶

Bash completion support will complete subcommands and parameters. To enable Bash completion for platformio subcommands you need to put into your .bashrc:

eval "$(_PLATFORMIO_COMPLETE=source platformio)"
eval "$(_PLATFORMIO_COMPLETE=source pio)"

ZSH completion ¶

To enable zsh completion please run these commands:

autoload bashcompinit && bashcompinit
eval "$(_PLATFORMIO_COMPLETE=source platformio)"
eval "$(_PLATFORMIO_COMPLETE=source pio)"

Note

For permanent command completion you need to place commands above to ~/.bashrc or ~/.zshrc file.

Install Python Interpreter ¶

PlatformIO Core is written in Python that 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

Install PIO Core Shell Commands ¶

PlatformIO Core consists of 2 standalone tools in a system:

platformio or pio (short alias) - User Guide
piodebuggdb - alias of platformio debug

If you have PlatformIO IDE already installed, you do not need to install PlatformIO Core separately. Just link these tools with your shell:

Unix ¶

Please open system Terminal paste these commands (MAY require administrator access sudo)

ln -s ~/.platformio/penv/bin/platformio /usr/local/bin/platformio
ln -s ~/.platformio/penv/bin/pio /usr/local/bin/pio
ln -s ~/.platformio/penv/bin/piodebuggdb /usr/local/bin/piodebuggdb

Windows ¶

Please read one of these instructions How do I set or change the PATH system variable?

You need to edit system environment variable called Path and append C:\Users\{username}\.platformio\penv\Scripts; path in the beginning of a list (please replace {username} with your account name).

Convert Arduino file to C++ manually ¶

Some Cloud & Standalone IDE doesn’t support Arduino files (*.ino and .pde) because they are not valid C/C++ based source files:

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

In this case, code completion and code linting does not work properly or disabled. To avoid this issue you can manually convert your INO files to CPP.

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:

Add #include <Arduino.h> at the top of the source file
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) {
}

PlatformIO IDE ¶

Please refer to PlatformIO IDE Frequently Asked Questions.

Before/Pre and After/Post build actions ¶

PlatformIO Build System has rich API that allows to attach different pre-/post actions (hooks). See features of extra_script option for Project Configuration File platformio.ini.

Troubleshooting ¶

Installation ¶

Multiple PIO Cores in a system ¶

Multiple standalone PlatformIO Core in a system could lead to a different issues. We highly recommend to keep one instance of PIO Core or use built-in PIO Core in PlatformIO IDE:

PlatformIO IDE for Atom - Menu PlatformIO: Settings > PlatformIO IDE > Use built-in PlatformIO Core

Finally, if you have a standalone PlatformIO Core in a system, please open system Terminal (not PlatformIO IDE Terminal) and uninstall obsolete PIO Core:

pip uninstall platformio

# if you used MacOS "brew"
brew uninstall platformio

If you need to have PlatformIO Core globally in a system, please Install PIO Core Shell Commands.

‘platformio’ is not recognized as an internal or external command ¶

If you use PlatformIO IDE, please check in PlatformIO IDE Settings that “Use built-in PIO Core” is enabled.

If you modify system environment variable PATH in your Bash/Fish/ZSH profile, please do not override global PATH. This line export PATH="/my/custom/path" is incorrect. Use export PATH="/my/custom/path":$PATH instead.

[Errno 1] Operation not permitted ¶

Answered in issue #295.

Windows AttributeError: ‘module’ object has no attribute ‘packages’¶

Answered in issue #252.

PlatformIO: command not found || An error “pkg_resources.DistributionNotFound”¶

Please upgrade SetupTools package:

[sudo] pip uninstall setuptools
[sudo] pip install setuptools

# Then re-install PlatformIO
[sudo] pip uninstall platformio
[sudo] pip install platformio

Building ¶

UnicodeDecodeError: Non-ASCII characters found in build environment ¶

KNOWN ISSUE. PlatformIO Core currently does not support projects which contain non-ASCII characters (codes) in a full path or depend on the libraries which use non-ASCII characters in their names.

TEMPORARY SOLUTION

Use PlatformIO IDE, it will automatically install PlatformIO Core in a root of system disk (%DISK%/.platformio) and avoid an issue when system User contains non-ASCII characters
Do not use non-ASCII characters in project folder name or its parent folders.

Also, if you want to place PlatformIO Core in own location, see:

Set PLATFORMIO_HOME_DIR environment variable with own path
Configure custom location per project using home_dir option in Project Configuration File platformio.ini.

Frequently Asked Questions¶

General ¶

What is PlatformIO?¶

What is `.pioenvs` directory ¶

Command completion in Terminal ¶

Bash completion ¶

ZSH completion ¶

Install Python Interpreter ¶

Install PIO Core Shell Commands ¶

Unix ¶

Windows ¶

Convert Arduino file to C++ manually ¶

PlatformIO IDE ¶

Before/Pre and After/Post build actions ¶

Troubleshooting ¶

Installation ¶

Multiple PIO Cores in a system ¶

‘platformio’ is not recognized as an internal or external command ¶

[Errno 1] Operation not permitted ¶

Windows AttributeError: ‘module’ object has no attribute ‘packages’¶

PlatformIO: command not found || An error “pkg_resources.DistributionNotFound”¶

Building ¶

UnicodeDecodeError: Non-ASCII characters found in build environment ¶

ARM toolchain: cc1plus: error while loading shared libraries ¶

Archlinux: libncurses.so.5: cannot open shared object file ¶

Monitoring a serial port breaks upload ¶