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

Contents

- Configuration

- Examples

- Stable and upstream versions

- Packages

- Frameworks

- Boards

## Configuration

- CPU Frequency

- FLASH Frequency

- FLASH Mode

- Reset Method

- Flash Size

- Upload Speed

- lwIP Variant

- SDK Version

- SSL Support

- Serial Debug

- Debug Level

- VTables

- Exceptions

- Uploading files to file system SPIFFS

- Over-the-Air (OTA) update

  - Authentication and upload options

- Demo

- Using Arduino Framework with Staging version

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

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

### Exceptions

Exceptions are disabled by default. To enable exceptions, use the following build_flags and build_unflags:

    [env:myenv]
    ...

    ; Remove default exceptions disabled flag
    build_unflags = -fno-exceptions

    ; Enable exceptions
    build_flags = -fexceptions

### 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 project 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:

- Directly specify `platformio run --upload-port` in command line

    platformio 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,

- `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]
    upload_protocol = espota
    ; 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/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 `PIO 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 =
           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)

## Examples

Examples are listed from Espressif 8266 development platform repository:

- arduino-webserver

- arduino-asyncudp

- arduino-blink

- simba-blink

- esp8266-rtos-sdk-blink

- esp8266-nonos-sdk-blink

- arduino-wifiscan

## 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
tool-esptool | esptool-ck
tool-esptoolpy | ESP8266 and ESP32 serial bootloader utility
tool-mkspiffs | Tool to build and unpack SPIFFS images
toolchain-xtensa | xtensa-gcc

Warning

Linux Users:

> - Install “udev” rules 99-platformio-udev.rules

> - Raspberry Pi users, please read this article Enable serial port on Raspberry Pi.

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

- You can list pre-configured boards by platformio boards command or PlatformIO Boards Explorer

- For more detailed `board` information please scroll the tables below by horizontally.

### 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
--- | --- | --- | --- | --- | ---
ESP-Mx DevKit (ESP8285) | No | ESP8266 | 80MHz | 1MB | 80KB
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 | 1MB | 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

### ITEAD

Name | Debug | MCU | Frequency | Flash | RAM
--- | --- | --- | --- | --- | ---
Sonoff Basic | No | ESP8266 | 80MHz | 1MB | 80KB
Sonoff S20 | No | ESP8266 | 80MHz | 1MB | 80KB
Sonoff SV | No | ESP8266 | 80MHz | 1MB | 80KB
Sonoff TH | No | ESP8266 | 80MHz | 1MB | 80KB

### Invent One

Name | Debug | MCU | Frequency | Flash | RAM
--- | --- | --- | --- | --- | ---
Invent One | 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

### Schirmilabs

Name | Debug | MCU | Frequency | Flash | RAM
--- | --- | --- | --- | --- | ---
Schirmilabs Eduino WiFi | No | ESP8266 | 80MHz | 4MB | 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 | No | ESP8266 | 80MHz | 4MB | 80KB
WeMos D1 R2 and 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