Project Configuration File platformio.ini

The Project configuration file is named platformio.ini. This is a INI-style file.

platformio.ini has sections (each denoted by a [header]) and key / value pairs within the sections. Lines beginning with ; are ignored and may be used to provide comments.

The sections and their allowable values are described below.

Section [platformio]

A platformio section is used for overriding default configuration options

Note

Relative path is allowed for directory option:

  • ~ will be expanded to user’s home directory
  • ../ or ..\ go up to one folder

Options

home_dir

Is used to store platform toolchains, frameworks, global libraries for :ref: ldf, service data and etc.

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.

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.

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.

Note

This option is useful for people who migrate from Arduino/Energia IDEs where source directory should have the same name like the main source file. See example project with own source directory.

envs_dir

Warning

PLEASE DO NOT EDIT FILES IN THIS FOLDER. PlatformIO will overwrite your changes on the next build. THIS IS A CACHE DIRECTORY.

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.

Note

If you have any problems with building your Project environments which are defined in Project Configuration File platformio.ini, then TRY TO DELETE this folder. In this situation you will remove all cached files without any risk.

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.

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). For example.

[platformio]
env_default = uno, nodemcu

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

[env:nodemcu]
platform = espressif
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

Section [env:NAME]

A section with env: prefix is used to define virtual environment with specific options that will be processed with platformio run command. You can define unlimited numbers of environments.

Each environment must have unique NAME. The valid chars for NAME are

  • letters a-z
  • numbers 0-9
  • special char _ (underscore)

For example, [env:hello_world].

General options

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 , separator.

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 options

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 espressif supports it.

board_flash_mode

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

Build options

build_flags

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

Format Scope Description
-D name CPPDEFINES Predefine name as a macro, with definition 1.
-D name=definition CPPDEFINES The contents of definition are tokenized and processed as if they appeared during translation phase three in a #define directive.
-U name CPPDEFINES Cancel any previous definition of name, either built in or provided with a -D option.
-Wp,option CPPFLAGS Bypass the compiler driver and pass option directly through to the preprocessor
-Wall CCFLAGS Turns on all optional warnings which are desirable for normal code.
-Werror CCFLAGS Make all warnings into hard errors. Source code which triggers warnings will be rejected.
-w CCFLAGS Suppress all warnings, including those which GNU CPP issues by default.
-include file CCFLAGS Process file as if #include "file" appeared as the first line of the primary source file.
-Idir CPPPATH Add the directory dir to the list of directories to be searched for header files.
-Wa,option ASFLAGS, CCFLAGS Pass option as an option to the assembler. If option contains commas, it is split into multiple options at the commas.
-Wl,option LINKFLAGS Pass option as an option to the linker. If option contains commas, it is split into multiple options at the commas.
-llibrary LIBS Search the library named library when linking
-Ldir LIBPATH Add directory dir to the list of directories to be searched for -l.

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:exec_command]
; get VCS revision "on-the-fly"
build_flags = !echo "-DPIO_SRC_REV="$(git rev-parse HEAD)

For more detailed information about available flags/options go to:

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.

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:

Custom Uploader

Example, specify own upload command for Platform atmelavr:

platformio.ini:

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

extra_script.py:

Import('env')

env.Replace(UPLOADHEXCMD='"$UPLOADER" ${ARGUMENTS.get("custom_option")} --uploader --flags')

# uncomment line below to see environment variables
# print env.Dump()
# print ARGUMENTS
Before/Pre and After/Post actions

PlatformIO Build System has rich API that allows to attach different pre-/post actions (hooks) using env.AddPreAction(target, callback) function. A first argument target can be a name of target that is passed using platformio run --target command or path to file which PlatformIO processes (ELF, HEX, BIN, etc.). For example, to call function before HEX file will be created, need to use as a $BUILD_DIR/firmware.hex target value.

The example below demonstrates how to call different functions when platformio run --target is called with upload value. extra_script.py file is located on the same level as platformio.ini.

platformio.ini:

[env:pre_and_post_hooks]
extra_script = extra_script.py

extra_script.py:

Import("env")

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("$BUILD_DIR/firmware.elf", callback...)
# env.AddPostAction("$BUILD_DIR/firmware.hex", callback...)

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

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 options

upload_port

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

  • /dev/ttyUSB0 - Unix-based OS
  • COM3 - Windows OS
  • 192.168.0.13 - IP address when using OTA

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

To print all available serial ports use platformio device command.

This option can be set by global environment variable PLATFORMIO_UPLOAD_PORT.

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 espressif supports it.

Library options

lib_deps

New in version 3.0.

See also

Please make sure to read Library Dependency Finder (LDF) guide first.

Specify project dependencies that should be installed automatically to libdeps_dir before environment processing. Multiple dependencies are allowed (multi-lines).

Valid forms

[env:myenv]
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_force

See also

Please make sure to read Library Dependency Finder (LDF) guide first.

Force Library Dependency Finder to depend on the specified library if it even is not included in the project source code. Also, this library will be processed in the first order.

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 , separator.

Example:

[env:myenv]
lib_force = OneWire, SPI

lib_ignore

See also

Please make sure to read Library Dependency Finder (LDF) guide first.

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 , separator.

Example:

[env:ignore_some_libs]
lib_ignore = SPI, Ethernet

lib_extra_dirs

New in version 3.0.

See also

Please make sure to read Library Dependency Finder (LDF) guide first.

A list with extra directories/storages where Library Dependency Finder will look for dependencies. Multiple paths are allowed. Please separate them using comma , symbol.

This option can be set by global environment variable PLATFORMIO_LIB_EXTRA_DIRS.

Warning

This is a not direct path to library with source code. It should be the path to storage that contains libraries grouped by folders. For example, /extra/lib/storage/ but not /extra/lib/storage/MyLibrary.

Example:

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

lib_ldf_mode

New in version 3.0.

See also

Please make sure to read Library Dependency Finder (LDF) guide first.

Library Dependency Finder starts work from analyzing source files of the project (src_dir) and can work in the different modes (see Dependency Finder Mode).

By default, this value is set to lib_ldf_mode = 2 and means that LDF will parse ALL C/C++ source code of the project and will parse ALL C/C++ source code of the each dependent library (recursively).

lib_compat_mode

New in version 3.0.

See also

Please make sure to read Library Dependency Finder (LDF) guide first.

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 options

test_ignore

New in version 3.0.

See also

Please make sure to read Unit Testing guide first.

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

Pattern Meaning
* matches everything
? matches any single character
[seq] matches any character in seq
[!seq] matches any character not in seq

Example

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

Examples

Note

A full list with project examples can be found in PlatformIO Repository.

  1. Platform atmelavr: Arduino UNO board with auto pre-configured board_* and upload_* options (use only board option) and Arduino Wiring-based Framework
[env:atmelavr_arduino_uno_board]
platform = atmelavr
framework = arduino
board = uno

; enable auto-uploading
targets = upload
  1. Platform atmelavr: Embedded board that is based on ATmega168 MCU with “arduino” bootloader
[env:atmelavr_atmega168_board]
platform = atmelavr
board_mcu = atmega168
board_f_cpu = 16000000L

upload_port = /dev/ttyUSB0
; for Windows OS
; upload_port = COM3
upload_protocol = arduino
upload_speed = 19200

; enable auto-uploading
targets = upload
  1. Upload firmware via USB programmer (USBasp) to Platform atmelavr microcontrollers
[env:atmelavr_usbasp]
platform = atmelavr
framework = arduino
board = pro8MHzatmega328
upload_protocol = usbasp
upload_flags = -Pusb -B5

Then upload firmware using target program for platformio run --target. command. To use other programmers see Upload using Programmer.

  1. Platform ststm32: Upload firmware using GDB script upload.gdb, issue #175
[env:st_via_gdb]
platform = ststm32
board = armstrap_eagle512
upload_protocol = gdb

Also, take a look at this article Armstrap Eagle and PlatformIO.

  1. Platform ststm32: Upload firmware using ST-Link instead mbed’s media disk
[env:stlink_for_mbed]
platform = ststm32
board = disco_f100rb
upload_protocol = stlink