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.
Under boards you find a (slowly growing) collection of programs for each board listed below. They will help you explore the features of those boards.
Examples are available for VSCode/PlatformIO and/or ArduinoIDE. Each example has it's own project directory (the ones for PlatformIO contain a platformio.ini file). Make sure you have the latest Arduino ESP32 development package installed.
Right now examples are provided for the following boards:
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.
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.
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.
A small selection of some very useful project settings (for more experienced programmers) deserve to be mentioned here.
- Forces builds to use alternative/older/additional platform packages/frameworks. Not all combinations will build successfully though.
;platform = espressif32
platform = espressif32@^6.9.0
;platform = espressif32@4.2.0
;platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
;platform = https://github.com/pioarduino/platform-espressif32/releases/download/51.03.07/platform-espressif32.zip
;
platform_packages =
; framework-arduinoespressif32@https://github.com/espressif/arduino-esp32/releases/download/3.1.0/esp32-3.1.0.zip
; framework-arduinoespressif32@https://github.com/espressif/arduino-esp32/releases/download/2.0.4/esp32-2.0.4.zip
; framework-arduinoespressif32@https://github.com/espressif/arduino-esp32.git#2.0.3
; platformio/tool-openocd-esp32@^2.1100.211028
platformio/tool-openocd-esp32
- 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
- Range of COM ports to be tried for upload and monitoring.
monitor_port = COM[34569]
upload_port = COM[34569]
- The program is compiled with full symbolic debug information and no optimization.
build_type = debug
- Enables usage of ESP32 JTAG debug adapter "ESP32-Prog" for debugging.
debug_tool = esp-prog
- Sets the initial breakpoint to first line in function setup().
debug_init_break = tbreak setup
- 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
- 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
- Use specific built-in partition tables, depending on actual flash size of your board variant (e.g. Board-Xyz-N4, Board-Xyz-N8R2, Board-Xyz-N16R8), the size of your program, OTA updates not needed, etc. A big collection of predefined partition tables can be found here. Below a small selection:
; boards with >=4MB Flash: standard partition sizes, OTA possible
board_build.partitions = default.csv
board_upload.flash_size = 4MB
board_upload.maximum_size = 4194304
; boards with >=4MB Flash: slightly bigger application, reduced spiffs partition, OTA possible
;board_build.partitions = min_spiffs.csv
;board_upload.flash_size = 4MB
;board_upload.maximum_size = 4194304
; boards with >=4MB Flash: bigger application, bigger spiffs partition, OTA no more possible
;board_build.partitions = no_ota.csv
;board_upload.flash_size = 4MB
;board_upload.maximum_size = 4194304
; boards with >=4MB Flash: even bigger application, small spiffs partition, OTA not possible
;board_build.partitions = huge_app.csv
;board_upload.flash_size = 4MB
;board_upload.maximum_size = 4194304
; standard partitions for boards with >=8MB Flash
;board_build.partitions = default_8MB.csv
;board_upload.flash_size = 8MB
;board_upload.maximum_size = 8388608
; standard partitions for boards with >=16MB Flash
;board_build.partitions = default_16MB.csv
;board_upload.flash_size = 16MB
;board_upload.maximum_size = 16777216
- You can even define your own partition tables. Copy an existing (and ideally almost matching) *.csv file into the root of your project directory, rename it to "partitions_custom.csv" and edit the partition settings as needed (e.g. size, offset).
board_build.partitions = partitions_custom.csv
- 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
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.
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.
Probably the most frustrating part of coding is provoking a core to panic/to crash which in most cases looks similar to this:
23:29:09.416 > Guru Meditation Error: Core 1 panic'ed (IntegerDivideByZero). Exception was unhandled.
23:29:09.476 >
23:29:09.476 > Core 1 register dump:
23:29:09.479 > PC : 0x4200193b PS : 0x00060430 A0 : 0x820019bb A1 : 0x3fcebf40
23:29:09.486 > A2 : 0x00000003 A3 : 0x00000001 A4 : 0x00000000 A5 : 0x0000e100
...
However, don't panic ! A quick guide how to read aboves message and discover the cause of pain I have put together in folder debugging_without_JTAG.