Espressif 32¶
| Configuration: | 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:
qioqoutdiodout
[env:myenv]
board_build.flash_mode = qio
External RAM (PSRAM)¶
You can enable external RAM using the next extra build_flags in Project Configuration File platformio.ini depending on a framework type.
Framework Arduino:
[env:myenv]
platform = espressif32
framework = arduino
board = ...
build_flags =
-DBOARD_HAS_PSRAM
-mfix-esp32-psram-cache-issue
Framework ESP-IDF:
[env:myenv]
platform = espressif32
framework = espidf
board = ...
build_flags =
-DCONFIG_SPIRAM_CACHE_WORKAROUND
More details are located in the official ESP-IDF documentation - Support for external RAM.
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
Embedding Binary Data¶
Sometimes you have a file with some binary or text data that you’d like to make available to your program - but you don’t want to reformat the file as C source.
You can set a macro (define) COMPONENT_EMBED_FILES using
build_flags in Project Configuration File platformio.ini, giving the names of the
files to embed in this way:
[env:myenv]
platform = espressif32
board = ...
build_flags =
-DCOMPONENT_EMBED_TXTFILES=src/private.pem.key:src/certificate.pem.crt:src/aws-root-ca.pem
Multiple files are allowed and should be split by colon - :.
The file’s contents will be added to the .rodata section in flash, and
are available via symbol names as follows:
extern const uint8_t aws_root_ca_pem_start[] asm("_binary_src_aws_root_ca_pem_start");
extern const uint8_t aws_root_ca_pem_end[] asm("_binary_src_aws_root_ca_pem_end");
extern const uint8_t certificate_pem_crt_start[] asm("_binary_src_certificate_pem_crt_start");
extern const uint8_t certificate_pem_crt_end[] asm("_binary_src_certificate_pem_crt_end");
extern const uint8_t private_pem_key_start[] asm("_binary_src_private_pem_key_start");
extern const uint8_t private_pem_key_end[] asm("_binary_src_private_pem_key_end");
The names are generated from the full name of the file, as given in
COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with
underscores. The _binary + _nested_folder prefix in the symbol name
is added by “objcopy” and is the same for both text and binary files.
See full example with embedding Amazon AWS certificates:
Uploading files to file system SPIFFS¶
- Initialize project platformio init (if you have not initialized yet)
- Create
datafolder (it should be on the same level assrcfolder) and put files here. Also, you can specify own location for data_dir - Run
buildfsoruploadfstarget usingplatformio run --targetcommand.
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¶
Using JFrog Bintray (free and secure Cloud solution)¶
- Video and presentation - swampUP: Over-The-Air (OTA) firmware upgrades for Internet of Things devices with PlatformIO and JFrog Bintray
- Demo source code: https://github.com/platformio/bintray-secure-ota
Using built-in Local solution¶
Demo code for:
There are 2 options how to upload firmware OTA:
- Directly specify
platformio run --upload-portin command line
platformio run --target upload --upload-port IP_ADDRESS_HERE or mDNS_NAME.local
- Specify
upload_portoption in Project Configuration File platformio.ini
[env:myenv]
upload_port = IP_ADDRESS_HERE or mDNS_NAME.local
For example,
platformio run -t upload --upload-port 192.168.0.255platformio 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]
; each flag in a new line
upload_flags =
--port=3232
Available flags
--port=ESP_PORTESP32 OTA Port. Default 3232--auth=AUTHSet authentication password--spiffsUse 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.
Please install PlatformIO IDE
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
Try to build project
If you see build errors, then try to build this project using the same
stagewith Arduino IDEIf 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)
Arduino Core Wiki¶
Tips, tricks and common problems: http://desire.giesecke.tk/index.php/2018/01/30/esp32-wiki-entries/
Examples¶
Examples are listed from Espressif 32 development platform repository:
Debugging¶
PIO Unified Debugger - “1-click” solution for debugging with a zero configuration.
Pinout Diagram¶
JTAG Wiring Connections
| Board Pin | JTAG Tool Pin |
|---|---|
| IO13 | TCK |
| IO12 | TDI |
| IO15 | TDO |
| IO14 | TMS |
| EN | RST |
| GND | GND |
Tools & Debug Probes¶
Supported debugging tools are listed in “Debug” column. For more detailed information, please scroll table by horizontal. You can switch between debugging Tools & Debug Probes using debug_tool options.
Warning
You will need to install debug tool drivers depending on your system. Please click on compatible debug tool below for the further instructions.
On-Board Debug Tools¶
Boards listed below have on-board debug tool and ARE READY for debugging! You do not need to use/buy external debug tool.
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
esp-wrover-kit |
Espressif ESP-WROVER-KIT | FTDI Chip (default, on-board), ESP-Prog, Mini-Module FT2232H, Olimex ARM-USB-OCD-H, Olimex ARM-USB-OCD, Olimex ARM-USB-TINY-H, Olimex ARM-USB-TINY | ESP32 | 240MHz | 4MB | 320KB |
External Debug Tools¶
Boards listed below are compatible with PIO Unified Debugger but DEPEND ON external debug tool. See “Debug” column for compatible debug tools.
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 = [email protected]
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:
- 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. |
| 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
- You can list pre-configured boards by platformio boards command or PlatformIO Boards Explorer
- For more detailed
boardinformation please scroll tables below by horizontal.
Adafruit¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
featheresp32 |
Adafruit ESP32 Feather | Yes | ESP32 | 240MHz | 4MB | 320KB |
April Brother¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
espea32 |
April Brother ESPea32 | No | ESP32 | 240MHz | 4MB | 320KB |
DFRobot¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
firebeetle32 |
FireBeetle-ESP32 | Yes | ESP32 | 240MHz | 4MB | 320KB |
DOIT¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
esp32doit-devkit-v1 |
DOIT ESP32 DEVKIT V1 | Yes | ESP32 | 240MHz | 4MB | 320KB |
Dongsen Technology¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
pocket_32 |
Dongsen Tech Pocket 32 | Yes | ESP32 | 240MHz | 4MB | 320KB |
DycodeX¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
espectro32 |
ESPectro32 | Yes | ESP32 | 240MHz | 4MB | 320KB |
ESP32vn¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
esp32vn-iot-uno |
ESP32vn IoT Uno | Yes | ESP32 | 240MHz | 4MB | 320KB |
Electronic SweetPeas¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
esp320 |
Electronic SweetPeas ESP320 | No | ESP32 | 240MHz | 4MB | 320KB |
Espressif¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
esp-wrover-kit |
Espressif ESP-WROVER-KIT | Yes | ESP32 | 240MHz | 4MB | 320KB |
esp32dev |
Espressif ESP32 Dev Module | Yes | ESP32 | 240MHz | 4MB | 320KB |
pico32 |
ESP32 Pico Kit | No | ESP32 | 240MHz | 4MB | 320KB |
Heltec Automation¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
heltec_wifi_kit_32 |
Heltec WIFI Kit 32 | No | ESP32 | 240MHz | 4MB | 320KB |
heltec_wifi_lora_32 |
Heltec WIFI LoRa 32 | No | ESP32 | 240MHz | 4MB | 320KB |
Hornbill¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
hornbill32dev |
Hornbill ESP32 Dev | Yes | ESP32 | 240MHz | 4MB | 320KB |
hornbill32minima |
Hornbill ESP32 Minima | Yes | ESP32 | 240MHz | 4MB | 320KB |
IntoRobot¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
intorobot |
IntoRobot Fig | No | ESP32 | 240MHz | 4MB | 320KB |
M5Stack¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
m5stack-core-esp32 |
M5Stack Core ESP32 | No | ESP32 | 240MHz | 4MB | 320KB |
m5stack-fire |
M5Stack FIRE | No | ESP32 | 240MHz | 16MB | 320KB |
MH-ET Live¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
mhetesp32devkit |
MH ET LIVE ESP32DevKIT | Yes | ESP32 | 240MHz | 4MB | 320KB |
mhetesp32minikit |
MH ET LIVE ESP32MiniKit | Yes | ESP32 | 240MHz | 4MB | 320KB |
MakerAsia¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
nano32 |
MakerAsia Nano32 | No | ESP32 | 240MHz | 4MB | 320KB |
Microduino¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
microduino-core-esp32 |
Microduino Core ESP32 | No | ESP32 | 240MHz | 4MB | 320KB |
NodeMCU¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
nodemcu-32s |
NodeMCU-32S | Yes | ESP32 | 240MHz | 4MB | 320KB |
Noduino¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
quantum |
Noduino Quantum | No | ESP32 | 240MHz | 16MB | 320KB |
OLIMEX¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
esp32-evb |
OLIMEX ESP32-EVB | Yes | ESP32 | 240MHz | 4MB | 320KB |
esp32-gateway |
OLIMEX ESP32-GATEWAY | Yes | ESP32 | 240MHz | 4MB | 320KB |
Onehorse¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
onehorse32dev |
Onehorse ESP32 Dev Module | No | ESP32 | 240MHz | 4MB | 320KB |
RoboticsBrno¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
alksesp32 |
ALKS ESP32 | Yes | ESP32 | 240MHz | 4MB | 320KB |
SparkFun Electronics¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
esp32thing |
SparkFun ESP32 Thing | Yes | ESP32 | 240MHz | 4MB | 320KB |
TTGO¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
ttgo-lora32-v1 |
TTGO LoRa32-OLED V1 | Yes | ESP32 | 240MHz | 4MB | 320KB |
WEMOS¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
lolin32 |
WEMOS LOLIN32 | Yes | ESP32 | 240MHz | 4MB | 320KB |
lolin_d32 |
WEMOS LOLIN D32 | Yes | ESP32 | 240MHz | 4MB | 320KB |
lolin_d32_pro |
WEMOS LOLIN D32 PRO | Yes | ESP32 | 240MHz | 4MB | 320KB |
wemosbat |
WeMos WiFi & Bluetooth Battery | Yes | ESP32 | 240MHz | 4MB | 320KB |
Widora¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
widora-air |
Widora AIR | No | ESP32 | 240MHz | 16MB | 320KB |
XinaBox¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
xinabox_cw02 |
XinaBox CW02 | Yes | ESP32 | 240MHz | 4MB | 320KB |
u-blox¶
| ID | Name | Debug | MCU | Frequency | Flash | RAM |
|---|---|---|---|---|---|---|
nina_w10 |
u-blox NINA-W10 series | No | ESP32 | 240MHz | 2MB | 320KB |