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 build_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 PlatformIO 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 and Unix-like ¶

In Unix and Unix-like systems, there are multiple ways to achieve this.

Method 1 ¶

You can add PlatformIO executables’ directory to the PATH environmental variable. This method will allow you to execute platformio commands from any terminal emulator as long as you’re logged in as the user PlatformIO is installed and configured for.

If you use Bash as your default shell, you can do it by editing either ~/.profile or ~/.bash_profile and adding the following line:

export PATH=$PATH:~/.platformio/penv/bin

If you use Zsh, you can either edit ~/.zprofile and add the code above, or for supporting both, Bash and Zsh, you can first edit ~/.profile and add the code above, then edit ~/.zprofile and add the following line:

emulate sh -c '. ~/.profile'

After everithing’s done, just restart your session (log out and log back in) and you’re good to go.

If you don’t know the difference between the two, check out this page.

Method 2 ¶

Go to the PlatformIO menu → Settings → PlatformIO IDE, scroll down to the Custom PATH for `platformio` command and enter the following: ~/.platformio/penv/bin. After you’ve done that, you’ll need to go to the PlatformIO menu → Settings → PlatformIO IDE Terminal, scroll down to the Toggles section and uncheck the Login Shell checkbox. Finally, restart Atom and check out the result.

Method 3 ¶

You can create system-wide symlinks. This method is not recommended if you have multiple users on your computer because the symlinks will be broken for other users and they will get errors while executing PlatformIO commands. If that’s not a problem, open your system terminal app and 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

After that, you should be able to run PlatformIO from terminal. No restart is required.

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 & Desktop 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) {
}

Firmware memory size explanation: text, data and bss ¶

If project builds successfully, PlatformIO calculates firmware/program memory size by segments:

.text:

The code segment, also known as a text segment or simply as text, is where a portion of an object file or the corresponding section of the program’s virtual address space that contains executable instructions is stored and is generally read-only and fixed size.

.data:

The .data segment contains any global or static variables which have a pre-defined value and can be modified. The values for these variables are initially stored within the read-only memory (typically within .text) and are copied into the .data segment during the start-up routine of the program. Example,

int val = 3;
char string[] = "Hello World";

.bss:

Uninitialized data, is usually adjacent to the data segment. The BSS segment contains all global variables and static variables that are initialized to zero or do not have explicit initialization in source code. For instance, a variable defined as static int i; would be contained in the BSS segment.

The rough calculation for MCU could be done as:

Flash data = .text + .data
RAM data = .bss

For example, build log by Espressif 8266 project:

...
PLATFORM: Espressif 8266 > NodeMCU 1.0 (ESP-12E Module)
SYSTEM: ESP8266 80MHz 80KB RAM (4MB Flash)
...
Compiling .pioenvs/nodemcuv2/src/...
...
Linking .pioenvs/nodemcuv2/firmware.elf
Building .pioenvs/nodemcuv2/firmware.bin
Calculating size .pioenvs/nodemcuv2/firmware.elf
text       data     bss     dec     hex filename
283399     4816   30264  318479   4dc0f .pioenvs/nodemcuv2/firmware.elf

All numbers are in bytes
dec is equal to “.text + .data + .bss”
hex is the dec in hexadecimal format

Flash data = .text + .data = 288215 Bytes = 281 KB (maximum is 4 MB)
RAM data = .bss = 30264 Bytes = 30 KB (maximum is 80 KB)

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 PlatformIO 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

99-platformio-udev.rules ¶

Linux users have to install udev rules for PlatformIO supported boards/devices. The latest version of rules may be found at https://raw.githubusercontent.com/platformio/platformio-core/develop/scripts/99-platformio-udev.rules

This file must be placed at /etc/udev/rules.d/99-platformio-udev.rules (preferred location) or /lib/udev/rules.d/99-platformio-udev.rules (required on some broken systems).

Please open system Terminal and type

# Recommended
sudo curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/scripts/99-platformio-udev.rules > /etc/udev/rules.d/99-platformio-udev.rules

# OR, manually download and copy this file to destination folder
sudo cp 99-platformio-udev.rules /etc/udev/rules.d/99-platformio-udev.rules

Restart “udev” management tool:

sudo service udev restart

# or

sudo udevadm control --reload-rules
sudo udevadm trigger

Ubuntu/Debian users may need to add own “username” to the “dialout” group if they are not “root”, doing this issuing

sudo usermod -a -G dialout $USER
sudo usermod -a -G plugdev $USER

After this file is installed, physically unplug and reconnect your board.

Package Manager ¶

[Error 5] Access is denied ¶

PlatformIO installs all packages to “home_dir/packages” directory. You MUST HAVE write access for this folder. Please note that PlatformIO does not require “sudo”/administrative privileges.

Solution 1: Remove folder ¶

A quick solution is to remove “home_dir/packages” folder and repeat installation/building/uploading again.

Solution 2: Antivirus ¶

Some antivirus tools forbid programs to create files in background. PlatformIO Package Manager does all work in background: downloads package, unpacks archive in temporary folder and moves final files to “home_dir/packages” folder.

Antivirus tool can block PlatformIO, that is why you see “[Error 5] Access is denied”. Try to disable it for a while or add home_dir directory to exclusion/white list.

Solution 3: Run from Terminal ¶

As we mentioned in “Solution 2”, antivirus tools can block background file system operations. Other solution is to run PlatformIO Core from a system terminal.

Open System Terminal, on Windows cmd.exe (not PlatformIO IDE Terminal)

Build project and upload firmware using PlatformIO Core which will download and install all dependent packages:

# Change directory to PlatformIO Project where is located "platformio.ini"
cd path/to/platformio/project

# Force PlatformIO to install all tools
platformio run --target upload

If “platformio” command is not globally available in your environment and you use PlatformIO IDE, please use built-in PlatformIO Core which is located in:

Windows: C:\Users\{username}\.platformio\penv\Scripts\platformio Please replace {username} with a real user name
Unix: ~/.platformio/penv/bin/platformio

Note

You can add platformio and pio commands to your system environment. See Install PlatformIO Core Shell Commands.

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 PlatformIO Core Shell Commands ¶

Unix and Unix-like ¶

Method 1 ¶

Method 2 ¶

Method 3 ¶

Windows ¶

Convert Arduino file to C++ manually ¶

Firmware memory size explanation: text, data and bss ¶

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

99-platformio-udev.rules ¶

Package Manager ¶

[Error 5] Access is denied ¶

Solution 1: Remove folder ¶

Solution 2: Antivirus ¶

Solution 3: Run from Terminal ¶

Solution 4: Manual ¶

Building ¶

UnicodeWarning: Unicode equal comparison failed ¶

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 ¶