Project Configuration File platformio.ini¶

env_default¶

platformio run command processes all environments [env:***] by default if platformio run --environment option is not specified. env_default allows to define environments which should be processed by default.

Multiple environments are allowed if they are separated with “, ” (comma+space). For example.

[platformio]
env_default = uno, nodemcu

[env:uno]
platform = atmelavr
framework = arduino
board = uno

[env:nodemcu]
platform = espressif8266
framework = arduino
board = nodemcu

[env:teensy31]
platform = teensy
framework = arduino
board = teensy31

[env:lpmsp430g2553]
platform = timsp430
framework = energia
board = lpmsp430g2553
build_flags = -D LED_BUILTIN=RED_LED

home_dir¶

Is used to store platform toolchains, frameworks, global libraries for :ref: ldf, service data and etc. The size of this folder will depend on number of installed development platforms.

A default value is User’s home directory:

• Unix ~/.platformio

• Windows %HOMEPATH%\.platformio

This option can be overridden by global environment variable PLATFORMIO_HOME_DIR.

Example:

[platformio]
home_dir = /path/to/custom/pio/storage

lib_dir¶

You can put here your own/private libraries. The source code of each library should be placed in separate directory, like lib/private_lib/[here are source files]. This directory has the highest priority for Library Dependency Finder (LDF).

A default value is lib that means that folder is located in the root of project.

This option can be overridden by global environment variable PLATFORMIO_LIB_DIR.

For example, see how can be organized Foo and Bar libraries:

|--lib
|  |--Bar
|  |  |--docs
|  |  |--examples
|  |  |--src
|  |     |- Bar.c
|  |     |- Bar.h
|  |--Foo
|  |  |- Foo.c
|  |  |- Foo.h
|- platformio.ini
|--src
   |- main.c

Then in src/main.c you should use:

#include <Foo.h>
#include <Bar.h>

// rest H/C/CPP code

PlatformIO will find your libraries automatically, configure preprocessor’s include paths and build them.

libdeps_dir¶

Internal storage where Library Manager will install project dependencies (lib_deps). A default value is .piolibdeps that means that folder is located in the root of project.

This option can be overridden by global environment variable PLATFORMIO_LIBDEPS_DIR.

lib_extra_dirs¶

A list with global extra directories for a project where Library Dependency Finder (LDF) will look for libraries.

This option has the same behavior as lib_extra_dirs option for a specific build environment defined in [env:] section. The main difference is that the option that is defined in [platofrmio] section will be applied automatically for all [env:] sections.

For the possible values and examples please follow to lib_extra_dirs.

src_dir¶

A path to project’s source directory. PlatformIO uses it for platformio run command. A default value is src that means that folder is located in the root of project.

This option can be overridden by global environment variable PLATFORMIO_SRC_DIR.

envs_dir¶

PlatformIO Build System uses this folder for project environments to store compiled object files, static libraries, firmwares and other cached information. It allows PlatformIO to build source code extremely fast!

You can delete this folder without any risk! If you modify Project Configuration File platformio.ini, then PlatformIO will remove this folder automatically. It will be created on the next build operation.

A default value is .pioenvs that means that folder is located in the root of project.

This option can be overridden by global environment variable PLATFORMIO_ENVS_DIR.

data_dir¶

Data directory to store contents and Uploading files to file system SPIFFS. A default value is data that means that folder is located in the root of project.

This option can be overridden by global environment variable PLATFORMIO_DATA_DIR.

test_dir¶

Directory where Unit Testing engine will look for the tests. A default value is test that means that folder is located in the root of project.

This option can be overridden by global environment variable PLATFORMIO_TEST_DIR.

boards_dir¶

Custom board settings per project. You can change this path with your own. A default value is boards that means that folder is located in the root of project.

By default, PlatformIO looks for boards in this order:

1. Project boards_dir

2. Global home_dir/boards

3. Development platform home_dir/platforms/*/boards.

This option can be overridden by global environment variable PLATFORMIO_BOARDS_DIR.

platform¶

Development Platforms name.

PlatformIO allows to use specific version of platform using Semantic Versioning (X.Y.Z=MAJOR.MINOR.PATCH). Version specifications can take any of the following forms:

• 0.1.2: an exact version number. Use only this exact version

• ^0.1.2: any compatible version (exact version for 0.x.x versions

• ~0.1.2: any version with the same major and minor versions, and an equal or greater patch version

• >0.1.2: any version greater than 0.1.2. >=, <, and <= are also possible

• >0.1.0,!=0.2.0,<0.3.0: any version greater than 0.1.0, not equal to 0.2.0 and less than 0.3.0

Examples:

[env:the_latest_version]
platform = atmelavr

[env:specific_major_version]
platform = atmelavr@^0.1.2

[env:specific_major_and_minor_version]
platform = atmelavr@~0.1.2

framework¶

Frameworks name.

The multiple frameworks are allowed, split them with comma+space “, “.

board¶

PlatformIO has pre-configured settings for the most popular boards. You don’t need to specify board_mcu, board_f_cpu, upload_protocol or upload_speed options. Just define a board type and PlatformIO will pre-fill options described above with appropriate values.

You can find the board type in Boards section of each Development Platforms or using PlatformIO Embedded Boards Explorer.

board_mcu¶

board_mcu is a microcontroller(MCU) type that is used by compiler to recognize MCU architecture. The correct type of board_mcu depends on platform library. For example, the list of board_mcu for “megaAVR Devices” is described here.

The full list of board_mcu for the popular embedded platforms you can find in Boards section of Development Platforms. See “Microcontroller” column.

board_f_cpu¶

An option board_f_cpu is used to define MCU frequency (Hertz, Clock). A format of this option is C-like long integer value with L suffix. The 1 Hertz is equal to 1L, then 16 Mhz (Mega Hertz) is equal to 16000000L.

The full list of board_f_cpu for the popular embedded platforms you can find in Boards section of Development Platforms. See “Frequency” column. You can overclock a board by specifying a board_f_cpu value other than the default.

board_f_flash¶

An option board_f_flash is used to define FLASH chip frequency (Hertz, Clock). A format of this option is C-like long integer value with L suffix. The 1 Hertz is equal to 1L, then 40 Mhz (Mega Hertz) is equal to 40000000L.

This option isn’t available for the all development platforms. The only Platform espressif8266 supports it.

board_flash_mode¶

Flash chip interface mode. This option isn’t available for the all development platforms. The only Platform espressif8266 supports it.

build_flags¶

These flags/options control preprocessing, compilation, assembly and linking processes:

This option can be set by global environment variable PLATFORMIO_BUILD_FLAGS.

Example:

[env:specific_defines]
build_flags = -DFOO -DBAR=1 -DFLOAT_VALUE=1.23457e+07

[env:string_defines]
build_flags = '-DHELLO="World!"' '-DWIFI_PASS="My password"'

[env:specific_inclibs]
build_flags = -I/opt/include -L/opt/lib -lfoo

[env:specific_ld_script]
build_flags = -Wl,-T/path/to/ld_script.ld

[env:generate_flags_with_external_command]
build_flags = !cmd_or_path_to_script

[env:git_revision_macro]
build_flags = !echo "-DPIO_SRC_REV="$(git rev-parse HEAD)

[env:git_revision_macro]
build_flags = !print_git_rev.bat

@echo off
FOR /F "tokens=1 delims=" %%A in ('git rev-parse HEAD') do echo -DPIO_SRC_REV=%%A

src_build_flags¶

An option src_build_flags has the same behavior like build_flags but will be applied only for the project source code from src_dir directory.

This option can be set by global environment variable PLATFORMIO_SRC_BUILD_FLAGS.

build_unflags¶

Remove base/initial flags which were set by development platform.

[env:unflags]
build_unflags = -Os -std=gnu++11
build_flags = -O2

src_filter¶

This option allows to specify which source files should be included/excluded from build process. Filter supports 2 templates:

• +<PATH> include template

• -<PATH> exclude template

PATH MAST BE related from src_dir. All patterns will be applied in theirs order. GLOB Patterns are allowed.

By default, src_filter is predefined to +<*> -<.git/> -<svn/> -<example/> -<examples/> -<test/> -<tests/>, that means “includes ALL files, then exclude .git and svn repository folders, example … folder.

This option can be set by global environment variable PLATFORMIO_SRC_FILTER.

targets¶

A list with targets which will be processed by platformio run command by default. You can enter more than one target separated with “space”.

The list with available targets is located in platformio run --target.

Tip! You can use these targets like an option to platformio run --target command. For example:

# clean project
platformio run -t clean

# dump current build environment
platformio run --target envdump

When no targets are defined, PlatformIO will build only sources by default.

upload_port¶

This option is used by “uploader” tool when sending firmware to board via upload_port. For example,

• /dev/ttyUSB0 - Serial port (Unix-based OS)

• COM3 - Serial port (Windows OS)

• 192.168.0.13 - IP address when using OTA

• /media/disk - physical path to media disk/flash drive (Framework mbed enabled boards)

• D: - physical path to media disk/flash drive (Windows OS).

If upload_port isn’t specified, then PlatformIO will try to detect it automatically.

To print all available serial ports use platformio device list command.

This option can be set by global environment variable PLATFORMIO_UPLOAD_PORT.

Please note that you can use Unix shell-style wildcards:

Example:

[env:uno]
platform = atmelavr
framework = arduino
; any port that stats with /dev/ttyUSB
upload_port = /dev/ttyUSB*

; COM1 or COM3
upload_port = COM[13]

upload_protocol¶

A protocol that “uploader” tool uses to talk to the board.

upload_speed¶

A connection speed (baud rate) which “uploader” tool uses when sending firmware to board.

upload_flags¶

Extra flags for uploader. Will be added to the end of uploader command. If you need to override uploader command or base flags please use extra_script.

This option can be set by global environment variable PLATFORMIO_UPLOAD_FLAGS.

upload_resetmethod¶

Specify reset method for “uploader” tool. This option isn’t available for all development platforms. The only Platform espressif8266 supports it.

lib_deps¶

Specify project dependencies that should be installed automatically to libdeps_dir before environment processing. Multiple dependencies are allowed (multi-lines or separated with comma+space “, “).

If you have multiple build environments that depend on the same libraries, you can use Dynamic variables to use common configuration.

Valid forms

; one line definition (comma + space)
[env:myenv]
lib_deps = LIBRARY_1, LIBRARY_2, LIBRARY_N

; multi-line definition
[env:myenv2]
lib_deps =
  LIBRARY_1
  LIBRARY_2
  LIBRARY_N

The each line with LIBRARY_1... LIBRARY_N will be passed automatically to platformio lib install command. Please follow to platformio lib install for detailed documentation about possible values.

Example:

[env:depends_on_some_libs]
lib_deps =
  13
  PubSubClient
  Json@~5.6,!=5.4
  https://github.com/gioblu/PJON.git#v2.0
  https://github.com/me-no-dev/ESPAsyncTCP.git

lib_ignore¶

Specify libraries which should be ignored by Library Dependency Finder.

The correct value for this option is library name (not folder name). In the most cases, library name is pre-defined in manifest file (library.json, library.properties, module.json). The multiple library names are allowed, split them with comma+space “, “.

There is ability to ignore built-in Framework mbed libraries: mbed-rtos, mbed-events, mbed-fs, mbed-net, mbed-rpc, mbed-dsp, mbed-USBHost, mbed-USBDevice. See full list here.

Example:

[env:ignore_some_libs]
lib_ignore = SPI, Ethernet, mbed-fs

lib_extra_dirs¶

A list with extra directories/storages where Library Dependency Finder (LDF) will look for dependencies. Multiple paths are allowed. Please separate them using comma+space “, “.

This option can be set by global environment variable PLATFORMIO_LIB_EXTRA_DIRS or using global [platformio] section and lib_extra_dirs option.

Example:

[env:custom_lib_dirs]
lib_extra_dirs = /path/to/private/dir1,/path/to/private/dir2

lib_ldf_mode¶

This option specifies how does Library Dependency Finder should analyze dependencies (#include directives). See Dependency Finder Mode for details.

lib_compat_mode¶

Library compatibility mode allows to control strictness of Library Dependency Finder. More details Compatibility Mode.

By default, this value is set to lib_compat_mode = 1 and means that LDF will check only for framework compatibility.

test_ignore¶

Ignore Unit Testing tests where the name matches specified patterns. Multiple names are allowed. Please separate them using comma+space “, “. Also, you can ignore some tests using platformio test --ignore command.

Example

[env:myenv]
test_ignore = footest, bartest_*, test[13]

test_port¶

This option is used as communication interface (Serial/UART) between PlatformIO Unit Testing Engine and target device. For example,

• /dev/ttyUSB0 - Unix-based OS

• COM3 - Windows OS

If test_port isn’t specified, then PlatformIO will try to detect it automatically.

To print all available serial ports use platformio device list command.

extra_script¶

Allows to launch extra script using SCons software construction tool. For more details please follow to “Construction Environments” section of SCons documentation.

This option can be set by global environment variable PLATFORMIO_EXTRA_SCRIPT.

Take a look at the multiple snippets/answers for the user questions:

• #462 Split C/C++ build flags

• #365 Extra configuration for ESP8266 uploader

• #351 Specific reset method for ESP8266

• #247 Specific options for avrdude.

[env:env_extra_link_flags]
platform = windows_x86
extra_script = extra_script.py

Import('env')

env.Append(
  LINKFLAGS=[
      "-static",
      "-static-libgcc",
      "-static-libstdc++"
  ]
)

[env:env_custom_uploader]
platform = atmelavr
extra_script = /path/to/extra_script.py
custom_option = hello

Import('env')
from base64 import b64decode

env.Replace(UPLOADHEXCMD='"$UPLOADER" ' + b64decode(ARGUMENTS.get("CUSTOM_OPTION")) + ' --uploader --flags')

# uncomment line below to see environment variables
# print env.Dump()
# print ARGUMENTS

[env:pre_and_post_hooks]
extra_script = extra_script.py

Import("env")

#
# Upload actions
#

def before_upload(source, target, env):
    print "before_upload"
    # do some actions


def after_upload(source, target, env):
    print "after_upload"
    # do some actions

print "Current build targets", map(str, BUILD_TARGETS)

env.AddPreAction("upload", before_upload)
env.AddPostAction("upload", after_upload)

#
# Custom actions when building program/firmware
#

env.AddPreAction("buildprog", callback...)
env.AddPostAction("buildprog", callback...)

#
# Custom actions for specific files/objects
#

env.AddPreAction("$BUILD_DIR/firmware.elf", [callback1, callback2,...])
env.AddPostAction("$BUILD_DIR/firmware.hex", callback...)

# custom action before building SPIFFS image. For example, compress HTML, etc.
env.AddPreAction("$BUILD_DIR/spiffs.bin", callback...)

# custom action for project's main.cpp
env.AddPostAction("$BUILD_DIR/src/main.cpp.o", callback...)