ESP32 Development Boards - Getting started

A big variety of ESP32 development boards (from Espressif and lots of other companies) have surfaced since the first ESP32 chip was released in 2016 by Espressif. Most boards contain the original ESP32, some an ESP32-S2 and newer ones the most recent flavour ESP32-S3. For differences between those chips look here.

The ESP32 chip family is loaded with features, e.g. WiFi/Bluetooth, dual core (up to 240MHz clock frequency), integrated Flash memory, lots of GPIO pins (peripheral input/output), ADC/DAC, UART, I2S, SPI, low power states, JTAG debugging option, etc. Have a look at the many documents in folder ESP32_specs_and_manuals for various ESP32 datasheets.

Almost all development boards feature a greater number of GPIO pins, a combination of WLAN antenna and/or IPX antenna connector, USB-Port, LDO voltage regulator and some LEDs (Power/RX/TX). Some boards have additional features, like RJ45 Ethernet, TFT display, camera (e.g. OV2640), RGB-LED (e.g. WS2812B), battery connector, more Flash memory (up to 16MB) and/or PSRAM (up to 8MB), etc.

Probably the best way to get familiar with a certain board is writing a few tiny software programs (examples) for it. A good start would be to let the onboard LED blink or change color (RGB-LED), generate a few lines serial output, connect to the local WLAN, read the status of a connected push button, put the ESP32 into sleep mode, create a single file on an attached SD-Card or some other simple task. You get the idea.

BTW: Arduino uses the name sketch (file extension *.ino) for a program.

📁 Software Examples

Under boards you find a (growing) collection of programs for each board listed below. They will help you explore the features of those boards.

All examples were created and build with VSCode/PlatformIO. Each example has it's own project directory (one that contains a platformio.ini file). Make sure you have the latest Arduino ESP32 development package installed (V5.2.0 at the time of this writing).

For loading, editing and uploading an example just start VSCode/PlatformIO, go to "File"-->"Open Folder" and select the example's project directory.

Right now examples are provided for the following boards:

• ESP32-DevKit-V1

• YB-ESP32-S3-ETH DevBoard with Ethernet, WiFi, two USB ports and optional PSRAM in different variants

• ESP32-CAM, ESP32-CAM-USB and ESP32-CAM-MB

• ESP32-1.14-Display DevBoard

• ESP32-S3-0.85-Display DevBoard

• ESP32-S3-1.9-Display DevBoard

• YD-ESP32-S3 DevBoard with big Flash, ext. PSRAM & two USB ports

🛠️ Choosing a Development Platform

Arduino IDE is easy for beginners, simple but somewhat limited in functionality. In contrast PlatformIO is a much more powerful and versatile alternative which makes every task a breeze after getting familiar with it.

VSCode/PlatformIO provides some major advantages over the Arduino IDE:

• very comfortable and mighty code Editor with lots of shortcuts & integrated Intellisense features that make writing code a breeze
• usage of project file platformio.ini for controlling builds, adjusting serial monitor behaviour, enabling debugging, setting port parameters for software uploads (port, speed, RTS/CTS), etc.
• easy search for/integration of additional libraries
• integrated debugging functionality (additional external hardware required)
• integrated source control (github)
• etc.

❗ Application notes

If your particular board is not (yet) on the board list and you want to start programming it anyway then select another, already known board from the list which preferably is similar in features to your new board and you should be good to go.

However, in some cases you might not be able to fully utilize every board feature and build logs might report incorrect port numbers, memory sizes, etc. Provided example Test-ESP32-S3-1.9inch_RAM-PSRAM demonstrates how to reveal the true memory sizes of an ESP32 development board. Have a look at this example's files Build.log & Serial_Output.log to see above mentioned discrepancies.

⚡ Useful settings in platformio.ini

The project configuration file has sections (each denoted by a [header]) and one or multiple key/value pairs within the sections. Lines beginning with ";" are ignored and may be used to provide comments. The file platformio.ini is explained in more detail here.

Important: Different examples might require different build options, so always have a look at the platformio.ini file for relevant infos.

Some very useful general settings (for more experienced programmers) deserve to be mentioned here.

1. Forces builds to use older platform packages and/or frameworks instead of the newest one.

;platform = espressif32
platform = espressif32 @ 4.2.0
platform_packages = framework-arduinoespressif32 @ https://github.com/espressif/arduino-esp32/releases/download/2.0.4/esp32-2.0.4.zip
;platform_packages = framework-arduinoespressif32@https://github.com/espressif/arduino-esp32.git#2.0.3

2. Serial output lines carry time stamps, exceptions get decoded with function backtrace and serial output gets logged to a file:

monitor_filters = time, esp32_exception_decoder, log2file

3. The program is compiled with full symbolic debug information and no optimization.

build_type = debug

4. Enables usage of ESP32 JTAG debug adapter "ESP32-Prog" for debugging.

debug_tool = esp-prog

5. Sets the initial breakpoint to first line in function setup().

debug_init_break = tbreak setup

6. Generates various levels of debug output.

; 0 no debug output, 1 errors, 2 warnings, 3 infos, 4 debug info, 5 verbose 
build_flags = -DCORE_DEBUG_LEVEL=4

7. Disables any activity on COM signals RTS and/or DTR. Required by some ESP32 dev boards to enable serial output (e.g. ESP32-CAM-MB board). Be aware, this setting prevents the IDE from selecting boot modes and performing automatic software uploads to the board. In this case you must start the upload while pressing the boot mode button (usually named BOOT, PRG or IO0) for a few seconds.

monitor_rts = 0
monitor_dtr = 0

8. Switch between various built-in tables. A big collection of predefined tables can be found here.

;board_build.partitions = min_spiffs.csv
board_build.partitions = no_ota.csv

9. Your own "partitions_custom.csv" in the root of the project directory.

board_build.partitions = partitions_custom.csv

10. Collection of personal tasks, to be found under PlatformIO -> PROJECT TASKS -> Custom. Eventual paths are relative to the project folder.

extra_scripts = add_tasks.py

ℹ️ Resetting the board and uploading software via USB

The easiest way to reset an ESP32 dev board is to press the reset button (mostly labeled RST or EN). The easiest way to put the ESP32 into flash or upload mode is to press and release the reset button while holding down the button which selects the ESP32 boot mode (mostly labeled BOOT, PRG or IO0).

But have you ever wondered why your dev board sometimes is resetting when you start the Serial Monitor task and your development environment (PlatformIO or Arduino IDE) performs a successful software upload to the ESP32 and resets the board afterwards without prompting to press any button ?

Almost each ESP32 dev board contains a 2 transistor circuit which enables any IDE to auto reset the ESP32 chip or put it in boot mode.

Function and design of this little circuitry is explained in detail in folder reset_and_software_upload.

ℹ️ Debugging a program

Some practical hints on how to get started with debugging esp. with ESP32-Prog and ESP32-S3's builtin JTAG adapter I have put together in folder debugging.

Here a quick summary:

The ESP32 toolchain features a GNU online debugger (GDB). GDB relies on another task running in the background called OpenOCD (Online-Chip-Debugger for ESP32). This task interacts via USB with an JTAG adapter.

This JTAG adapter can be

• a separate external hardware (e.g. ESP32-Prog module) which is connected to the ESP32 JTAG pins, or
• integrated into the ESP32 chip itself (e.g ESP32-S3 with builtin JTAG adapter)

A general introduction to JTAG debugging is given on this webpage from Espressif. The picture below is taken from it.