Espressif 32

platform = espressif32

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 Project Configuration File platformio.ini

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

FLASH Frequency

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

  • 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 Project Configuration File platformio.ini to change a value. Possible values:

  • qio
  • qout
  • dio
  • dout
[env:myenv]
board_build.flash_mode = qio

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.

Actual information is available in Arduino for ESP32 Board Manifest. Please scroll to esp32.menu.DebugLevel section.

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

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

; None
build_flags = -DCORE_DEBUG_LEVEL=0

; Error
build_flags = -DCORE_DEBUG_LEVEL=1

; Warn
build_flags = -DCORE_DEBUG_LEVEL=2

; Info
build_flags = -DCORE_DEBUG_LEVEL=3

; Debug
build_flags = -DCORE_DEBUG_LEVEL=4

; Verbose
build_flags = -DCORE_DEBUG_LEVEL=5

Upload Speed

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

[env:myenv]
upload_speed = 9600

Enable C++ exceptions

Please add -D PIO_FRAMEWORK_ESP_IDF_ENABLE_EXCEPTIONS to build_flags of Project Configuration File platformio.ini to enable C++ exceptions for ESP-IDF.

See project example.

Partition Tables

You can create a custom partitions table (CSV) following ESP32 Partition Tables documentation. PlatformIO uses default partition tables depending on a framework type:

To override default table please use board_build.partitions option in Project Configuration File platformio.ini.

Warning

SPIFFS partition MUST have configured “Type” as “data” and “SubType” as “spiffs”. For example, spiffs, data, spiffs, 0x291000, 1M,

Examples:

; 1) A "partitions_custom.csv" in the root of project directory
[env:custom_table]
board_build.partitions = partitions_custom.csv

; 2) Switch between built-in tables
; https://github.com/espressif/arduino-esp32/tree/master/tools/partitions
; https://github.com/espressif/esp-idf/tree/master/components/partition_table
[env:custom_builtin_table]
board_build.partitions = no_ota.csv

Uploading files to file system SPIFFS

  1. Initialize project platformio init (if you have not initialized 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 buildfs or uploadfs target using platformio run --target command.

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

Examples:

Over-the-Air (OTA) update

Demo code for:

There are 2 options how to upload firmware OTA:

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 myesp32.local

Authentication and upload options

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

[env:myenv]
upload_flags = --port=3232

Available flags

  • --port=ESP_PORT ESP32 OTA Port. Default 3232
  • --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 -h

Usage: espota.py [options]

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

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

  Destination:
    -i ESP_IP, --ip=ESP_IP
                        ESP32 IP Address.
    -p ESP_PORT, --port=ESP_PORT
                        ESP32 ota Port. Default 3232

  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

Using Arduino Framework with Staging version

PlatformIO will install the latest Arduino Core for ESP32 from https://github.com/espressif/arduino-esp32. 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 Project Configuration File platformio.ini and set platform to https://github.com/platformio/platform-espressif32.git#feature/stage. For example,

    [env:esp32dev]
platform = https://github.com/platformio/platform-espressif32.git#feature/stage
board = esp32dev
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)

Debugging

PIO Unified Debugger - “1-click” solution for debugging with a zero configuration.

Supported debugging tools are listed in “Debug” column. For more detailed information, please scroll table by horizontal. You can switch between debugging Tools using debug_tool options.

On-Board tools

Boards listed below have on-board debugging tools and ARE READY for debugging! You do not need to use/buy external debugger.

ID Name Debug MCU Frequency Flash RAM
esp-wrover-kit Espressif ESP-WROVER-KIT FTDI FT2232H (default, on-board), Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 4MB

External tools

Boards listed below are compatible with PIO Unified Debugger but depend on external debugging tools. See “Debug” column for compatible debugging tools.

ID Name Debug MCU Frequency Flash RAM
esp32-evb OLIMEX ESP32-EVB Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
esp32-gateway OLIMEX ESP32-GATEWAY Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
esp32dev Espressif ESP32 Dev Module Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
esp32doit-devkit-v1 DOIT ESP32 DEVKIT V1 Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
esp32thing SparkFun ESP32 Thing Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
esp32vn-iot-uno ESP32vn IoT Uno Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
espectro32 ESPectro32 Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
espino32 ESPino32 Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
featheresp32 Adafruit ESP32 Feather Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
firebeetle32 FireBeetle-ESP32 Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
hornbill32dev Hornbill ESP32 Dev Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
hornbill32minima Hornbill ESP32 Minima Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
lolin32 WEMOS LOLIN32 Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
mhetesp32devkit MH ET LIVE ESP32DevKIT Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
mhetesp32minikit MH ET LIVE ESP32MiniKit Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
node32s Node32s Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
nodemcu-32s NodeMCU-32S Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
pocket_32 Dongsen Tech Pocket 32 Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB
wemosbat WeMos WiFi & Bluetooth Battery Mini-Module, Olimex ARM-USB-OCD-H, Olimex ARM-USB-TINY-H ESP32 240MHz 1.25MB 288KB

Stable and upstream versions

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

Stable

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

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

Upstream

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

Packages

Name Description
framework-arduinoespressif32 Arduino Wiring-based Framework (ESP32 Core)
framework-espidf Espressif IoT Development Framework
framework-pumbaa Pumbaa Framework
framework-simba Simba Framework
tool-espotapy ESP8266 OTA utility
tool-esptoolpy ESP8266 and ESP32 serial bootloader utility
tool-mkspiffs Tool to build and unpack SPIFFS images
tool-openocd-esp32 OpenOCD for Espressif 32
toolchain-xtensa32 xtensa32-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.
ESP-IDF Espressif IoT Development Framework. Official development framework for ESP32.
Pumbaa Pumbaa is Python on top of Simba. The implementation is a port of MicroPython, designed for embedded devices with limited amount of RAM and code memory.
Simba Simba is an RTOS and build framework. It aims to make embedded programming easy and portable.

Boards

Note

Adafruit

ID Name Debug MCU Frequency Flash RAM
featheresp32 Adafruit ESP32 Feather Yes ESP32 240MHz 1.25MB 288KB

Aiyarafun

ID Name Debug MCU Frequency Flash RAM
node32s Node32s Yes ESP32 240MHz 1.25MB 288KB

April Brother

ID Name Debug MCU Frequency Flash RAM
espea32 April Brother ESPea32 No ESP32 240MHz 1.25MB 288KB

DFRobot

ID Name Debug MCU Frequency Flash RAM
firebeetle32 FireBeetle-ESP32 Yes ESP32 240MHz 1.25MB 288KB

DOIT

ID Name Debug MCU Frequency Flash RAM
esp32doit-devkit-v1 DOIT ESP32 DEVKIT V1 Yes ESP32 240MHz 1.25MB 288KB

Dongsen Technology

ID Name Debug MCU Frequency Flash RAM
pocket_32 Dongsen Tech Pocket 32 Yes ESP32 240MHz 1.25MB 288KB

DycodeX

ID Name Debug MCU Frequency Flash RAM
espectro32 ESPectro32 Yes ESP32 240MHz 1.25MB 288KB

ESP32vn

ID Name Debug MCU Frequency Flash RAM
esp32vn-iot-uno ESP32vn IoT Uno Yes ESP32 240MHz 1.25MB 288KB

Electronic SweetPeas

ID Name Debug MCU Frequency Flash RAM
esp320 Electronic SweetPeas ESP320 No ESP32 240MHz 1.25MB 288KB

Espressif

ID Name Debug MCU Frequency Flash RAM
esp-wrover-kit Espressif ESP-WROVER-KIT Yes ESP32 240MHz 1.25MB 4MB
esp32dev Espressif ESP32 Dev Module Yes ESP32 240MHz 1.25MB 288KB
pico32 ESP32 Pico Kit No ESP32 240MHz 1.25MB 288KB

Heltec Automation

ID Name Debug MCU Frequency Flash RAM
heltec_wifi_kit_32 Heltec WIFI Kit 32 No ESP32 240MHz 1.25MB 288KB
heltec_wifi_lora_32 Heltec WIFI LoRa 32 No ESP32 240MHz 1.25MB 288KB

Hornbill

ID Name Debug MCU Frequency Flash RAM
hornbill32dev Hornbill ESP32 Dev Yes ESP32 240MHz 1.25MB 288KB
hornbill32minima Hornbill ESP32 Minima Yes ESP32 240MHz 1.25MB 288KB

IntoRobot

ID Name Debug MCU Frequency Flash RAM
intorobot IntoRobot Fig No ESP32 240MHz 1.25MB 288KB

M5Stack

ID Name Debug MCU Frequency Flash RAM
m5stack-core-esp32 M5Stack Core ESP32 No ESP32 240MHz 1.25MB 288KB

MH-ET Live

ID Name Debug MCU Frequency Flash RAM
mhetesp32devkit MH ET LIVE ESP32DevKIT Yes ESP32 240MHz 1.25MB 288KB
mhetesp32minikit MH ET LIVE ESP32MiniKit Yes ESP32 240MHz 1.25MB 288KB

MakerAsia

ID Name Debug MCU Frequency Flash RAM
nano32 MakerAsia Nano32 No ESP32 240MHz 1.25MB 288KB

Microduino

ID Name Debug MCU Frequency Flash RAM
microduino-core-esp32 Microduino Core ESP32 No ESP32 240MHz 1.25MB 288KB

NodeMCU

ID Name Debug MCU Frequency Flash RAM
nodemcu-32s NodeMCU-32S Yes ESP32 240MHz 1.25MB 288KB

Noduino

ID Name Debug MCU Frequency Flash RAM
quantum Noduino Quantum No ESP32 240MHz 1.25MB 288KB

OLIMEX

ID Name Debug MCU Frequency Flash RAM
esp32-evb OLIMEX ESP32-EVB Yes ESP32 240MHz 1.25MB 288KB
esp32-gateway OLIMEX ESP32-GATEWAY Yes ESP32 240MHz 1.25MB 288KB

Onehorse

ID Name Debug MCU Frequency Flash RAM
onehorse32dev Onehorse ESP32 Dev Module No ESP32 240MHz 1.25MB 288KB

SparkFun Electronics

ID Name Debug MCU Frequency Flash RAM
esp32thing SparkFun ESP32 Thing Yes ESP32 240MHz 1.25MB 288KB

ThaiEasyElec

ID Name Debug MCU Frequency Flash RAM
espino32 ESPino32 Yes ESP32 240MHz 1.25MB 288KB

WEMOS

ID Name Debug MCU Frequency Flash RAM
lolin32 WEMOS LOLIN32 Yes ESP32 240MHz 1.25MB 288KB
wemosbat WeMos WiFi & Bluetooth Battery Yes ESP32 240MHz 1.25MB 288KB

Widora

ID Name Debug MCU Frequency Flash RAM
widora-air Widora AIR No ESP32 240MHz 1.25MB 288KB

u-blox

ID Name Debug MCU Frequency Flash RAM
nina_w10 u-blox NINA-W10 series No ESP32 240MHz 1.25MB 288KB