Frequently Asked Questions¶

General¶

Install Python Interpreter¶

PlatformIO Core (CLI) is written in Python that is installed by default on the all popular OS except Windows.

Please navigate to official website and Download the latest Python and install it. Please READ NOTES BELOW.

macOS:

Please read the “Important Information” displayed during installation for information about SSL/TLS certificate validation and the running the “Install Certificates.command”.

If you do not install SSL/TLS certificates, PlatformIO will not be able to download dependent packages, libraries, and toolchains.

Windows:

Please select Add Python to Path (see below), otherwise, python command will not be available.

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:

1. Missing includes such as #include <Arduino.h>

2. Function declarations are omitted.

In this case, code completion and code linting do not work properly or are 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:

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

Finish.

Program Memory Usage¶

PlatformIO calculates firmware/program memory usage based on the next 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 the source code. For instance, a variable defined as static int i; would be contained in the BSS segment.

The rough calculation could be done as:

• PROGRAM (Flash) = .text + .data

• DATA (RAM) = .bss + .data

If you need to print all memory sections and addresses, please use pio run --verbose command.

Recommended for reading:

• https://en.wikipedia.org/wiki/Data_segment

• text, data and bss: Code and Data Size Explained

Advanced Serial Monitor with UI¶

PlatformIO Core provides CLI version (pio device monitor) of Serial Monitor. If you need advanced instrument with a rich UI, we recommend free and multi-platform CoolTerm serial port terminal application.

Custom SCons command-line options¶

PlatformIO is built on top of the open-source software construction tool called SCons. SCons has many useful command-line options that control its behavior and may come in handy to know the exact internal processes happening in SCons when it builds a target. For example:

• --dry-run configures SCons to print the commands that would be executed to build any target, but do not execute the commands.

• --tree=all forces SCons to print file dependency tree including implicit and ignored dependencies

• --debug=explain will print an explanation of why SCons decides to (re-)build the targets it selects for building.

The list of available command-line options can be found in the official SCons documentation.

The easiest way to pass extra command-line options to the SCons build system used in PlatformIO is via the external SCONSFLAGS environment variable:

# POSIX shell
export SCONSFLAGS="--tree=all"

# Windows CMD
C:\Users\foo> set SCONSFLAGS=--dry-run

Troubleshooting¶

pip uninstall platformio

# if you used macOS "brew"
brew uninstall platformio

# Recommended
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/master/scripts/99-platformio-udev.rules | sudo tee /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

sudo service udev restart

# or

sudo udevadm control --reload-rules
sudo udevadm trigger

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

sudo usermod -a -G uucp $USER
sudo usermod -a -G lock $USER