Espressif 8266

Configuration:

platform = espressif8266

Espressif Systems is a privately held fabless semiconductor company. They provide wireless communications and Wi-Fi chips which are widely used in mobile devices and the Internet of Things applications.

For more detailed information please visit vendor site.

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

Warning

Please make sure to read ESP8266 Flash layout information first.

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

  • eagle.flash.512k0.ld 512K (no SPIFFS)

  • eagle.flash.512k64.ld 512K (64K SPIFFS)

  • eagle.flash.512k128.ld 512K (128K SPIFFS)

  • eagle.flash.1m0.ld 1M (no SPIFFS)

  • eagle.flash.1m64.ld 1M (64K SPIFFS)

  • eagle.flash.1m128.ld 1M (128K SPIFFS)

  • eagle.flash.1m144.ld 1M (144K SPIFFS)

  • eagle.flash.1m160.ld 1M (160K SPIFFS)

  • eagle.flash.1m192.ld 1M (192K SPIFFS)

  • eagle.flash.1m256.ld 1M (256K SPIFFS)

  • eagle.flash.1m512.ld 1M (512K SPIFFS)

  • eagle.flash.2m.ld 2M (1M SPIFFS)

  • eagle.flash.4m1m.ld 4M (1M SPIFFS)

  • eagle.flash.4m2m.ld 4M (2M SPIFFS)

  • eagle.flash.4m.ld 4M (3M SPIFFS)

  • eagle.flash.8m.ld 8M (7M SPIFFS)

  • eagle.flash.16m.ld 16M (15M SPIFFS)

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

[env:myenv]
build_flags = -Wl,-Teagle.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_LWIP_HIGHER_BANDWIDTH v1.4 Higher Bandwidth

  • -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

  • -D PIO_FRAMEWORK_ARDUINO_LWIP2_HIGHER_BANDWIDTH_LOW_FLASH

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

For example, switch to lwIP v1.4

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

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.DebugLevel 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

Uploading files to file system SPIFFS

Warning

Please make sure to read ESP8266 Flash layout information first.

  1. Create new project using PlatformIO IDE or initialize project using PlatformIO Core (CLI) and platformio init (if you have not initialized it yet)

  2. Create data folder (it should be on the same level as src folder) and put files here. Also, you can specify own location for data_dir

  3. Run “Upload File System image” task in PlatformIO IDE or use PlatformIO Core (CLI) and platformio run --target command with uploadfs target.

To upload SPIFFS image using OTA update please specify upload_port / --upload-port as IP address or mDNS host name (ending with the *.local). For the details please follow to Over-the-Air (OTA) update.

By default, will be used default LD Script for the board where is specified SPIFFS offsets (start, end, page, block). You can override it using Flash Size.

Active discussion is located in issue #382.

Over-the-Air (OTA) update

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

There are 2 options:

platformio run --target upload --upload-port IP_ADDRESS_HERE or mDNS_NAME.local
[env:myenv]
upload_port = IP_ADDRESS_HERE or mDNS_NAME.local

For example,

  • platformio run -t upload --upload-port 192.168.0.255

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

Authentication and upload options

You can pass additional options/flags to OTA uploader using upload_flags option in “platformio.ini” (Project Configuration File)

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

Available flags

  • --port=ESP_PORT ESP8266 OTA Port. Default 8266

  • --auth=AUTH Set authentication password

  • --spiffs Use this option to transmit a SPIFFS image and do not flash the module

For the full list with available options please run

~/.platformio/packages/tool-espotapy/espota.py --help

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
    -t TIMEOUT, --timeout=TIMEOUT
                        Timeout to wait for the ESP8266 to accept invitation

Demo

../../_images/platformio-demo-ota-esp8266.jpg

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 PIO Home > Platforms > Updates.

  1. Please install PlatformIO IDE

  2. Initialize a new project, open “platformio.ini” (Project Configuration File) and set platform to https://github.com/platformio/platform-espressif8266.git#feature/stage. For example,

    [env:nodemcuv2]
    platform = https://github.com/platformio/platform-espressif8266.git#feature/stage
    board = nodemcuv2
    framework = arduino
    
  3. Try to build 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 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)

Examples

Examples are listed from Espressif 8266 development platform repository:

Stable and upstream versions

You can switch between stable releases of Espressif 8266 development platform and the latest upstream version using platform option in “platformio.ini” (Project Configuration File) as described below.

Stable

; Latest stable version
[env:latest_stable]
platform = espressif8266
board = ...

; Custom stable version
[env:custom_stable]
platform = espressif8266@x.y.z
board = ...

Upstream

[env:upstream_develop]
platform = https://github.com/platformio/platform-espressif8266.git
board = ...

Packages

Name

Description

framework-arduinoespressif8266

Arduino Wiring-based Framework (ESP8266 Core)

framework-esp8266-nonos-sdk

ESP8266 Non-OS SDK

framework-esp8266-rtos-sdk

ESP8266 SDK based on FreeRTOS

framework-simba

Simba Framework

sdk-esp8266

ESP8266 SDK

tool-espotapy

ESP8266 OTA utility

tool-esptool

esptool-ck

tool-mkspiffs

Tool to build and unpack SPIFFS images

toolchain-xtensa

xtensa-gcc

Warning

Linux Users:

Windows Users:

Please check that you have a correctly installed USB driver from board manufacturer

Frameworks

Name

Description

Arduino

Arduino Wiring-based Framework allows writing cross-platform software to control devices attached to a wide range of Arduino boards to create all kinds of creative coding, interactive objects, spaces or physical experiences.

ESP8266 Non-OS SDK

The non-OS SDK provides a set of application programming interfaces (APIs) for core ESP8266 functionalities such as data reception/transmission over Wi-Fi, TCP/IP stack functions, hardware interface functions and basic system management functions.

ESP8266 RTOS SDK

ESP8266 SDK based on FreeRTOS, a truly free professional grade RTOS for microcontrollers

Simba

Simba is an RTOS and build framework. It aims to make embedded programming easy and portable.

Boards

Note

4D Systems

Name

Debug

MCU

Frequency

Flash

RAM

4D Systems gen4 IoD Range

No

ESP8266

80MHz

512KB

80KB

Adafruit

Name

Debug

MCU

Frequency

Flash

RAM

Adafruit HUZZAH ESP8266

No

ESP8266

80MHz

4MB

80KB

Amperka

Name

Debug

MCU

Frequency

Flash

RAM

WiFi Slot

No

ESP8266

80MHz

4MB

80KB

DigiStump

Name

Debug

MCU

Frequency

Flash

RAM

DigiStump Oak

No

ESP8266

80MHz

4MB

80KB

Doit

Name

Debug

MCU

Frequency

Flash

RAM

ESPDuino (ESP-13 Module)

No

ESP8266

80MHz

4MB

80KB

DycodeX

Name

Debug

MCU

Frequency

Flash

RAM

ESPectro Core

No

ESP8266

80MHz

4MB

80KB

ESPert

Name

Debug

MCU

Frequency

Flash

RAM

ESPresso Lite 1.0

No

ESP8266

80MHz

4MB

80KB

ESPresso Lite 2.0

No

ESP8266

80MHz

4MB

80KB

ESPino

Name

Debug

MCU

Frequency

Flash

RAM

ESPino

No

ESP8266

80MHz

4MB

80KB

Espressif

Name

Debug

MCU

Frequency

Flash

RAM

ESP-WROOM-02

No

ESP8266

80MHz

2MB

80KB

Espressif ESP8266 ESP-12E

No

ESP8266

80MHz

4MB

80KB

Espressif Generic ESP8266 ESP-01 1M

No

ESP8266

80MHz

1MB

80KB

Espressif Generic ESP8266 ESP-01 512k

No

ESP8266

80MHz

512KB

80KB

Espressif Generic ESP8266 ESP-07

No

ESP8266

80MHz

4MB

80KB

Generic ESP8285 Module

No

ESP8266

80MHz

423.98KB

80KB

Phoenix 1.0

No

ESP8266

80MHz

4MB

80KB

Phoenix 2.0

No

ESP8266

80MHz

4MB

80KB

WifInfo

No

ESP8266

80MHz

1MB

80KB

Heltec

Name

Debug

MCU

Frequency

Flash

RAM

Heltec Wifi kit 8

No

ESP8266

80MHz

4MB

80KB

NodeMCU

Name

Debug

MCU

Frequency

Flash

RAM

NodeMCU 0.9 (ESP-12 Module)

No

ESP8266

80MHz

4MB

80KB

NodeMCU 1.0 (ESP-12E Module)

No

ESP8266

80MHz

4MB

80KB

Olimex

Name

Debug

MCU

Frequency

Flash

RAM

Olimex MOD-WIFI-ESP8266(-DEV)

No

ESP8266

80MHz

2MB

80KB

SeeedStudio

Name

Debug

MCU

Frequency

Flash

RAM

Wio Link

No

ESP8266

80MHz

4MB

80KB

Wio Node

No

ESP8266

80MHz

4MB

80KB

SparkFun

Name

Debug

MCU

Frequency

Flash

RAM

SparkFun Blynk Board

No

ESP8266

80MHz

4MB

80KB

SparkFun ESP8266 Thing

No

ESP8266

80MHz

512KB

80KB

SparkFun ESP8266 Thing Dev

No

ESP8266

80MHz

512KB

80KB

SweetPea

Name

Debug

MCU

Frequency

Flash

RAM

SweetPea ESP-210

No

ESP8266

80MHz

4MB

80KB

ThaiEasyElec

Name

Debug

MCU

Frequency

Flash

RAM

ThaiEasyElec ESPino

No

ESP8266

80MHz

4MB

80KB

WEMOS

Name

Debug

MCU

Frequency

Flash

RAM

WEMOS D1 R1 (Retired)

No

ESP8266

80MHz

4MB

80KB

WeMos D1 R2 & mini

No

ESP8266

80MHz

4MB

80KB

WeMos D1 mini Lite

No

ESP8266

80MHz

1MB

80KB

WeMos D1 mini Pro

No

ESP8266

80MHz

16MB

80KB

WifiDuino

Name

Debug

MCU

Frequency

Flash

RAM

WiFiduino

No

ESP8266

80MHz

4MB

80KB

XinaBox

Name

Debug

MCU

Frequency

Flash

RAM

XinaBox CW01

No

ESP8266

80MHz

4MB

80KB