neulab/tldr huggingface dataset:
Path to the linker script to be used instead of the one defined by a framework. This is useful for specifying a modified linker script, for example, when an application requires a special memory section for a bootloader.
More options You can override any board option declared in manifest file using the next format board_{OBJECT.PATH}, where {OBJECT.PATH} is an object path in JSON manifest. Please navigate to "boards" folder of PlatfomIO development platforms and open JSON file to list all available options.
For example, Manifest: Espressif ESP32 Dev Module:
[env:custom_board_options] ; Custom CPU Frequency board_build.f_cpu = 160000000L
; Custom FLASH Frequency board_build.f_flash = 80000000L
; Custom FLASH Mode board_build.flash_mode = qio
; Custom linker script board_build.ldscript = /path/to/ldscript.ld
; Custom maximum program size board_upload.maximum_size = 1310720
Build options • build_type
• build_flags
• Built-in Variables
• Dynamic build flags
• src_build_flags
• build_unflags
• src_filter
• targets
build_type New in version 4.0.
Type: String | Multiple: No | Default: release
See extended documentation for build_configurations.
build_flags Type: String | Multiple: Yes
These flags/options affect the preprocessing, compilation, assembly and linking processes for C and C++ code. All compiler and linker flags can be used. Here is a list of some common options.
In spite of the name, CPPDEFINES rows also applies to the C compiler.
This option can also be set by global environment variable PLATFORMIO_BUILD_FLAGS.
For more detailed information about available flags/options go to:
• Options to Request or Suppress Warnings
• Options for Debugging Your Program
• Options That Control Optimization
• Options Controlling the Preprocessor
• Passing Options to the Assembler
• Options for Linking
• Options for Directory Search
[env:specific_defines] build_flags = -DFOO -DBAR=1 -D BUILD_ENV_NAME=$PIOENV -D CURRENT_TIME=$UNIX_TIME -DFLOAT_VALUE=1.23457e+07
[env:string_defines] build_flags = -DHELLO="World!" '-DWIFI_PASS="My password"' ; Password with special chars: My pass'word -DWIFI_PASS=\"My\ pass\'word\"
[env:specific_inclibs] build_flags = -I/opt/include -L/opt/lib -lfoo
[env:ignore_incremental_builds] ; We dynamically change the value of "LAST_BUILD_TIME" macro, ; PlatformIO will not cache objects build_flags = -DLAST_BUILD_TIME=$UNIX_TIME
NOTE: If you need to control build flags that are specific for debug configuration please refer to projectconf_debug_build_flags.
Built-in Variables You can inject the built-in variables into your build flags, such as:
• $PYTHONEXE, full path to current Python interpreter
• $UNIX_TIME, current time in Unix format
• $PIOENV, name of build environment from projectconf
• $PIOPLATFORM, name of development platform
• $PIOFRAMEWORK, a list of frameworks
• $PROJECT_DIR, project directory
• $PROJECT_CORE_DIR, PlatformIO Core directory, see projectconf_pio_core_dir
• $PROJECT_BUILD_DIR, project build directory per all environments
• $BUILD_DIR, build directory per current environment
See the full list of PlatformIO variables.
Please use target envdump for the platformio run --target command to see ALL variable values for a build environment.
Dynamic build flags PlatformIO allows users to run an external command/script which outputs build flags into STDOUT by prepending the shell command with a ! character. PlatformIO will automatically replace commands with their output when appending flags to build environments.
You can use any shell or programming language.
This external command will be called on each cmd_run command before building/uploading process.
Use cases:
• Macro with the latest VCS revision/tag "on-the-fly"
• Generate dynamic headers (*.h)
• Process media content before generating SPIFFS image
• Make some changes to source code or related libraries
NOTE: If you need more advanced control and would like to apply changes to a PlatformIO Build System environment, please refer to projectconf_advanced_scripting.
[env:generate_flags_with_external_command] build_flags = !cmd_or_path_to_script
; Unix only, get output from internal command build_flags = !echo "-DSOME_MACRO="$(some_cmd arg1 --option1)
Use Case: Create a "PIO_SRC_REV" macro with the latest Git revision
This example includes a separate file named git_rev_macro.py, to be placed in the same directory as platformio.ini.
platformio.ini:
[env:git_revision_macro] build_flags = !python git_rev_macro.py
git_rev_macro.py:
revision = subprocess.check_output(["git", "rev-parse", "HEAD"]).strip() print("-DPIO_SRC_REV=%s" % revision)
src_build_flags Type: String | Multiple: Yes
An option src_build_flags has the same behavior as build_flags but will be applied only for project source files in the projectconf_pio_src_dir directory.
This option can also be set by the global environment variable PLATFORMIO_SRC_BUILD_FLAGS.
build_unflags Type: String | Multiple: Yes
Selectively remove base/initial flags that were set by the development platform.
[env:unflags] build_unflags = -Os -std=gnu++11 build_flags = -O2
src_filter Type: String (Templates) | Multiple: Yes
This option allows one to specify which source files should be included or excluded from projectconf_pio_src_dir for a build process.  Filter supports two templates:
• +<PATH> include template
• -<PATH> exclude template
PATH is relative to projectconf_pio_src_dir. All patterns will be applied in their order of definition.  GLOB Patterns are allowed.
By default, src_filter is predefined to +<*> -<.git/> -<.svn/> -<example/> -<examples/> -<test/> -<tests/>, meaning "include ALL files, then exclude the .git and svn repository folders and the example ... folder.
This option can also be set by the global environment variable PLATFORMIO_SRC_FILTER.
targets Type: String | Multiple: Yes
A list of targets which will be processed by the cmd_run command by default. You can enter more than one target, if separated by comma+space ", ".
The list with available targets is located in platformio run --target.
1. Build a project using Release Configuration, upload the firmware, and start Serial Monitor automatically:
[env:upload_and_monitor] targets = upload, monitor
2. Build a project using Debug Configuration.
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.
Library options SEE ALSO: Please make sure to read ldf guide first.
• lib_deps
• lib_ignore
• lib_extra_dirs
• lib_ldf_mode
• lib_compat_mode
• lib_archive
lib_deps SEE ALSO: Please make sure to read ldf guide first.
Specify project dependencies that should be installed automatically to projectconf_pio_libdeps_dir before environment processing.
If you have multiple build environments that depend on the same libraries, you can use projectconf_dynamic_vars 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 cmd_lib_install command. Please follow to cmd_lib_install for detailed documentation about possible values.
[env:myenv] lib_deps = 13 PubSubClient ArduinoJson@~5.6,!=5.4 https://github.com/gioblu/PJON.git#v2.0 me-no-dev/ESPAsyncTCP IRremoteESP8266=https://github.com/markszabo/IRremoteESP8266/archive/master.zip
lib_ignore SEE ALSO: Please make sure to read ldf guide first.
Specify libraries which should be ignored by Library Dependency Finder.
The correct value for this option is a library name (not folder name). You will see these names in "Library Dependency Graph" when building a project between < and > symbols.
... Library Dependency Finder -> http://bit.ly/configure-pio-ldf LDF MODES: FINDER(chain+) COMPATIBILITY(soft) Collected 54 compatible libraries Scanning dependencies... Dependency Graph |-- <Hash> v1.0 |-- <AsyncMqttClient> v0.8.2 |   |-- <ESPAsyncTCP> v1.1.3 |-- <ESP8266WiFi> v1.0 |-- <ESP Async WebServer> v1.1.1 |   |-- <ESPAsyncTCP> v1.1.3 |   |-- <ESP8266WiFi> v1.0 |   |-- <Hash> v1.0 |   |-- <ArduinoJson> v5.13.1 |-- <ArduinoJson> v5.13.1 |-- <DNSServer> v1.1.0 |   |-- <ESP8266WiFi> v1.0 |-- <Ticker> v1.0 ....
platformio.ini
[env:myenv] ; Single line lib_ignore = AsyncMqttClient, DNSServer
; Multi-line lib_ignore = AsyncMqttClient ESP Async WebServer
lib_extra_dirs SEE ALSO: Please make sure to read ldf guide first.
Type: DirPath | Multiple: Yes
A list with extra directories/storages where ldf will look for dependencies.
This option can also be set by global environment variable PLATFORMIO_LIB_EXTRA_DIRS.
WARNING: This is a not direct path to a library with source code. It should be a path to storage that contains libraries grouped by folders. For example, D:\PlatformIO\extra\libraries but not D:\PlatformIO\extra\libraries\FooLibrary.
[env:myenv] lib_extra_dirs = /common/libraries /iot/libraries
lib_ldf_mode SEE ALSO: Please make sure to read ldf guide first.
Type: String | Multiple: No | Default: chain
This option specifies how does Library Dependency Finder should analyze dependencies (#include directives). See ldf_mode for details and available options.
[env:myenv] ; evaluate C/C++ Preprocessor conditional syntax lib_ldf_mode = chain+
lib_compat_mode SEE ALSO: Please make sure to read ldf guide first.
Type: String | Multiple: No | Default: soft
Library compatibility mode allows one to control strictness of Library Dependency Finder. See ldf_compat_mode for details and available options..
By default, this value is set to lib_compat_mode = soft and means that LDF will check only for framework compatibility.
[env:myenv] ; Checks for the compatibility with frameworks and dev/platforms lib_compat_mode = strict
lib_archive Type: Bool (yes or no) | Multiple: No | Default: yes
Create an archive (*.a, static library) from the object files and link it into a firmware (program). This is default behavior of PlatformIO Build System (lib_archive = yes).
Setting lib_archive = no will instruct PIO Build System to link object files directly (in-line). This could be useful if you need to override weak symbols defined in framework or other libraries.
You can disable library archiving per a custom library using libjson_archive field in library_config manifest.
[env:myenv] lib_archive = no
Upload options • upload_port
• upload_protocol
• upload_speed
• upload_flags
• upload_resetmethod
• upload_command
upload_port Type: String (Pattern) | Multiple: No
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 please use cmd_device_list command.
This option can also be set by global environment variable PLATFORMIO_UPLOAD_PORT.
Please note that you can use Unix shell-style wildcards:
[env:uno] platform = atmelavr framework = arduino ; any port that starts with /dev/ttyUSB upload_port = /dev/ttyUSB*
; COM1 or COM3 upload_port = COM[13]
upload_protocol Type: String | Multiple: No
A protocol that "uploader" tool uses to talk to a board. Please check boards for supported uploading protocols by your board.
upload_speed Type: Integer | Multiple: No
A connection speed (baud rate) which "uploader" tool uses when sending firmware to board.
upload_flags Type: String | Multiple: Yes
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 projectconf_extra_scripts.
This option can also be set by global environment variable PLATFORMIO_UPLOAD_FLAGS.
Please specify each flag/option in a new line starting with minimum 2 spaces.
[env:atmega328pb] platform = atmelavr board = atmega328pb framework = arduino upload_flags = -P$UPLOAD_PORT -b$UPLOAD_SPEED -u -Ulock:w:0xCF:m -Uhfuse:w:0xD7:m -Uefuse:w:0xF6:m -Ulfuse:w:0xE2:m
upload_resetmethod Type: String | Multiple: No
Specify reset method for "uploader" tool. This option isn't available for all development platforms. The only platform_espressif8266 supports it.
upload_command New in version 4.0.
Type: String | Multiple: No
Override default platforms upload command with a custom. You can pass a full upload command with arguments and options or mix with upload_flags.
Default upload commands are declared in build/main.py script file of platforms. See a list with open source platforms => https://github.com/topics/platformio-platform
NOTE: Please note that you can use build variables in upload_command, such as PlatformIO project folders and other runtime configuration. A list with build variables are available by running platformio run --target envdump command.
1. Override default upload command but handle pre-uploading actions (looking for serial port, extra image preparation, etc.). Normally, the pre-configured upload options will be stored in $UPLOADERFLAGS build variable. A classic default upload command for platforms may look as some-flash-bin-tool $UPLOADERFLAGS $SOURCE, where $SOURCE will be replaced by a real program/firmware binary.
$PROJECT_PACKAGES_DIR build variable points to projectconf_pio_packages_dir.
[env:program_via_AVR_ISP] platform = atmelavr framework = arduino board = uno upload_flags = -C $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf -p atmega328p -P $UPLOAD_PORT -b 115200 -c stk500v1 upload_command = avrdude $UPLOAD_FLAGS -U flash:w:$SOURCE:i
2. Override default upload command and skip pre-uploading actions.
[env:program_via_usbasp] platform = atmelavr framework = arduino board = uno upload_flags = -C $PROJECT_PACKAGES_DIR/tool-avrdude/avrdude.conf -p atmega328p -Pusb -c stk500v1 upload_command = avrdude $UPLOAD_FLAGS -U flash:w:$SOURCE:i
; Use ST-util for flashing ; https://github.com/texane/stlink
[env:custom_st_flash] platform = ststm32 framework = stm32cube board = bluepill_f103c6 upload_command = $PROJECT_PACKAGES_DIR/tool-stlink/st-flash write $SOURCE 0x8000000
Monitor options • monitor_port
• monitor_speed
• monitor_filters
• monitor_rts
• monitor_dtr
• monitor_flags
Custom options for cmd_device_monitor command.
monitor_port Type: String | Multiple: No
Port, a number or a device name, or valid URL Handlers.  See platformio device monitor --port. To print all available serial ports please use cmd_device_list command.
[env:custom_monitor_port] ... ; Unix monitor_port = /dev/ttyUSB1
; Windows, COM1 or COM3 monitor_port = COM[13]
; Socket monitor_port = socket://localhost:4444
monitor_speed Type: Integer | Multiple: No | Default: 9600
A monitor speed (baud rate).  See platformio device monitor --baud.
[env:custom_monitor_speedrate] ... monitor_speed = 115200
monitor_filters New in version 4.3.
Apply filters and text transformation for device output. See available filters at cmd_device_monitor_filters.
[env:log_output_to_file_with_timestamp] ... platform = ... monitor_filters = log2file, time, default
monitor_rts Type: Integer (0 or 1) | Multiple: No
A monitor initial RTS line state. See platformio device monitor --rts.
monitor_dtr Type: Integer (0 or 1) | Multiple: No
A monitor initial DTR line state. See platformio device monitor --dtr.
monitor_flags New in version 4.0.
Pass extra flags and options to cmd_device_monitor command. Please note that each flag, option or its value should be passed in a new line. See example below.
Available flags and options are the same which are documented for cmd_device_monitor command.
[env:extra_monitor_flags] platform = ... board = ... monitor_flags= --parity N --encoding hexlify
Check options SEE ALSO: Please make sure to read piocheck guide first.
• check_tool
• check_patterns
• check_flags
• check_severity
check_tool Type: String | Multiple: Yes | Default: cppcheck
A name of the check tool used for analysis. This option is useful when you want to check source code with two or more tools.
See available tools in check_tools.
[env:myenv] platform = ... board = ... check_tool = cppcheck, clangtidy
check_patterns Type: String (Pattern) | Multiple: Yes
This option allows specifying which source files or folders should be included/excluded from the check process. GLOB Patterns are allowed. projectconf_pio_src_dir and projectconf_pio_include_dir folders are checked by default.
Another option for filtering source files is platformio check --pattern command.
[env:custom_check_patterns] platform = ... board = ... check_tool = clangtidy check_patterns = app/sources tests/hardware/*.c
check_flags Type: String | Multiple: Yes
Additional flags to be passed to the tool command line. This option is useful when you want to adjust the check process to fit your project requirements.  By default, the flags are passed to all tools specified in check_tool section. To set individual flags, define tool name at the beginning of the line.
Another option for adding flags is platformio check --flags command.
[env:extra_check_flags] platform = ... board = ... check_tool = cppcheck, clangtidy check_flags = --common-flag cppcheck: --enable=performance --inline-suppr clangtidy: -fix-errors -format-style=mozilla
check_severity Type: String | Multiple: Yes | Default: low, medium, high
This option allows specifying the check_severity types which will be reported by the check_tools.
Another option for filtering source files is platformio check --severity command.
[env:detect_only_medium_or_high_defects] platform = ... board = ... check_severity = medium, high
Test options SEE ALSO: Please make sure to read unit_testing guide first.
• test_filter
• test_ignore
• test_port
• test_speed
• test_transport
• test_build_project_src
test_filter Type: String (Pattern) | Multiple: Yes
Process only the unit_testing tests where the name matches specified patterns.
Also, you can filter some tests using platformio test --filter command.
[env:myenv] test_filter = footest, bartest_*, test[13]
test_ignore Type: String (Pattern) | Multiple: Yes
Ignore unit_testing tests where the name matches specified patterns.
Also, you can ignore some tests using platformio test --ignore command.
[env:myenv] test_ignore = footest bartest_* test[13]
test_port Type: String (Pattern) | Multiple: No
This option specifies 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 cmd_device_list command.
test_speed Type: Integer | Multiple: No | Default: 115200
A connection speed (baud rate) to communicate with a target device.
test_transport Type: String | Multiple: No
A transport type which will be used to read test results from a target device.  See more details at unit_testing_transport.
test_build_project_src Type: Bool (yes or no) | Multiple: No | Default: no
Force unit_testing engine to build project source code from projectconf_pio_src_dir setting test_build_project_src to yes.  More detail about unit_testing_shared_code.
[env:myenv] platform = ... test_build_project_src = yes
Debugging options SEE ALSO: Please make sure to read piodebug guide first.
• debug_tool
• debug_build_flags
• debug_init_break
• debug_init_cmds
• debug_extra_cmds
• debug_load_cmds
• debug_load_mode
• debug_server
• debug_port
• debug_svd_path
debug_tool Type: String | Multiple: No
A name of debugging tool. This option is useful when board supports more than one debugging tool (adapter, probe) or you want to create debugging_tool_custom debugging configuration.
See available tools in debugging_tools.
[env:debug] platform = ... board = ... debug_tool = custom
debug_build_flags New in version 4.2.0.
Type: String | Multiple: Yes | Default: -Og -g2 -ggdb2
These flags/options affect the preprocessing, compilation, assembly and linking processes for C and C++ code.
NOTE: This option might be helpful to adjust the optimization level if firmware with debug information is too big to be uploaded to a target
[env:debug] platform = ... board = ...
; Set optimization level and amount of debug information generated by the compiler debug_build_flags = -O0 -ggdb3 -g3
Other possible flags that might be useful for debugging your application.
debug_init_break Type: String | Multiple: No | Default: tbreak main
An initial breakpoint that makes your program stop whenever a certain point in the program is reached. Default value is set to tbreak main and means creating a temporary breakpoint at int main(...) function and automatically delete it after the first time a program stops there.
• GDB Setting Breakpoints
• GDB Breakpoint Locations
NOTE: Please note that each debugging tool (adapter, probe) has limited number of hardware breakpoints.
If you need more Project Initial Breakpoints, please place them in debug_extra_cmds.
; Examples 1: disable initial breakpoint debug_init_break =
; Examples 2: temporary stop at ``void loop()`` function debug_init_break = tbreak loop
; Examples 3: stop in main.cpp at line 13 debug_init_break = break main.cpp:13
; Examples 4: temporary stop at ``void Reset_Handler(void)`` debug_init_break = tbreak Reset_Handler
debug_init_cmds Type: String | Multiple: Yes | Default: See details...
Initial commands that will be passed to back-end debugger.
PlatformIO dynamically configures back-end debugger depending on a debug environment. Here is a list with default initial commands for the popular debugging_tools.
For example, the custom initial commands for GDB:
[env:debug] platform = ... board = ... debug_init_cmds = target extended-remote $DEBUG_PORT $INIT_BREAK monitor reset halt $LOAD_CMDS monitor init monitor reset halt
debug_extra_cmds Type: String | Multiple: Yes
Extra commands that will be passed to back-end debugger after debug_init_cmds.  For example, add custom breakpoint and load .gdbinit from a project directory for GDB:
[env:debug] platform = ... board = ... debug_extra_cmds = break main.cpp:13 break foo.cpp:100 source .gdbinit
NOTE: Initial Project Breakpoints: Use break path/to/file:LINE_NUMBER to define initial breakpoints for debug environment. Multiple breakpoints are allowed.
To save session breakpoints, please use save breakpoints [filename] command in Debug Console. For example, save breakpoints .gdbinit. Later, this file could be loaded via source [filename] command. See above.
debug_load_cmds New in version 4.0.
Type: String | Multiple: Yes | Default: load
Specify a command which will be used to load program/firmware to a target device. Possible options:
• load - default option
• load [address] - load program at specified address, where "[address]" should be a valid number
• preload - some embedded devices have locked Flash Memory (a few Freescale Kinetis and NXP LPC boards). In this case, firmware loading using debugging client is disabled. preload command instructs piocore to load program/firmware using development platform "upload" method (via bootloader, media disk, etc)
• (empty value, debug_load_cmds =), disables program loading at all.
• custom commands - pass any debugging client command (GDB, etc.)
Sometimes you need to run extra monitor commands (on debug server side) before program/firmware loading, such as flash unlocking or erasing. In this case we can combine service commands with loading and run them before. See example:
[env:debug] platform = ... board = ... debug_load_cmds = monitor flash erase_sector 0 0 11 load
debug_load_mode Type: String | Multiple: No | Default: always
Allows one to control when PlatformIO should load debugging firmware to the end target. Possible options:
• always - load for the each debugging session, default
• modified - load only when firmware was modified
• manual - do not load firmware automatically. You are responsible to pre-flash target with debugging firmware in this case.
debug_server Type: String | Multiple: Yes
Allows one to setup a custom debugging server. By default, boards are pre-configured with a debugging server that is compatible with "on-board" debugging tool (adapter, probe). Also, this option is useful for a debugging_tool_custom debugging tool.
Option format (multi-line):
• First line is an executable path of debugging server
• 2-nd and the next lines are arguments for executable file
[env:debug] platform = ... board = ... debug_server = /path/to/debugging/server arg1 arg2 ... argN
debug_port Type: String | Multiple: No
A debugging port of a remote target. Could be a serial device or network address.  PlatformIO detects it automatically if is not specified.
• localhost:3333
debug_svd_path Type: FilePath | Multiple: No
A custom path to SVD file which contains information about device peripherals.
Advanced options extends New in version 4.1.
This option allows one to inherit configuration from other sections or build environments in projectconf. Multiple items are allowed, split them with , or with a new line.
If you need to extend only a few options from some section, please take a look at projectconf_dynamic_vars.
[strict_ldf] lib_ldf_mode = chain+ lib_compat_mode = strict
[espressi32_base] platform = espressif32 framework = arduino
[env:release] extends = espressi32_base, strict_ldf board = esp32dev build_flags = -D RELEASE
[env:debug] extends = env:release build_type = debug build_flags = -D DEBUG
extra_scripts Type: FilePath | Multiple: Yes
A list of PRE and POST extra scripts.
See details and examples in projectconf_advanced_scripting section.
If you plan to share these scripts with pioremote machine, please put them to projectconf_pio_shared_dir.
Build Configurations New in version 4.0.0.
There are 2 types (projectconf_build_type) of build configuration in PlatformIO:
release Default configuration. A "release" configuration of your firmware/program does not contain symbolic debug information and is optimized for the firmware size or speed (depending on platforms)
debug  A "debug" configuration of your firmware/program is compiled with full symbolic debug information and no optimization. Optimization complicates debugging, because the relationship between source code and generated instructions is more complex.
If you need to build a project in debug configuration, please use one of these options:
• Add projectconf_build_type with debug value to projectconf
• Use target debug for the platformio run --target command.
NOTE: piodebug automatically switches to debug configuration when you do project debugging from pioide or use the cmd_debug command.
To avoid having piodebug rebuild the project, please create a separate build environment that defines build_type = debug. See the example below where the mydebug build environment will be used automatically by piodebug:
[env] platform = ... board = ... framework = ... ... other common configuration
[env:myrelease] some_extra_options = ...
[env:mydebug] build_type = debug some_extra_options = ...
Please note that you can set a default build environment per a project using the projectconf_pio_default_envs option in projectconf_section_platformio.
Dynamic variables Dynamic variables (interpolations) are useful when you have a custom configuration data between build environments. For examples, extra projectconf_build_flags or project dependencies projectconf_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 projectconf_section_platformio and projectconf_section_env sections are reserved and could not be used as a custom section. Some good section names might be extra or custom.
NOTE: If you need to share common configuration options between build environments, please take a look at "Global scope" in projectconf_section_env or projectconf_env_extends option which allows extending of other sections.
[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}
WARNING: Be careful with special characters in system environment variables on Unix systems, especially when they are used as the value for preprocessor directives.  Symbols like $, &, ~, etc must be explicitly escaped, for example:
export WIFI_PASS='\"my\~p\&a\\\$\$\$\$word\"'
Examples NOTE: A full list with project examples can be found in PlatformIO Repository.
Community project examples with platformio.ini:
• MarlinFirmware/Marlin
• xoseperez/espurna
• esphome/esphome
• cyberman54/ESP32-Paxcounter
For more examples, see projectconf_examples.
[platformio] default_envs = nodemcuv2
; You MUST inject these options into [env:] section ; using ${common_env_data.***} (see below) [common_env_data] build_flags = -D VERSION=1.2.3 -D DEBUG=1 lib_deps_builtin = SPI Wire lib_deps_external = ArduinoJson@~5.6,!=5.4 https://github.com/gioblu/PJON.git#v2.0 IRremoteESP8266=https://github.com/markszabo/IRremoteESP8266/archive/master.zip
; Build options build_flags = ${common_env_data.build_flags} -DSSID_NAME=HELLO -DSSID_PASWORD=WORLD
; Library options lib_deps = ${common_env_data.lib_deps_builtin} ${common_env_data.lib_deps_external} https://github.com/me-no-dev/ESPAsyncTCP.git PubSubClient@2.6 OneWire
; Serial Monitor options monitor_speed = 115200 monitor_flags = --encoding hexlify
; Unit Testing options test_ignore = test_desktop
[env:bluepill_f103c8] platform = ststm32 framework = arduino board = bluepill_f103c8
; Build options build_flags = ${common_env_data.build_flags}
; Library options lib_deps = ${common_env_data.lib_deps_external}
; Debug options debug_tool = custom debug_server = JLinkGDBServer -singlerun -if SWD -select USB -port 2331 -device STM32F103C8
Environment variables Environment variables are a set of dynamic named values that can affect the way running processes will behave on a computer. PlatformIO handles variables which start with PLATFORMIO_ prefix.
How to set environment variable?
# Windows set VARIABLE_NAME=VALUE
# Windows GUI -> https://www.youtube.com/watch?v=bEroNNzqlF4
# Unix (bash, zsh) export VARIABLE_NAME=VALUE
# Unix (fish) set -x VARIABLE_NAME VALUE
Contents • General
• Directories
• Building
• Uploading
General PlatformIO uses General environment variables for the common operations/commands.
PlatformIO handles CI variable which is setup by Continuous Integration (Travis, Circle and etc.) systems.  PlatformIO uses it to disable prompts and progress bars. In other words, CI=true automatically setup PLATFORMIO_DISABLE_PROGRESSBAR to true.
PLATFORMIO_AUTH_TOKEN
Allows one to specify Personal Authentication Token that could be used for automatic login in to pioaccount. It is very useful for ci systems and pioremote operations where you are not able manually authorize.
You can get own Personal Authentication Token using cmd_account_token command.
PLATFORMIO_FORCE_ANSI
Force to output ANSI control character even if the output is a pipe (not a tty).  The possible values are true and false. Default is PLATFORMIO_FORCE_ANSI=false.
PLATFORMIO_NO_ANSI
Do not print ANSI control characters.  The possible values are true and false. Default is PLATFORMIO_NO_ANSI=false.
You can also use platformio --no-ansi flag for piocore.
PLATFORMIO_DISABLE_PROGRESSBAR
Disable progress bar for package/library downloader and uploader. This is useful when calling PlatformIO from subprocess and output is a pipe (not a tty).  The possible values are true and false. Default is PLATFORMIO_DISABLE_PROGRESSBAR=false.
Directories PLATFORMIO_CORE_DIR
Allows one to override projectconf option projectconf_pio_core_dir.
PLATFORMIO_GLOBALLIB_DIR
Allows one to override projectconf option projectconf_pio_globallib_dir.
PLATFORMIO_PLATFORMS_DIR
Allows one to override projectconf option projectconf_pio_platforms_dir.
PLATFORMIO_PACKAGES_DIR
Allows one to override projectconf option projectconf_pio_packages_dir.
PLATFORMIO_CACHE_DIR
Allows one to override projectconf option projectconf_pio_cache_dir.
PLATFORMIO_BUILD_CACHE_DIR
Allows one to override projectconf option projectconf_pio_build_cache_dir.
PLATFORMIO_WORKSPACE_DIR
Allows one to override projectconf option projectconf_pio_workspace_dir.
PLATFORMIO_INCLUDE_DIR
Allows one to override projectconf option projectconf_pio_include_dir.
PLATFORMIO_SRC_DIR
Allows one to override projectconf option projectconf_pio_src_dir.
PLATFORMIO_LIB_DIR
Allows one to override projectconf option projectconf_pio_lib_dir.
PLATFORMIO_LIBDEPS_DIR
Allows one to override projectconf option projectconf_pio_libdeps_dir.
PLATFORMIO_BUILD_DIR
Allows one to override projectconf option projectconf_pio_build_dir.
PLATFORMIO_DATA_DIR
Allows one to override projectconf option projectconf_pio_data_dir.
PLATFORMIO_TEST_DIR
Allows one to override projectconf option projectconf_pio_test_dir.
PLATFORMIO_BOARDS_DIR
Allows one to override projectconf option projectconf_pio_boards_dir.
PLATFORMIO_SHARED_DIR
Allows one to override projectconf option projectconf_pio_shared_dir.
PLATFORMIO_REMOTE_AGENT_DIR
Allows one to override platformio remote agent start --working-dir.
PLATFORMIO_LIB_EXTRA_DIRS
Allows one to set projectconf option projectconf_lib_extra_dirs.
Building PLATFORMIO_BUILD_FLAGS
Allows one to set projectconf option projectconf_build_flags.
# Unix: export PLATFORMIO_BUILD_FLAGS=-DFOO export PLATFORMIO_BUILD_FLAGS=-DFOO -DBAR=1 -Wall
# Windows: SET PLATFORMIO_BUILD_FLAGS=-DFOO SET PLATFORMIO_BUILD_FLAGS=-DFOO -DBAR=1 -Wall
WARNING: Consider using projectconf_dynamic_vars instead of PLATFORMIO_BUILD_FLAGS environment variable if additional build flags contain preprocessor directive with special characters ($, &, ~, etc) in its value.
PLATFORMIO_SRC_BUILD_FLAGS
Allows one to set projectconf option projectconf_src_build_flags.
PLATFORMIO_SRC_FILTER
Allows one to set projectconf option projectconf_src_filter.
PLATFORMIO_EXTRA_SCRIPTS
Allows one to set projectconf option projectconf_extra_scripts.
PLATFORMIO_DEFAULT_ENVS
Allows one to set projectconf option projectconf_pio_default_envs.
Uploading PLATFORMIO_UPLOAD_PORT
Allows one to set projectconf option projectconf_upload_port.
PLATFORMIO_UPLOAD_FLAGS
Allows one to set projectconf option projectconf_upload_flags.
Settings Allows one to override PlatformIO settings. You can manage them via cmd_settings command.
PLATFORMIO_SETTING_AUTO_UPDATE_LIBRARIES
Allows one to override setting setting_auto_update_libraries.
PLATFORMIO_SETTING_AUTO_UPDATE_PLATFORMS
Allows one to override setting setting_auto_update_platforms.
PLATFORMIO_SETTING_CHECK_LIBRARIES_INTERVAL
Allows one to override setting setting_check_libraries_interval.
PLATFORMIO_SETTING_CHECK_PLATFORMIO_INTERVAL
Allows one to override setting setting_check_platformio_interval.
PLATFORMIO_SETTING_CHECK_PLATFORMS_INTERVAL
Allows one to override setting setting_check_platforms_interval.
PLATFORMIO_SETTING_ENABLE_CACHE
Allows one to override setting setting_enable_cache.
PLATFORMIO_SETTING_STRICT_SSL
Allows one to override setting setting_strict_ssl.
PLATFORMIO_SETTING_ENABLE_TELEMETRY
Allows one to override setting setting_enable_telemetry.
PLATFORMIO_SETTING_FORCE_VERBOSE
Allows one to override setting setting_force_verbose.
PLATFORMIO_SETTING_PROJECTS_DIR
Allows one to override setting setting_projects_dir.
Advanced Scripting WARNING: Advanced Scripting is recommended for Advanced Users and requires knowledge of the Python language.
WARNING: projectconf_dynamic_build_flags is a highly recommended alternative to advanced scripting, where you can use any programming language. Also, that option is useful if you need to apply changes to the project before the building/uploading process, such as:
Contents • Advanced Scripting
• Launch types
• Construction Environments
• Before/Pre and After/Post actions
• Build Middlewares
• Custom target
• Command shortcut
• Dependent target
• Target with options
• Custom options in platformio.ini
• Split C/C++ build flags
• Extra Linker Flags without -Wl, prefix
• Custom upload tool
• Upload to Cloud (OTA)
• Custom firmware/program name
• Override package files
• Override Board Configuration
• Custom debug flags
The PlatformIO Build System allows the user to extend the build process with custom scripts using the Python interpreter and the SCons construction tool.  Build flags, upload flags, targets, toolchains data and other information are available for modification as SCons Construction Environments.  Custom scripts are included with projectconf_extra_scripts
WARNING: You can not run or debug these scripts manually with a Python interpreter. They will be loaded automatically when the cmd_run command processes the project environment.
Launch types There are two execution orders for extra scripts:
1. PRE - executes before the main script of platforms
2. POST - executes after the main script of platforms
Multiple extra scripts are allowed. Please split them via  ", " (comma + space) in the same line or use multi-line values.
For example, in projectconf:
[env:my_env_1] platform = ... ; Defaults to POST script since no prefix is used extra_scripts = post_extra_script.py
[env:my_env_2] platform = ... extra_scripts = pre:pre_extra_script.py post:post_extra_script1.py post_extra_script2.py
This option can also be set by the global environment variable PLATFORMIO_EXTRA_SCRIPTS.
Construction Environments The PlatformIO Build System uses two built-in construction environments to process each project:
• env, Import("env") - the global construction environment used for the platforms and frameworks build scripts, upload tools, ldf, and other internal operations
• projenv, Import("projenv") - the isolated construction environment used for processing the project source code in projectconf_pio_src_dir. Please note that any projectconf_src_build_flags specified in projectconf will be passed to projenv and not to env.
1. projenv is available only for POST-type scripts
2. Flags passed to env using PRE-type script will affect projenv too.
my_pre_extra_script.py:
Import("env")
# access to global construction environment print(env)
# Dump construction environment (for debug purpose) print(env.Dump())
# append extra flags to global build environment # which later will be used to build: # - project source code # - frameworks # - dependent libraries env.Append(CPPDEFINES=[ "MACRO_1_NAME", ("MACRO_2_NAME", "MACRO_2_VALUE") ])
my_post_extra_script.py:
Import("env", "projenv")
# access to project construction environment print(projenv)
# Dump construction environments (for debug purpose) print(env.Dump()) print(projenv.Dump())
# append extra flags to global build environment # which later will be used to build: # - frameworks # - dependent libraries env.Append(CPPDEFINES=[ "MACRO_1_NAME", ("MACRO_2_NAME", "MACRO_2_VALUE") ])
# append extra flags to only project build environment projenv.Append(CPPDEFINES=[ "PROJECT_EXTRA_MACRO_1_NAME", ("ROJECT_EXTRA_MACRO_2_NAME", "ROJECT_EXTRA_MACRO_2_VALUE") ])
See examples below how to import construction environments and modify existing data or add new.
Before/Pre and After/Post actions The PlatformIO Build System has a rich API that allows one to attach different pre-/post actions (hooks) using env.AddPreAction(target, callback) or env.AddPreAction(target, [callback1, callback2, ...]) function. The first argument target can be the name of a target that is passed using the platformio run --target command, the name of a built-in target (buildprog, size, upload, program, buildfs, uploadfs, uploadfsota) or the path to a file which PlatformIO processes (ELF, HEX, BIN, OBJ, etc.).
The extra_script.py file is located in the same directory as platformio.ini.
[env:pre_and_post_hooks] extra_scripts = post:extra_script.py
extra_script.py:
# access to global build environment print(env)
# access to project build environment (is used source files in "src" folder) print(projenv)
# # Dump build environment (for debug purpose) # print(env.Dump()) #
# # Change build flags in runtime # env.ProcessUnFlags("-DVECT_TAB_ADDR") env.Append(CPPDEFINES=("VECT_TAB_ADDR", 0x123456789))
# # Upload actions #
def before_upload(source, target, env): print("before_upload") # do some actions
# call Node.JS or other script env.Execute("node --version")
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/${PROGNAME}.elf", [callback1, callback2,...]) env.AddPostAction("$BUILD_DIR/${PROGNAME}.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...)
# Custom HEX from ELF env.AddPostAction( "$BUILD_DIR/${PROGNAME}.elf", env.VerboseAction(" ".join([ "$OBJCOPY", "-O", "ihex", "-R", ".eeprom", "$BUILD_DIR/${PROGNAME}.elf", "$BUILD_DIR/${PROGNAME}.hex" ]), "Building $BUILD_DIR/${PROGNAME}.hex") )
Build Middlewares New in version 4.1.
PlatformIO Build System allows you to add middleware functions that can be used for Build Node(Object) construction. This is very useful if you need to add custom flags for the specific file nodes or exclude them from a build process.
There is env.AddBuildMiddleware(callback, pattern) helper which instructs PlatformIO Build System to call callback for each SCons File System Node whose path matches with Unix shell-style "pattern" (wildcards).
If a pattern is omitted, the callback will be called for each File System Node which is added for the build process.
You can add an unlimited number of build middlewares. They will be called in order of registration. Please note, if the first middleware ignores some File Nodes, they will not be passed to the next middleware in chain.
[env:build_middleware] extra_scripts = pre:extra_script.py
# --- Add custom macros for the ALL files which name contains "http" def extra_http_configuration(node): """ `node.name` - a name of File System Node `node.get_path()` - a relative path `node.get_abspath()` - an absolute path """
# do not modify node if file name does not contain "http" if "http" not in node.name: return node
# now, we can override ANY SCons variables (CPPDEFINES, CCFLAGS, etc.,) for the specific file # pass SCons variables as extra keyword arguments to `env.Object()` function # p.s: run `pio run -t envdump` to see a list with SCons variables
return env.Object( node, CPPDEFINES=env["CPPDEFINES"] + [("HTTP_HOST", "device.local"), ("HTTP_PORT", 8080)], CCFLAGS=env["CCFLAGS"] + ["-fno-builtin-printf"] )
env.AddBuildMiddleware(extra_http_configuration)
# --- Replace some file from a build process with another
def replace_node_with_another(node): return env.File("path/to/patched/RtosTimer.cpp")
env.AddBuildMiddleware( replace_node_with_another, "framework-mbed/rtos/RtosTimer.cpp" )
# --- Skip assembly *.S files from build process
def skip_asm_from_build(node): # to ignore file from a build process, just return None return None
env.AddBuildMiddleware(skip_asm_from_build, "*.S")
Custom target There is a list with built-in targets which could be processed using platformio run --target option. You can create unlimited number of the own targets and declare custom handlers for them.
We will use SCons's Alias(alias, [targets, [action]]) , env.Alias(alias, [targets, [action]]) function to declare a custom target/alias.
Command shortcut Create a custom node target (alias) which will print a NodeJS version
[env:myenv] platform = ... ... extra_scripts = extra_script.py
Import("env") env.AlwaysBuild(env.Alias("node", None, ["node --version"]))
Now, run pio run -t node.
Dependent target Sometimes you need to run a command which depends on another target (file, firmware, etc). Let's create an ota target and declare command which will depend on a project firmware. If a build process successes, declared command will be run.
Import("env") env.AlwaysBuild(env.Alias("ota", "$BUILD_DIR/${PROGNAME}.elf", ["ota_script --firmware-path $SOURCE"]))
Now, run pio run -t ota.
Target with options Let's create a simple ping target and process it with platformio run --target ping command:
[env:env_custom_target] platform = ... ... extra_scripts = extra_script.py custom_ping_host = google.com
try: import configparser except ImportError: import ConfigParser as configparser
config = configparser.ConfigParser() config.read("platformio.ini") host = config.get("env_custom_target", "custom_ping_host")
def mytarget_callback(*args, **kwargs): print("Hello PlatformIO!") env.Execute("ping " + host)
env.AlwaysBuild(env.Alias("ping", None, mytarget_callback))
Examples The best examples are PlatformIO development platforms.  Please check builder folder for the main and framework scripts.
Custom options in platformio.ini platformio.ini:
[env:my_env] platform = ... extra_scripts = extra_script.py
custom_option1 = value1 custom_option2 = value2
config = configparser.ConfigParser() config.read("platformio.ini")
value1 = config.get("my_env", "custom_option1") value2 = config.get("my_env", "custom_option2")
Split C/C++ build flags platformio.ini:
extra_script.py (place it near platformio.ini):
# General options that are passed to the C and C++ compilers env.Append(CCFLAGS=["flag1", "flag2"])
# General options that are passed to the C compiler (C only; not C++). env.Append(CFLAGS=["flag1", "flag2"])
# General options that are passed to the C++ compiler env.Append(CXXFLAGS=["flag1", "flag2"])
Extra Linker Flags without -Wl, prefix Sometimes you need to pass extra flags to GCC linker without Wl,. You could use projectconf_build_flags option but it will not work. PlatformIO will not parse these flags to LINKFLAGS scope. In this case, simple extra script will help:
[env:env_extra_link_flags] platform = windows_x86 extra_scripts = extra_script.py
# # Dump build environment (for debug) # print(env.Dump()) #
env.Append( LINKFLAGS=[ "-static", "-static-libgcc", "-static-libstdc++" ] )
Custom upload tool You can override default upload command of development platform using extra script. There is the common environment variable UPLOADCMD which PlatformIO Build System will handle when you platformio run -t upload.
Please note that some development platforms can have more than 1 upload command.  For example, platform_atmelavr has UPLOADHEXCMD (firmware) and UPLOADEEPCMD (EEPROM data).
See examples below:
[env:my_custom_upload_tool] platform = ... ; place it into the root of project or use full path extra_scripts = extra_script.py upload_protocol = custom ; each flag in a new line upload_flags = -arg1 -arg2 -argN
# please keep $SOURCE variable, it will be replaced with a path to firmware
# Generic env.Replace( UPLOADER="executable or path to executable", UPLOADCMD="$UPLOADER $UPLOADERFLAGS $SOURCE" )
# In-line command with arguments env.Replace( UPLOADCMD="executable -arg1 -arg2 $SOURCE" )
# Python callback def on_upload(source, target, env): print(source, target) firmware_path = str(source[0]) # do something env.Execute("executable arg1 arg2")
env.Replace(UPLOADCMD=on_upload)
Custom openOCD command
[env:disco_f407vg] platform = ststm32 board = disco_f407vg framework = mbed