platformio.ini (configuration file)
Each PlatformIO project has a configuration file named platformio.ini in the root directory for the project.
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.
Multiple value options can be specified in two ways:
- Split values with “, ” (comma + space)
- Multi-line format, where each new line starts with at least two spaces
there are two main sections
1- PlatformIO Core (CLI) settings: Section [platformio]
2- Environment settings: Section [env]
[platformio]
description : Short description of the project
default_envs : The platformio run command processes all environments [env:***] by default if the platformio run --environment option is not specified.
extra_configs : This option allows extending a base “platformio.ini” (Project Configuration File) with extra configuration files.
Base “platformio.ini”
[platformio]
description = this is new project
default_envs = esp32dev
extra_configs =
extra_envs.ini
extra_debug.ini
; Global data for all [env:***]
[env]
platform = espressif32
framework = espidf
; Custom data group
; can be use in [env:***] via ${common.***}
[common]
debug_flags = -D RELEASE
lib_flags = -lc -lm
[env:esp-wrover-kit]
board = esp-wrover-kit
build_flags = ${common.debug_flags}
extra_envs.ini
[env:esp32dev]
board = esp32dev
build_flags = ${common.lib_flags} ${common.debug_flags}
[env:lolin32]
platform = espressif32
framework = espidf
board = lolin32
build_flags = ${common.debug_flags}
src_dir: The path to the project’s directory with source code. Default: “Project/src”
lib_dir : You can put your own/private libraries here. The source code of each library should be placed in a separate directory Default: “Project/data”
For example, see how the Foo and Bar libraries are organized:
|--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>
[env]
Each project may have multiple configuration environments defining the available project tasks for building, programming, debugging, unit testing, device monitoring, library dependencies, etc.
Common [env] : An optional configuration environment with common options that will be shared between all [env:NAME] environments in the platform.ini file.
example:
[env]
platform = ststm32
framework = stm32cube
board = nucleo_l152re
lib_deps = Dep1, Dep2
[env:release]
build_flags = -D RELEASE
lib_deps =
${env.lib_deps}
Dep3
[env:debug]
build_type = debug
build_flags = -D DEBUG
lib_deps = DepCustom
Environment [env:NAME] : A section with an env: prefix defines a working environment for platformio run, platformio test, platformio check, platformio debug and other commands. Multiple [env:NAME] environments with different NAME are allowed. Every project must define at least one working environment.
Each environment must have a unique NAME. The valid chars for NAME are letters a-z, numbers 0-9, special char _ (underscore). For example, [env:hello_world].
you can use options inside [env] the next link for all available options
https://docs.platformio.org/en/latest/projectconf/section_env.html#options
Dynamic variables
Dynamic variables (interpolations) are useful when you have a custom configuration data between build environments. For examples, extra build_flags or project dependencies lib_deps.
Each variable should have a next format: ${<section>.<option>}, where <section> is a value from [<section>] group, and <option> is a first item from pair <option> = value.
You can inject system environment variable using sysenv as a section. For example, ${sysenv.HOME}.
- Variable can be applied only for the option’s value
- Multiple variables are allowed
- The Section [platformio] and Section [env] sections are reserved and could not be used as a custom section. Some good section names might be
extra or custom.
[env]
; Unix
lib_extra_dirs = ${sysenv.HOME}/Documents/Arduino/libraries
; Windows
lib_extra_dirs = ${sysenv.HOMEDRIVE}${sysenv.HOMEPATH}\Documents\Arduino\libraries
; You MUST inject these options into [env:] section
; using ${extra.***} (see below)
[extra]
build_flags = -D VERSION=1.2.3 -D DEBUG=1
lib_deps_builtin =
SPI
Wire
lib_deps_external = ArduinoJson@>5.6.0
[env:uno]
platform = atmelavr
framework = arduino
board = uno
build_flags = ${extra.build_flags}
lib_deps =
${extra.lib_deps_builtin}
${extra.lib_deps_external}
[env:nodemcuv2]
platform = espressif8266
framework = arduino
board = nodemcuv2
build_flags = ${extra.build_flags} -Wall
lib_deps =
${extra.lib_deps_builtin}
${extra.lib_deps_external}
PubSubClient@2.6
OneWire
; Keep sensitive data in environment variables
;
; Unix
; export WIFI_SSID='\"my\ ssid\ name\"'
; export WIFI_PASS='\"my\ password\"'
;
; Windows
; set WIFI_SSID='"my ssid name"'
; set WIFI_PASS='"my password"'
[env:esp32dev]
extends = env:nodemcuv2
platform = espressif32
board = esp32dev
build_flags =
-DWIFI_SSID=${sysenv.WIFI_SSID}
-DWIFI_PASS=${sysenv.WIFI_PASS}
