Configuration¶

CPU Frequency¶

See board_build.f_cpu option from “platformio.ini” (Project Configuration File)

[env:myenv]
; set frequency to 160MHz
board_build.f_cpu = 160000000L

FLASH Frequency¶

Please use board_build.f_flash option from “platformio.ini” (Project Configuration File) to change a value. Possible values:

• 20000000L

• 26000000L

• 40000000L (default)

• 80000000L

[env:myenv]
; set frequency to 80MHz
board_build.f_flash = 80000000L

FLASH Mode¶

Flash chip interface mode. This parameter is stored in the binary image header, along with the flash size and flash frequency. The ROM bootloader in the ESP chip uses the value of these parameters in order to know how to talk to the flash chip.

Please use board_build.flash_mode option from “platformio.ini” (Project Configuration File) to change a value. Possible values:

• qio

• qout

• dio

• dout

[env:myenv]
board_build.flash_mode = qio

Reset Method¶

You can set custom reset method using upload_resetmethod option from “platformio.ini” (Project Configuration File).

The possible values are:

• ck - RTS controls RESET or CH_PD, DTR controls GPIO0

• wifio - TXD controls GPIO0 via PNP transistor and DTR controls RESET via a capacitor

• nodemcu - GPIO0 and RESET controlled using two NPN transistors as in NodeMCU devkit.

See default reset methods per board.

[env:myenv]
upload_resetmethod = ck

Flash Size¶

Available LD-scripts: https://github.com/esp8266/Arduino/tree/master/tools/sdk/ld

Please open eagle.flash.***.ld file to check how flash is split.

To override default LD script please use board_build.ldscript option from “platformio.ini” (Project Configuration File).

[env:myenv]
board_build.ldscript = eagle.flash.4m.ld

Upload Speed¶

You can set custom upload speed using upload_speed option from “platformio.ini” (Project Configuration File)

[env:myenv]
upload_speed = 9600

lwIP Variant¶

Available variants (macros):

• -D PIO_FRAMEWORK_ARDUINO_LWIP2_LOW_MEMORY v2 Lower Memory (default)

• -D PIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH v2 Higher Bandwidth

• -D PIO_FRAMEWORK_ARDUINO_LWIP2_LOW_MEMORY_LOW_FLASH v2 Lower Memory (no features)

• -D PIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH v2 Higher Bandwidth (no features)

• -D PIO_FRAMEWORK_ARDUINO_LWIP2_IPV6_LOW_MEMORY v2 IPv6 Lower Memory

• -D PIO_FRAMEWORK_ARDUINO_LWIP2_IPV6_HIGHER_BANDWIDTH v2 IPv6 Higher Bandwidth

• -D PIO_FRAMEWORK_ARDUINO_LWIP_HIGHER_BANDWIDTH v1.4 Higher Bandwidth

You can change lwIP Variant by passing a custom macro using project build_flags.

For example, to switch to lwIP v1.4

[env:myenv]
...
build_flags = -D PIO_FRAMEWORK_ARDUINO_LWIP_HIGHER_BANDWIDTH

SDK Version¶

Available versions (macros):

• -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK3 NonOS SDK-pre-3.0 as of Jun 26, 2018

• -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK221 NonOS SDK v2.2.1 (legacy) as of Jun 8, 2018

• -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK22x_190313 NonOS SDK v2.2.x branch as of Mar 13, 2019

• -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK22x_190703 NonOS SDK v2.2.x branch as of Jul 03, 2019 (default)

• -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK22x_191024 NonOS SDK v2.2.x branch as of Oct 24, 2019

• -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK22x_191105 NonOS SDK v2.2.x branch as of to Nov 05, 2019

• -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK22x_191122 NonOS SDK v2.2.x branch as of to Nov 22, 2019

You can change SDK version by passing a custom macro using project build_flags.

For example, to switch to SDK-pre-3.0:

[env:myenv]
...
build_flags = -D PIO_FRAMEWORK_ARDUINO_ESPRESSIF_SDK3

SSL Support¶

By default, all SSL ciphers (most compatible) are supported.

You can control SSL support passing a custom macro using project build_flags.

For example, use basic SSL ciphers (lower ROM use):

[env:myenv]
...
build_flags = -D BEARSSL_SSL_BASIC

Serial Debug¶

Please use the next build_flags to enable Serial debug:

[env:myenv]
...
build_flags = -DDEBUG_ESP_PORT=Serial

; or for Serial1
build_flags = -DDEBUG_ESP_PORT=Serial1

Debug Level¶

Please use one of the next build_flags to change debug level. A build_flags option could be used only the one time per build environment. If you need to specify more flags, please separate them with a new line or space.

Also, please note that you will need to extend build_flags with Serial Debug macro. For example, build_flags = -DDEBUG_ESP_PORT=Serial -DDEBUG_ESP_SSL ....

Actual information is available in Arduino for ESP8266 Board Manifest. Please scroll to generic.menu.lvl section.

[env:myenv]
platform = ...
board = ...
framework = arduino

;;;;; Possible options ;;;;;;

; SSL
build_flags = -DDEBUG_ESP_SSL

; TLS_MEM
build_flags = -DDEBUG_ESP_TLS_MEM

; HTTP_CLIENT
build_flags = -DDEBUG_ESP_HTTP_CLIENT

; HTTP_SERVER
build_flags = -DDEBUG_ESP_HTTP_SERVER

; SSL+TLS_MEM
build_flags =
  -DDEBUG_ESP_SSL
  -DDEBUG_ESP_TLS_MEM

; SSL+HTTP_CLIENT
build_flags =
  -DDEBUG_ESP_SSL
  -DDEBUG_ESP_HTTP_CLIENT

; SSL+HTTP_SERVER
build_flags =
  -DDEBUG_ESP_SSL
  -DDEBUG_ESP_HTTP_SERVER

; TLS_MEM+HTTP_CLIENT
build_flags =
  -DDEBUG_ESP_TLS_MEM
  -DDEBUG_ESP_HTTP_CLIENT

; TLS_MEM+HTTP_SERVER
build_flags =
  -DDEBUG_ESP_TLS_MEM
  -DDEBUG_ESP_HTTP_SERVER

; HTTP_CLIENT+HTTP_SERVER
build_flags =
  -DDEBUG_ESP_HTTP_CLIENT
  -DDEBUG_ESP_HTTP_SERVER

; SSL+TLS_MEM+HTTP_CLIENT
build_flags =
  -DDEBUG_ESP_SSL
  -DDEBUG_ESP_TLS_MEM
  -DDEBUG_ESP_HTTP_CLIENT

; SSL+TLS_MEM+HTTP_SERVER
build_flags =
  -DDEBUG_ESP_SSL
  -DDEBUG_ESP_TLS_MEM
  -DDEBUG_ESP_HTTP_SERVER

; SSL+HTTP_CLIENT+HTTP_SERVER
build_flags =
  -DDEBUG_ESP_SSL
  -DDEBUG_ESP_HTTP_CLIENT
  -DDEBUG_ESP_HTTP_SERVER

; TLS_MEM+HTTP_CLIENT+HTTP_SERVER
build_flags =
  -DDEBUG_ESP_TLS_MEM
  -DDEBUG_ESP_HTTP_CLIENT
  -DDEBUG_ESP_HTTP_SERVER

; SSL+TLS_MEM+HTTP_CLIENT+HTTP_SERVER
build_flags =
  -DDEBUG_ESP_SSL
  -DDEBUG_ESP_TLS_MEM
  -DDEBUG_ESP_HTTP_CLIENT
  -DDEBUG_ESP_HTTP_SERVER

; CORE
build_flags = -DDEBUG_ESP_CORE

; WIFI
build_flags = -DDEBUG_ESP_WIFI

; HTTP_UPDATE
build_flags = -DDEBUG_ESP_HTTP_UPDATE

; UPDATER
build_flags = -DDEBUG_ESP_UPDATER

; OTA
build_flags = -DDEBUG_ESP_OTA

; OOM
build_flags =
  -DDEBUG_ESP_OOM
  -include "umm_malloc/umm_malloc_cfg.h"

; CORE+WIFI+HTTP_UPDATE+UPDATER+OTA+OOM
build_flags =
  -DDEBUG_ESP_CORE
  -DDEBUG_ESP_WIFI
  -DDEBUG_ESP_HTTP_UPDATE
  -DDEBUG_ESP_UPDATER
  -DDEBUG_ESP_OTA
  -DDEBUG_ESP_OOM -include "umm_malloc/umm_malloc_cfg.h"

; SSL+TLS_MEM+HTTP_CLIENT+HTTP_SERVER+CORE+WIFI+HTTP_UPDATE+UPDATER+OTA+OOM
build_flags =
  -DDEBUG_ESP_SSL
  -DDEBUG_ESP_TLS_MEM
  -DDEBUG_ESP_HTTP_CLIENT
  -DDEBUG_ESP_HTTP_SERVER
  -DDEBUG_ESP_CORE
  -DDEBUG_ESP_WIFI
  -DDEBUG_ESP_HTTP_UPDATE
  -DDEBUG_ESP_UPDATER
  -DDEBUG_ESP_OTA
  -DDEBUG_ESP_OOM -include "umm_malloc/umm_malloc_cfg.h"

; NoAssert-NDEBUG
build_flags = -DNDEBUG

VTables¶

Please use one of the next build_flags:

[env:myenv]
...

; Flash (default)
build_flags = -DVTABLES_IN_FLASH

; Heap
build_flags = -DVTABLES_IN_DRAM

; IRAM
build_flags = -DVTABLES_IN_IRAM

MMU - Adjusting ICACHE to IRAM ratio¶

By default the balanced ratio (32KB cache + 32KB IRAM) configuration is used. Alternative configurations can be enabled using the build_flags option in “platformio.ini” (Project Configuration File):

Examples:

[env:espduino]
platform = espressif8266
framework = arduino
board = espduino
build_flags =
    -D PIO_FRAMEWORK_ARDUINO_MMU_CACHE16_IRAM48

[env:espino]
platform = espressif8266
framework = arduino
board = espino
build_flags =
    -D PIO_FRAMEWORK_ARDUINO_MMU_CACHE16_IRAM32_SECHEAP_NOTSHARED

[env:d1_mini]
platform = espressif8266
framework = arduino
board = d1_mini
build_flags =
    -D PIO_FRAMEWORK_ARDUINO_MMU_CUSTOM
    -D MMU_IRAM_SIZE=0xC000
    -D MMU_ICACHE_SIZE=0x4000
    -D MMU_IRAM_HEAP

More detailed information on this matter can be found in the official documentation.

Exceptions¶

Exceptions are disabled by default. To enable exceptions, use the PIO_FRAMEWORK_ARDUINO_ENABLE_EXCEPTIONS macro in build_flags. That macro will add the -fexceptions flag and will link the final firmware against the stdc++-exc library with enabled exceptions. For example:

[env:myenv]
...

; Enable exceptions
build_flags = -D PIO_FRAMEWORK_ARDUINO_ENABLE_EXCEPTIONS

Using Filesystem¶

[env:myenv]
platform = espressif8266
framework = arduino
board = ...
board_build.filesystem = littlefs

[env:d1]
platform = espressif8266
framework = arduino
board = d1
board_build.filesystem = littlefs
extra_scripts =
    pre:extra_script.py

Import("env")
env.Replace(ESP8266_FS_IMAGE_NAME="custom_image_name")

Over-the-Air (OTA) update¶

Firstly, please read What is OTA? How to use it?

There are 2 options:

• Directly specify pio run --upload-port in command line

pio run --target upload --upload-port IP_ADDRESS_HERE or mDNS_NAME.local

• Specify upload_port option in “platformio.ini” (Project Configuration File)

You also need to set upload_protocol to espota.

[env:myenv]
upload_protocol = espota
upload_port = IP_ADDRESS_HERE or mDNS_NAME.local

For example,

• pio run -t upload --upload-port 192.168.0.255

• pio run -t upload --upload-port myesp8266.local

[env:myenv]
upload_protocol = espota
; each flag in a new line
upload_flags =
  --port=8266

~/.platformio/packages/framework-arduinoespressif8266/tools/espota.py --help

Usage: espota.py [options]

Transmit image over the air to the esp8266 module with OTA support.

Options:
  -h, --help            show this help message and exit

  Destination:
    -i ESP_IP, --ip=ESP_IP
                        ESP8266 IP Address.
    -I HOST_IP, --host_ip=HOST_IP
                        Host IP Address.
    -p ESP_PORT, --port=ESP_PORT
                        ESP8266 ota Port. Default 8266
    -P HOST_PORT, --host_port=HOST_PORT
                        Host server ota Port. Default random 10000-60000

  Authentication:
    -a AUTH, --auth=AUTH
                        Set authentication password.

  Image:
    -f FILE, --file=FILE
                        Image file.
    -s, --spiffs        Use this option to transmit a SPIFFS image and do not
                        flash the module.

  Output:
    -d, --debug         Show debug output. And override loglevel with debug.
    -r, --progress      Show progress output. Does not work for ArduinoIDE

Demo¶

Using Arduino Framework with Staging version¶

PlatformIO will install the latest Arduino Core for ESP8266 from https://github.com/esp8266/Arduino. The Git should be installed in a system. To update Arduino Core to the latest revision, please open PlatformIO IDE and navigate to PlatformIO Home > Platforms > Updates.

1. Please install PlatformIO IDE

2. Initialize a new project, open “platformio.ini” (Project Configuration File) and specify the link to the framework repository in platform_packages section. For example,

   [env:nodemcuv2]
   platform = espressif8266
   board = nodemcuv2
   framework = arduino
   platform_packages =
       platformio/framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git
   

3. Try to build the project

4. If you see build errors, then try to build this project using the same stage with Arduino IDE

5. If it works with Arduino IDE but doesn’t work with PlatformIO, then please file a new issue with attached information:

   • test project/files

   • detailed log of build process from Arduino IDE (please copy it from console to https://hastebin.com)

   • detailed log of build process from PlatformIO Build System (please copy it from console to https://hastebin.com)