Espressif 32¶

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:

• 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

External RAM (PSRAM)¶

You can enable external RAM using the next extra build_flags in “platformio.ini” (Project Configuration File) 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 Espressif IoT Development Framework:

[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 “platformio.ini” (Project Configuration File)

[env:myenv]
upload_speed = 9600

Erase Flash¶

Please pio run --target the next command to erase the entire flash chip (all data replaced with 0xFF bytes):

> pio run --target erase

# or short version

> pio run -t erase

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:

• default.csv for Arduino (show pre-configured partition tables)

• partitions_singleapp.csv for Espressif IoT Development Framework (show pre-configured partition tables)

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

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.

There are two options board_build.embed_txtfiles and board_build.embed_files which can be used for embedding data. The only difference is that files specified in board_build.embed_txtfiles option are null-terminated in the final binary.

[env:myenv]
platform = espressif32
board = ...
board_build.embed_txtfiles =
  src/private.pem.key
  src/certificate.pem.crt
  src/aws-root-ca.pem

The file 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. 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:

• https://github.com/platformio/platform-espressif32/tree/develop/examples/espidf-aws-iot

Uploading files to file system SPIFFS¶

1. Create new project using PlatformIO IDE or initialize project using PlatformIO Core (CLI) and pio 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 pio 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).

Examples:

• SPIFFS for Arduino

• SPIFFS for ESP-IDF

Over-the-Air (OTA) update¶

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

pio run -t upload --upload-port 192.168.0.255
pio run -t upload --upload-port myesp32.local

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

[env:myenv]
platform = espressif32
board = esp32dev
framework = arduino
upload_protocol = espota
upload_port = 192.168.0.255

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

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

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.
    -I HOST_IP, --host_ip=HOST_IP
                        Host IP Address.
    -p ESP_PORT, --port=ESP_PORT
                        ESP32 ota Port. Default 3232
    -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 ESP32 to accept invitation

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 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:esp32dev]
   platform = espressif32
   board = esp32dev
   framework = arduino
   platform_packages =
       platformio/framework-arduinoespressif32 @ https://github.com/espressif/arduino-esp32.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)

Arduino Core Wiki¶

Tips, tricks and common problems: http://desire.giesecke.tk/index.php/2018/01/30/esp32-wiki-entries/

Pinout Diagram¶

JTAG Wiring Connections

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 option in “platformio.ini” (Project Configuration File).

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

AI Thinker¶

AZ-Delivery¶

Adafruit¶

Aiyarafun¶

April Brother¶

BPI Tech¶

Blinker¶

DFRobot¶

DOIT¶

DSTIKE¶

Dongsen Technology¶

DycodeX¶

ESP32vn¶

ETBoard¶

Electronic SweetPeas¶

Espressif¶

Fishino¶

Fred¶

HONEYLemon¶

Hardkernel¶

Heltec Automation¶

Hornbill¶

INEX¶

Imbrios¶

IntoRobot¶

IoTaaP¶

KITS¶

LOGISENSES¶

Labplus¶

M5Stack¶

MGBOT¶

MH-ET Live¶

Magicblocks.io¶

MakerAsia¶

Microduino¶

NodeMCU¶

Noduino¶

OLIMEX¶

OROCA¶

Onehorse¶

ProtoCentral¶

Pycom Ltd.¶

Qmobot LLP¶

RoboticsBrno¶

S.ODI¶

SG-O¶

Silicognition¶

SparkFun¶

SparkFun Electronics¶

TTGO¶

ThaiEasyElec¶

Turta¶

Unexpected Maker¶

Unknown¶

VintLabs¶

WEMOS¶

Widora¶

XinaBox¶

YeaCreate¶

meteca¶

oddWires¶

u-blox¶