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 # or ; 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, external libraries, 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

This directory is used to store external libraries downloaded by Library Manager.

A default value is %home_dir%/lib.

This option can be overridden by global environment variable PLATFORMIO_LIB_DIR.

Note

You can put here your own/private libraries. The source code of each library should be placed in separate directory. For example, %lib_dir%/private_lib/[here are source files].

src_dir

A path to project’s source directory. PlatformIO uses it for platformio run command.

A default value is src which 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

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 which 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 environmets 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 which means that folder is located in the root of project.

This option can be overridden by global environment variable PLATFORMIO_DATA_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

framework

Framework type.

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.

Building 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

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/>, which 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.

Example, specify own upload command for Platform atmelavr:

platformio.ini:

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

extra_script.py:

from SCons.Script import DefaultEnvironment

env = DefaultEnvironment()

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

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

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 curent build environment
platformio run --target envdump

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

Uploading 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 serialports 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_install

Specify dependent libraries which should be installed before environment process. The only library IDs are allowed. Multiple libraries can be passed using comma , sign.

You can obtain library IDs using platformio lib search command.

Example:

[env:depends_on_some_libs]
lib_install = 1,13,19

lib_use

Specify libraries which should be used by Library Dependency Finder (LDF) with the highest priority.

Example:

[env:libs_with_highest_priority]
lib_use = OneWire_ID1,SPI

lib_ignore

Specify libraries which should be ignored by Library Dependency Finder (LDF)

Example:

[env:ignore_some_libs]
lib_ignore = SPI,EngduinoV3_ID123

lib_dfcyclic

Control cyclic (recursive) behavior for Library Dependency Finder (LDF). By default, this option is turned OFF (lib_dfcyclic=False) and means that LDF will find only libraries which are included in source files from the project src_dir.

If you want to enable cyclic (recursive, nested) search, please set this option to True. Founded library will be treated like a new source files and LDF will search dependencies for it.

Example:

[env:libs_with_enabled_ldf_cyclic]
lib_dfcyclic = True

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