Advanced Scripting¶

New in version 3.4.1.

Warning

Advanced Scripting is recommended for Advanced Users and requires Python language knowledge.

We highly recommend to take a look at Dynamic build flags option where you can use any programming language. Also, this option is useful if you need to apply changes to the project before building/uploading process:

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

More details Dynamic build flags.

PlatformIO Build System allows to launch custom extra_scripts (based on SCons software construction tool) while processing environment. For more details please follow to “Construction Environments” section of SCons documentation.

Warning

You can not run/debug these scripts directly with Python Interpreter. They will be loaded automatically when you processing project environment using platformio run command.

There are 2 type of extra scripts:

PRE - executes before a main script of Development Platforms
POST - executes after a main script of Development Platforms

Multiple extra scripts are allowed. Please split them via “, ” (comma + space) in the same line or use multi-line values.

For example, Project Configuration File platformio.ini

[env:my_env_1]
platform = ...
; without prefix, POST script
extra_scripts = post_extra_script.py

[env:my_env_2]
platform = ...
extra_scripts = pre:pre_extra_script1.py, pre:pre_extra_script2.py

[env:my_env_3]
platform = ...
extra_scripts =
  pre:pre_extra_script.py
  post:post_extra_script1.py
  post_extra_script2.py

This option can be set by global environment variable PLATFORMIO_EXTRA_SCRIPTS.

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.

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) or env.AddPreAction(target, [callback1, callback2, ...]) function. A first argument target can be a name of target that is passed using platformio run --target command, a name of built-in targets (buildprog, size, upload, program, buildfs, uploadfs, uploadfsota) or path to file which PlatformIO processes (ELF, HEX, BIN, OBJ, etc.).

Examples

extra_script.py file is located on the same level as platformio.ini.

platformio.ini:

[env:pre_and_post_hooks]
extra_scripts = extra_script.py

extra_script.py:

Import("env")

#
# Dump build environment (for debug)
# print env.Dump()
#

#
# 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/${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")
)

Extra Linker Flags without `-Wl,` prefix ¶

Sometimes you need to pass extra flags to GCC linker without Wl,. You could use 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:

platformio.ini:

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

extra_script.py (place it near platformio.ini):

Import('env')

#
# Dump build environment (for debug)
# print env.Dump()
#

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

Custom Uploader ¶

Example, specify own upload command for Atmel AVR:

platformio.ini:

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

extra_script.py:

Import('env')
from base64 import b64decode

#
# Dump build environment (for debug)
# print env.Dump()
#

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

# uncomment line below to see environment variables
# print ARGUMENTS

Custom firmware/program name ¶

Sometime is useful to have a different firmware/program name in build_dir.

platformio.ini:

[env:env_custom_prog_name]
platform = espressif8266
board = nodemcuv2
framework = arduino
build_flags = -D VERSION=13
extra_scripts = pre:extra_script.py

extra_script.py:

Import("env")

my_flags = env.ParseFlags(env['BUILD_FLAGS'])
defines = {k: v for (k, v) in my_flags.get("CPPDEFINES")}
# print defines

env.Replace(PROGNAME="firmware_%s" % defines.get("VERSION"))

Advanced Scripting¶

Before/Pre and After/Post actions¶

Extra Linker Flags without -Wl, prefix¶

Custom Uploader¶

Custom firmware/program name¶

Before/Pre and After/Post actions ¶

Extra Linker Flags without `-Wl,` prefix ¶

Custom Uploader ¶

Custom firmware/program name ¶