PlatformIO

Build & Flash the Firmware with PlatformIO

Installing PlatformIO

NOTICE: Python 3.6 is the minimum supported version.

You can check the getting started page in the PlatformIO site to know how to setup the environment for your platform. There are also some videos on YouTube about it.

Building

For example, to build a binary for Sonoff Basic:

$ pio run -e sonoff-basic

The resulting .bin file can be found at .pio/build/sonoff-basic/firmware.bin

Or, using special generic environment:

$ env ESPURNA_FLAGS="-DITEAD_SONOFF_BASIC" pio run -e esp8266-1m-base

(including any other flags / environment variables, depending on the board you are working with)

For Window's cmd.exe, syntax is a bit different:

> cmd /V /C "set ESPURNA_FLAGS=-DITEAD_SONOFF_BASIC && pio run -e esp8266-1m-base"

Flash your board

Notice This describes serial upload, see OTA page for information about wireless upload and PlatformIO documentation

Wire your board (check the Hardware page) and flash the firmware (with upload):

$ env ESPURNA_FLAGS="-DITEAD_SONOFF_BASIC" pio run -e esp8266-1m-base -t upload

Libraries

PlatformIO will take care of the library dependencies. The first time you run the build process it will fetch and install all the libraries required by ESPurna in the specified versions.

For the most up-to-date list, please see code/platformio.ini lib_deps = ... in the [common] section.

Core libraries:

• Benoit Blanchon's ArduinoJson
• Marvin Roger's AsyncMqttClient ^[1]
• Hristo Gochkov's ESPAsyncTCP
• Hristo Gochkov's ESPAsyncWebServer
• Xose Pérez's EEPROM Rotate
• Fork of Xose Pérez's JustWifi

Optional libraries, depending on specific ..._SUPPORT flags:

• Joël Gähwiler's Arduino MQTT ^[1]
• Nick O'Leary's PubSubClient ^[1]
• Pascal Kurtansky's Brzo I2C ^[2]
• Xose Pérez's FauxmoESP
• Xose Pérez's HLW8012 ^[3]
• Xose Pérez's my92xx ^[4]
• Xose Pérez's NoFUSS
• Mark Szabo (et al.) IrRemoteES8266
• Paul Stoffregen (et al.) OneWire
• Mariusz Kacki's PMS ^[4]
• Randy Simons' RemoteSwitch
• Maxim Prokhorov's fork of Xose Pérez's RPNLib ^[5]
• @1technophile fork of Suat Özgür's RCSwitch ^[6]

Button management and settings storage inspired by:

• Xose Pérez's DebounceEvent
• The PatternAgents (et al.) Embedis

At last, legacy libraries for Core 2.3.0 (deprecated, only matters when building using platform = [email protected]):

• German Martin's NtpCLientLib
• Fork of Michael Maregolis & Paul Stoffregen's Time
• Peter Lerup's ESPSoftwareSerial, pinned to the version 3.4.1>

These libraries are automatically installed once you first try to build the project. But if you are updating to a newer version it's always a good idea to force them to update:

> pio lib update

Customize build settings

platformio.ini format

Please refer to the official PlatformIO documentation for platformio.ini: https://docs.platformio.org/en/latest/projectconf/

ESPurna's platformio.ini has the following structure:

• code/espurna/ is set as source code root directory
• code/platformio_override.ini can be used to override existing or create new sections.
• [common] sections is used to set some variables that later will be used as ${common.variable}
• [env] section implicitly provides keys for every environment, so we don't have to repeat ourselves
• [env:...-base] specifies framework (arduino, only available option), board (upload settings, variant build flags), ldscript (memory regions, flash constants and flash size), platform (PlatformIO build system version) and platform_packages (in case we need to change build tools versions)
• [env:named] extends from the -base environment and sets src_build_flags with our project-specific flags. Common way to specify hardware is to have #if defined(HARDWARE_FLAG) (see code/espurna/config/hardware.h') and add -DHARDWARE_FLAGwhen you need to enable multiple#define` options.

It is important to note that in case of repeating keys:

[env:example]
extends = esp8266-1m-base
src_build_flags = -DMY_CUSTOM_HARDWARE -DUSE_CUSTOM_H

[env:override]
extends = env:example
src_build_flags = -DANOTHER_HARDWARE

When building env:override, -DUSE_CUSTOM_H will not be added to the compiler build flags. To append to the existing variable you would need to explicitly specify the key that you want it to use. For example:

[env:example]
extends = esp8266-1m-base
src_build_flags = -DMY_CUSTOM_HARDWARE -DUSE_CUSTOM_H

[env:override]
extends = esp8266-1m-base
src_build_flags = ${env:example.src_build_flags} -DSOME_OTHER_FLAG=1

build_flags and src_build_flags

• src_build_flags is used only by our project's files
• build_flags sets command line options for project's files, Core and libraries

For example, our [env] sections contains the following flags:

build_flags = -g -w -DNO_GLOBAL_EEPROM -DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH

Where:

• -g add debug information into the resulting .elf file
• -w suppresses build warnings for libraries and Core
• -DNO_GLOBAL_EEPROM is a compatibility flag that disables Core built-in EEPROM library which conflicts with the EEPROM_Rotate. (WARNING removing it will cause build to fail with recent Core versions, unless you also change board_build.ldscript to the value that will use the .ld file from the Core, see tools/sdk/ld)
• -DPIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH sets lwipv2 variant to 1460 MSS option, see https://docs.platformio.org/en/latest/platforms/espressif8266.html#lwip-variant and / or https://github.com/esp8266/Arduino/blob/9845deb2832bb28bf355d5ff652eb7908977b443/tools/platformio-build.py#L199-L244 for the upstream configuration options.

Any environment that wants to modify build flags needs to explicitly specify the existing build_flags variable as build_flags = ${common.build_flags} -DLIBRARY_CUSTOM_FLAG=12345 -DPIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK221.

Custom environment

If you want to modify the stock configuration but you don't want to touch the repo files you can create a brand new environment in the code/platformio_override.ini:

[env:my-environment]
extends = esp8266-1m-base
src_build_flags = -DITEAD_SONOFF_BASIC -DDHT_SUPPORT=1

custom.h

Add -DUSE_CUSTOM_H to src_build_flags and create code/espurna/config/custom.h. For example:

#define WEB_EMBEDDED 0
#define NTP_SERVER              "it.pool.ntp.org"
#define MQTT_TOPIC              "my/topic"
#define DOMOTICZ_ENABLED 1
#define ALEXA_SUPPORT 0

(see code/espurna/config/general.h and code/espurna/config/sensor.h for available flags)

It is also possible to add flag through command line by setting OS environment variables PLATFORMIO_SRC_BUILD_FLAGS and PLATFORMIO_BUILD_FLAGS, for src_build_flags and build_flags respectively:

export PLATFORMIO_SRC_BUILD_FLAGS="-DUSE_CUSTOM_H"

We also provide a ESPURNA_FLAGS OS environment variable that is used by the OTA:

export ESPURNA_FLAGS="-DUSE_CUSTOM_H"

ESPURNA_FLAGS is interchangeable with the PLATFORMIO_SRC_BUILD_FLAGS and both will append flags into the existing src_build_flags contents.

Advanced options

-DDISABLE_POSTMORTEM_STACKDUMP (build_flags / src_build_flags option)

Used to disable serial print of postmortem stack dump after a board crashes. This functionality is part of the Arduino Core, so we build a dummy file with an empty printf function and replace the reference to printf in the resulting .o file. Kind of a hack, this should probably be configured in the Core itself. But, we need to write a patch for that.

ESPURNA_PIO_PATCH_ISSUE_1610 (OS environment variable)

Temporary solution for the https://github.com/xoseperez/espurna/issues/1610, ATM this option is only used in CI to build release .bin files

ESPURNA_PIO_SHARED_LIBRARIES (OS environment variable)

Before building the source, PIO build system will call pio lib -d <destination dir> install <platformio.ini lib_deps contents>. This was introduces as a workaround for the following change in PlatformIO 4.0:

• Library Management
  Switched to workspace .pio/libdeps folder for project dependencies instead of .piolibdeps"

• In CI, destination dir is set to ~/.platformio/lib
• Otherwise, destination is set to ${common.shared_libdeps_dir}

ESPURNA_BUILD_SINGLE_SOURCE (OS environment variable)

Combine every .cpp into a single file to significantly speed up compilation process. This will also result in a reduced .bin size (~7KB smaller). ATM this option is only used in CI to build release .bin files

ESPURNA_FLAGS, ESPURNA_IP, ESPURNA_AUTH, ESPURNA_BOARD (OS environment variables)

• ESPURNA_IP flags upload type as OTA (when using -t upload) and adds --ip=$ESPURNA_IP to the espota.py arguments list
• ESPURNA_AUTH adds --auth=$ESPURNA_AUTH to the espota.py arguments list (depends on ESPURNA_IP)
• ESPURNA_FLAGS adds it's contents into the projects build flags (modify src_build_flags for the same result)
• (legacy) ESPURNA_BOARD updates build flags with -D$ESPURNA_BOARD. This was used previously as a platformio.ini substitution, but is no longer used and will be removed in the future.

---

¹ See MQTT configuration.
² See I2C configuration.
³ See Sensors configuration.
⁴ See Lights configuration.
⁵ See RPN Rules configuration.
⁶ See RFBridge configuration.