RIOT/cpu/esp32

RIOT-OS for Espressif ESP32 MCUs

Table of Contents

1. Overview
2. Short Configuration Reference
3. MCU ESP32
   1. Features of ESP32
   2. Features Supported by RIOT-OS
   3. Limitations of the RIOT-port
4. Toolchain
   1. RIOT Docker Toolchain (riotdocker)
   2. Manual Toolchain Installation
5. Flashing the Device
   1. Toolchain Usage
   2. Compile Options
   3. Flash Modes
   4. ESP-IDF Heap Implementation
6. Common Peripherals
   1. GPIO pins
   2. ADC Channels
   3. DAC Channels
   4. I2C Interfaces
   5. PWM Channels
   6. SPI Interfaces
   7. Timers
   8. UART Interfaces
   9. CAN Interfaces
   10. Other Peripherals
7. Special On-board Peripherals
   1. SPI RAM Modules
   2. SPIFFS Device
8. Network Interfaces
   1. Ethernet MAC Network Interface
   2. ESP-NOW Network Interface
   3. Other Network Devices
9. Application-Specific Configurations
   1. Make Variable CONFIGS
   2. Application-Specific Board Configuration
   3. Application-Specific Driver Configuration
10. Debugging
    1. JTAG Debugging
    2. QEMU Mode and GDB

Overview  [TOC]

RIOT-Xtensa-ESP is a bare metal implementation of RIOT-OS for ESP32 SOCs which supports most features of RIOT-OS. The peripheral SPI and I2C interfaces allow to connect all external hardware modules supported by RIOT-OS, such as sensors and actuators. SPI interface can also be used to connect external IEEE802.15.4 modules to integrate ESP32 boards into a GNRC network.

Although the port does not use the official ESP-IDF (Espresso IoT Development Framework) SDK, it must be installed for compilation. The reason is that the port uses most of the ESP32 SOC definitions provided by the ESP-IDF header files. In addition, it needs the hardware abstraction library (libhal), and the ESP32 WiFi stack binary libraries which are part of the ESP-IDF SDK.

Short Configuration Reference  [TOC]

The following table gives a short reference of all board configuration parameters used by the ESP32 port in alphabetical order.

Parameter	Short Description	Type*
ADC_GPIOS	GPIOs that can be used as ADC channels	m
CAN_TX	GPIO used as CAN tranceiver TX signal	o
CAN_RX	GPIO used as CAN tranceiver RX signal	o
DAC_GPIOS	GPIOs that can be used as DAC channels	m
I2C0_SPEED	Bus speed of I2C_DEV(0)	o
I2C0_SCL	GPIO used as SCL for I2C_DEV(0)	o
I2C0_SDA	GPIO used as SCL for I2C_DEV(0	o
I2C1_SPEED	Bus speed of I2C_DEV(1)	o
I2C1_SCL	GPIO used as SCL for I2C_DEV(1)	o
I2C1_SDA	GPIO used as SCL for I2C_DEV(1)	o
PWM0_GPIOS	GPIOs that can be used at channels of PWM_DEV(0)	o
PWM1_GPIOS	GPIOs that can be used at channels of PWM_DEV(1)	o
SPI0_DEV	SPI Interface used as SPI_DEV(0), can be VSPI HSPI (FSPI)	o
SPI0_SCK	GPIO used as SCK for SPI_DEV(0)	o
SPI0_MOSI	GPIO used as MOSI for SPI_DEV(0)	o
SPI0_MISO	GPIO used as MISO for SPI_DEV(0)	o
SPI0_CS0	GPIO used as default CS for SPI_DEV(0)	o
SPI1_DEV	SPI Interface used as SPI_DEV(1), can be VSPI HSPI (FSPI)	o
SPI1_SCK	GPIO used as SCK for SPI_DEV(1)	o
SPI1_MOSI	GPIO used as MOSI for SPI_DEV(1)	o
SPI1_MISO	GPIO used as MISO for SPI_DEV(1)	o
SPI1_CS0	GPIO used as default CS for SPI_DEV(1)	o
SPI2_DEV	SPI Interface used as SPI_DEV(2), can be VSPI HSPI (FSPI)	o
SPI2_SCK	GPIO used as SCK for SPI_DEV(2)	o
SPI2_MOSI	GPIO used as MOSI for SPI_DEV(2)	o
SPI2_MISO	GPIO used as MISO for SPI_DEV(2)	o
SPI2_CS0	GPIO used as default CS for SPI_DEV(2)	o
UART1_TXD	GPIO used as TxD for UART_DEV(1)	o
UART1_RXD	GPIO used as RxD for UART_DEV(1)	o
UART2_TXD	GPIO used as TxD for UART_DEV(2)	o
UART2_RXD	GPIO used as RxD for UART_DEV(2)	o

*Type: m - mandatory, o - optional

The following table gives a short reference in alphabetical order of modules that can be enabled/disabled by board configurations and/or application's makefile using USEMODULE and DISABLE_MODULE.

Module	Default	Short description
esp_can	not used	enable the ESP32 CAN device
esp_eth	not used	enable the ESP32 EMAC network device
esp_gdb	not used	enable the compilation with debug information for debugging
esp_hw_counter	not used	use hardware counters for RIOT timers
esp_i2c_hw	not used	use the i2C hardware implementation
esp_idf_heap	not used	enable ESP-IDF heap implementation
esp_now	not used	enable the ESP-NOW network device
esp_spi_ram	not used	enable SPI RAM
esp_spiffs	not used	enable SPIFFS for on-board flash memory

MCU ESP32  [TOC]

ESP32 is a low-cost, ultra-low-power, single or dual-core SoCs from Espressif Systems with integrated WiFi and dual-mode BT module. The processor core is based on the Tensilica Xtensa LX6 32-bit Controller Processor Core.

Features of ESP32  [TOC]

The key features of ESP32 are:

MCU	ESP32	Supported by RIOT
Vendor	Espressif
Cores	1 or 2 x Tensilica Xtensa LX6	1 core
FPU	yes (ULP - Ultra low power co-processor)	no
RAM	520 kByte SRAM 16 kByte RTC SRAM	yes
ROM	520 kByte	yes
Flash	512 kByte ... 16 MByte	yes
Frequency	240 MHz, 160 MHz, 80 MHz	yes
Power Consumption	68 mA @ 240 MHz 44 mA @ 160 MHz 31 mA @ 80 MHz 5 uA in deep sleep mode	yes yes yes no
Timers	4 x 64 bit	yes
ADCs	2 x SAR-ADC with up to 18 x 12 bit channels total	yes
DACs	2 x DAC with 8 bit	yes
GPIOs	34 (6 of them are only inputs)	yes
I2Cs	2	yes
SPIs	4	yes
UARTs	3	yes
WiFi	IEEE 802.11 b/g/n built in	yes
Bluetooth	v4.2 BR/EDR and BLE	no
Ethernet	MAC interface with dedicated DMA and IEEE 1588 support	yes
CAN	version 2.0	no
IR	up to 8 channels TX/RX	no
Motor PWM	2 devices x 6 channels	yes
LED PWM	16 channels	no
Crypto	Hardware acceleration of AES, SHA-2, RSA, ECC, RNG	no
Vcc	2.5 - 3.6 V
Documents	Datasheet Technical Reference

Please note: Even if used ESP32 SoC is a dual-core version, RIOT-OS uses only one core.

Rather than using the ESP32 SoC directly, ESP32 boards use an ESP32 module from Espressif which integrates additionally to the SoC some key components, like SPI flash memory, SPI RAM, or crystal oscillator. Some of these components are optional. A good overview about available modules can be found in the Online documentation of ESP-IDF.

Most common modules used by ESP32 boards are the ESP32-WROOM-32 and ESP32-WROVER.

Features Supported by RIOT-OS  [TOC]

The RIOT-OS for ESP32 SoCs supports the following features at the moment:

• I2C interfaces
• SPI interfaces
• UART interfaces
• CPU ID access
• RTC module
• ADC and DAC channels
• PWM channels
• SPI RAM
• SPI Flash Drive (MTD with SPIFFS and VFS)
• Hardware number generator
• Hardware timer devices
• ESP-NOW netdev interface
• ESP Ethernet MAC (EMAC) netdev interface

Limitations of the RIOT port  [TOC]

The implementation of RIOT-OS for ESP32 SOCs has the following limitations at the moment:

• Only one core (the PRO CPU) is used because RIOT does not support running multiple threads simultaneously.
• AP-based WiFi is experimental and not stable.
• RIOT modules crypto and hashes cannot be used together with modules esp_now and esp_wifi
• Bluetooth cannot be used at the moment.
• Flash encryption is not yet supported.

Toolchain

Following software components are required for compilation:

• Xtensa GCC compiler suite for ESP32
• ESP-IDF SDK which includes all ESP32 SOC definitions, the hardware abstraction library libhal.a, and the flash programmer tool esptool.py

There are two options to install the Toolchain:

• riotdocker image, see section RIOT Docker Toolchain (riotdocker)
• manual installation, see section Manual Toolchain Installation

RIOT Docker Toolchain (riotdocker)  [TOC]

The easiest way to use install the toolchain is the RIOT Docker image riotdocker. The compilation process using Docker consists of two steps

1. making the RIOT application in Docker with command make BOARD= ...
2. flashing the RIOT application on the host computer with command make flash-only BOARD=...

where step 2 requires that the flasher program esptool.py is installed.

Preparing the Environment  [TOC]

Using RIOT Docker requires at least the following software:

• Docker container virtualization software
• RIOT Docker (riotdocker) image
• flasher tool esptool.py

For information about installing Docker on your host, refer to the appropriate manuals for your operating system. For example, the easiest way to install Docker on the Ubuntu/Debian system is:

sudo apt-get install docker.io

The ESP flasher program esptool.py is available at GitHub. Don't use the the esptool package of your OS. esptool.py requires either Python 2.7 or Python 3.4 or later. The latest stable version of esptool.py can be installed with pip:

pip install esptool

esptool.py depends on pySerial which can be installed either using pip

pip install pyserial

or the package manager of your OS, for example on Debian/Ubuntu systems:

apt-get install pyserial

For more information on esptool.py, please refer the git repository

Please make sure that esptool.py is in your PATH variable.

Generating a riotdocker Image  [TOC]

A riotdocker fork that only installs the RIOT-Xtensa-ESP32-toolchain is available at GitHub. After cloning this git repository, you can use branch esp32_only to generate a Docker image with a size of "only" 990 MByte:

git clone https://github.com/gschorcht/riotdocker-Xtensa-ESP.git
cd riotdocker-Xtensa-ESP
git checkout esp32_only
docker build -t riotbuild .

A riotdocker version that contains the toolchains for all different RIOT platforms can be found at GitHub. However, the Docker image generated from the this Docker file has a size of about 1.5 GByte.

Once a Docker image has been created, it can be started with the following commands while in the RIOT root directory:

cd /path/to/RIOT
docker run -i -t --privileged -v /dev:/dev -u $UID -v $(pwd):/data/riotbuild riotbuild

Please note: RIOT's root directory /path/to/RIOT becomes visible as the home directory of the riotbuild user in the Docker image. That is, the output of compilations performed in RIOT Docker is also accessible on the host system.

Please refer the RIOT wiki on how to use the Docker image to compile RIOT OS.

Using an Existing riotdocker Image  [TOC]

Alternatively, an existing Docker image from Docker Hub can be used. You can either pull and start the schorcht/riotbuild_esp32 Docker image which only contains the RIOT-Xtensa-ESP32-toolchain using

cd /path/to/RIOT
docker run -i -t --privileged -v /dev:/dev -u $UID -v $(pwd):/data/riotbuild schorcht/riotbuild_esp32

or the riot/riotbuild Docker image (size is about 1.5 GB) which contains the toolchains for all platforms using

cd /path/to/RIOT
docker run -i -t --privileged -v /dev:/dev -u $UID -v $(pwd):/data/riotbuild riot/riotbuild

Make Process with Docker Image  [TOC]

Using Docker, the make process consists of the following two steps:

1. making the RIOT binary within a RIOT Docker image
2. flashing the RIOT binary using a flasher program on the host system

Once the RIOT Docker image has been started from RIOT's root directory, a RIOT application can be compiled inside the Docker using the make command as usual, for example:

make BOARD=esp32-esp-12x -C tests/shell ...

This will generate a RIOT binary in ELF format.

Please note: You can't use the flash target inside the Docker image.

The RIOT binary has to be flash outside docker on the host system. Since the Docker image was stared while in RIOT's root directory, the output of the compilations is also accessible on the host system. On the host system, the flash-only target can then be used to flash the binary.

make flash-only BOARD=esp32-esp-12x -C tests/shell

Manual Toolchain Installation  [TOC]

A more difficult way to install the toolchain is the manual installation of required components as described below.

Please note: To use the precompiled toolchain the following packages (Debian/Ubuntu) have to be installed:
build-essential cppcheck coccinelle curl doxygen git graphviz make pcregrep python python-serial python3 python3-flake8 unzip wget

Installation of Xtensa GCC compiler suite  [TOC]

Xtensa GCC compiler for ESP32 can be downloaded and installed as precompiled binary archive from GitHub.

mkdir -p $HOME/esp
cd $HOME/esp
git clone https://github.com/gschorcht/xtensa-esp32-elf.git

Once the compiler is installed you can add the binary directory to your PATH variable.

export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin

Installation of ESP-IDF (Espressif IoT Development Framework)  [TOC]

ESP-IDF, the official SDK from Espressif, can be downloaded and installed as GIT repository.

cd $HOME/esp
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
git checkout -q f198339ec09e90666150672884535802304d23ec
cd components/esp32/lib
git checkout -q 534a9b14101af90231d40a4f94924d67bc848d5f

Please note: Please take care to checkout correct branches which were used for the port. Newer versions might also work but were not tested.

Since we only use a few header files, ESP-IDF does not need to be compiled in any way. To use the installed ESP-IDF, just set the variable ESP32_SDK_DIR accordingly.

export ESP32_SDK_DIR=$HOME/esp/esp-idf

Flashing the Device  [TOC]

Toolchain Usage  [TOC]

Once you have installed all required components, you should have the following directories.

/path/to/esp/esp-idf
/path/to/esp/xtensa-esp32-elf

To use the toolchain and optionally the SDK, please check that your environment variables are set correctly to

export ESP32_SDK_DIR=/path/to/esp/esp-idf
export PATH=$PATH:/path/to/esp/xtensa-esp32-elf/bin

To compile an application for an ESP32 board, change to RIOT's root directory and execute the make command, e.g.,

make flash BOARD=esp32-generic -C tests/shell [Compile Options]

where the BOARD variable specifies the generic ESP32 board definition and option -C the directory of application.

Compile Options  [TOC]

The compilation process can be controlled by a number of variables for the make command:

Option	Values	Default	Description
CONFIGS	string	empty	Override default board and driver configurations, see section Application-Specific Configurations.
FLASH_MODE	dout, dio, qout, qio	dout	Set the flash mode, see section Flash Modes
PORT	/dev/*	/dev/ttyUSB0	Set the port for flashing the firmware.
QEMU	0, 1	0	Generate an image for QEMU, see section QEMU Mode and GDB.

Optional features of ESP32 can be enabled by USEMODULE definitions in the makefile of the application. These are:

Module	Description
esp_now	Use the built-in WiFi module with the ESP-NOW protocol as netdev network device, see section ESP-NOW Network Interface.
esp_eth	Use the Ethernet MAC (EMAC) interface as netdev network device, see section Ethernet Network Interface.
esp_gdb	Enable the compilation with debug information for debugging with QEMU and GDB (QEMU=1) or via JTAG interface with OpenOCD.
esp_i2c_hw	Use the hardware I2C implementation, see section I2C Interfaces.
esp_idf_heap	Use the ESP-IDF heap implementation, see section ESP-IDF Heap Implementation.
esp_spiffs	Enable the optional SPIFFS drive in on-board flash memory, see section SPIFFS Device.
esp_spi_ram	Enable the optional SPI RAM, see section SPI RAM Modules.
esp_can	Enable the ESP32 CAN device, see section CAN Interfaces.

For example, to activate the a SPIFFS drive in on-board flash memory, the makefile of application has simply to add the esp_spiffs module to USEMODULE make variable:

USEMODULE += esp_spiffs

Modules can be also be activated temporarily at the command line when calling the make command:

USEMODULE="esp_spiffs" make BOARD=...

Flash Modes  [TOC]

The FLASH_MODE make command variable determines the mode that is used for flash access in normal operation.

The flash mode determines whether 2 data lines (dio and dout) or 4 data lines (qio and qout) for addressing and data access. For each data line, one GPIO is required. Therefore, using qio or qout increases the performance of SPI Flash data transfers, but uses two additional GPIOs (GPIO9 and GPIO10). That is, in this flash modes these GPIOs are not available for other purposes. If you can live with lower flash data transfer rates, you should always use dio or dout to keep GPIO9 and GPIO10 free for other purposes.

For more information about these flash modes, refer the documentation of esptool.py.

ESP-IDF Heap Implementation  [TOC]

ESP-IDF SDK provides a complex heap implementation that supports multiple heap segments in different memory areas such as DRAM, IRAM, and PSRAM. Whenever you want to use these memory areas as heap, you have to use the heap implementation from the ESP-IDF SDK. ESP-IDF heap is not used by default. To use it, it has to be enabled by the the makefile of the application:

USEMODULE += esp_heap

Please note: ESP-IDF heap implementation is used by default, when the following modules are used: esp_spi_ram

Common Peripherals  [TOC]

ESP32 is an SoC and has a lot of peripherals that are not all supported by the RIOT port. This section describs the supported peripherals and how they have to be configured.

GPIO pins  [TOC]

ESP32 has 34 GPIO pins, where only a subset can be used as output, as ADC channel, as DAC channel and in deep sleep mode. Some of them are used by special SoC components, e.g., as touch sensors. The following table gives a short overview.

Pin	Type	ADC	PU/PD	Special function	Remarks
GPIO0	In/Out	yes	yes	Touch sensor	Bootstrapping, pulled up
GPIO1	In/Out	-	yes	UART0 TxD	Console
GPIO2	In/Out	yes	yes	Touch sensor	Bootstrapping, pulled down
GPIO3	In/Out	-	yes	UART0 RxD	Console
GPIO4	In/Out	yes	yes	Touch sensor	-
GPIO5	In/Out	-	yes	-	-
GPIO6	In/Out	-	yes	Flash SD_CLK	-
GPIO7	In/Out	-	yes	Flash SD_DATA0	-
GPIO8	In/Out	-	yes	Flash SD_DATA1	-
GPIO9	In/Out	-	yes	Flash SD_DATA2	only in qoutand qiomode, see section Flash Modes
GPIO10	In/Out	-	yes	Flash SD_DATA3	only in qoutand qiomode, see section Flash Modes
GPIO11	In/Out	-	yes	Flash SD_CMD	-
GPIO12	In/Out	yes	yes	MTDI / Touch sensor	JTAG interface / Bootstrapping, pulled down
GPIO13	In/Out	yes	yes	MTCK / Touch sensor	JTAG interface
GPIO14	In/Out	yes	yes	MTMS / Touch sensor	JTAG interface
GPIO15	In/Out	yes	yes	MTDO / Touch sensor	JTAG interface / Bootstrapping, pulled up
GPIO16	In/Out	-	yes	-	usually not available when SPI RAM is used
GPIO17	In/Out	-	yes	-	usually not available when SPI RAM is used
GPIO18	In/Out	-	yes	-	-
GPIO19	In/Out	-	yes	-	-
GPIO21	In/Out	-	yes	-	-
GPIO22	In/Out	-	yes	-	-
GPIO23	In/Out	-	yes	-	-
GPIO25	In/Out	yes	yes	DAC1	-
GPIO26	In/Out	yes	yes	DAC2	-
GPIO27	In/Out	yes	yes	Touch sensor	-
GPIO32	In/Out	yes	yes	XTAL32_P	can be used to connect an external 32 kHz crystal
GPIO33	In/Out	yes	-	XTAL32_N	can be used to connect an external 32 kHz crystal
GPIO34	In	yes	-	VDET	-
GPIO35	In	yes	-	VDET	-
GPIO36	In	yes	-	SENSOR_VP	-
GPIO37	In	yes	-	SENSOR_CAPP	usually not broken out
GPIO38	In	yes	-	SENSOR_CAPN	usually not broken out
GPIO38	In	yes	-	SENSOR_VN	-

ADC: these pins can be used as ADC inputs
PU/PD: these pins have software configurable pull-up/pull-down functionality.

Please note: GPIOs that can be used as ADC channels are also available as low power digital inputs/outputs in deep sleep mode.

GPIO0, GPIO2 are bootstrapping pins which are used to boot ESP32 in different modes:

GPIO0	GPIO2	Mode
1	X	boot in FLASH mode to boot the firmware from flash (default mode)
0	0	boot in UART mode for flashing the firmware

Please note: GPIO2 becomes the SPI MISO signal for boards that use the HSPI interface as SD-Card interface in 4-bit SD mode. On these boards all signals of the SD-Card interface are pulled up. Because of the bootstrapping functionality of GPIO2, it can become necessary to either press the Boot button, remove the SD card or remove the peripheral hardware to flash RIOT.

ADC Channels  [TOC]

ESP32 integrates two 12-bit ADCs (ADC1 and ADC2) capable of measuring up to 18 analog signals in total. Most of these ADC channels are either connected to a number of integrated sensors like a Hall sensors, touch sensors and a temperature sensor or can be connected with certain GPIOs. Integrated sensors are disabled in RIOT's implementation and are not accessible. Thus, up to 18 GPIOs, can be used as ADC inputs:

• ADC1 supports 8 channels: GPIOs 32-39
• ADC2 supports 10 channels: GPIOs 0, 2, 4, 12-15, 25-27

These GPIOs are realized by the RTC unit and are therefore also called RTC GPIOs or RTCIO GPIOs.

Please note: GPIO37 and GPIO38 are usually not broken out on ESP32 boards and are therefore not usable.

The GPIOs that can be used as ADC channels for a given board are defined by the ADC_GPIOS macro in the board-specific peripheral configuration. This configuration can be changed by application-specific configurations.

Example:

#define ADC_GPIOS   { GPIO0, GPIO2, GPIO4 }

The order of the listed GPIOs determines the mapping between the RIOT's ADC lines and the GPIOs. The maximum number of GPIOs in the list is ADC_NUMOF_MAX which is defined to be 16.

ADC_NUMOF is determined automatically from ADC_GPIOS list and must not be changed.

Please note:

• ADC_GPIOS must be defined even if there are no GPIOs that could be used as ADC channels on the board. In this case, an empty list hast to be defined which just contains the curly braces.
• As long as the GPIOs listed in ADC_GPIOS are not initialized as ADC channels with the adc_init function, they can be used for other purposes.

For each ADC line, an attenuation of the input signal can be defined separately with the adc_set_attenuationfunction.

extern int adc_set_attenuation(adc_t line, adc_attenuation_t atten);

This results in different full ranges of the measurable voltage at the input. The attenuation can be set to 0 dB, 3 dB, 6 dB and 11 dB, with 11 dB being the standard attenuation. Since an ADC input is measured against a reference voltage Vref of 1.1 V, approximately the following measurement ranges are given when using a corresponding attenuation:

Attenuation	Voltage Range	Symbol
0 dB	0 ... 1.1V (Vref)	ADC_ATTENUATION_0_DB
3 dB	0 ... 1.5V	ADC_ATTENUATION_3_DB
6 dB	0 ... 2.2V	ADC_ATTENUATION_6_DB
11 dB (default)	0 ... 3.3V	ADC_ATTENUATION_11_DB

Please note: The reference voltage Vref can vary from device to device in the range of 1.0V and 1.2V. The Vref of a device can be read with the adc_vref_to_gpio25 function at GPIO 25.

extern int adc_vref_to_gpio25 (void);

For that purpose GPIO25 is initialized automatically as ADC channel and is connected internally to Vref to measure the current voltage. Once the initialization is finished and the function returns with success, the current voltage can be read from GPIO25. The results of the ADC input can then be adjusted accordingly. The adc_vref_to_gpio25 function can be used to determine the current voltage at ESP32.

DAC Channels  [TOC]

ESP32 supports 2 DAC lines at GPIO25 and GPIO26. These DACs have a width of 8 bits and produce voltages in the range from 0 V to 3.3 V (VDD_A). The 16 bits DAC values given as parameter of function dac_set are down-scaled to 8 bit.

The GPIOs that can be used as DAC channels for a given board are defined by the DAC_GPIOS macro in the board-specific peripheral configuration. This configuration can be changed by application-specific configurations.

Example:

#define DAC_GPIOS   { GPIO25, GPIO26 }

The order of the listed GPIOs determines the mapping between the RIOT's DAC lines and the GPIOs. The maximum number of GPIOs in the list is DAC_NUMOF_MAX which is defined to be 16.

DAC_NUMOF is determined automatically from DAC_GPIOS list and must not be changed.

Please note:

• DAC_GPIOS must be defined even if there are no GPIOs that could be used as DAC channels on the board. In this case, an empty list hast to be defined which just contains the curly braces.
• As long as the GPIOs listed in DAC_GPIOS are not initialized as DAC channels with the dac_init function, they can be used for other purposes.

I2C Interfaces  [TOC]

The ESP32 has two built-in I2C hardware interfaces that support I2C bus speed up to 400 kbps (I2C_SPEED_FAST).

The board-specific configuration of the I2C interface I2C_DEV(n) requires the definition of

• I2Cn_SPEED, the bus speed,
• I2Cn_SCL, the GPIO used as SCL signal, and
• I2Cn_SDA, the GPIO used as SDA signal,

where n can be 0 or 1. If they are not defined, the I2C interface I2C_DEV(n) is not used.

Example:

#define I2C0_SPEED  I2C_SPEED_FAST
#define I2C0_SCL    GPIO22
#define I2C0_SDA    GPIO21

#define I2C1_SPEED  I2C_SPEED_NORMAL
#define I2C1_SCL    GPIO13
#define I2C1_SDA    GPIO16

Please note: The configuration of the I2C interfaces I2C_DEV(n) must be in continuous ascending order of n.

I2C_NUMOF is determined automatically from board-specific peripheral definitions of I2Cn_SPEED, I2Cn_SCK, and I2Cn_SDA.

The following table shows the default configuration of I2C interfaces used for a large number of boards. It can be changed by application-specific configurations.

Device	Signal	Pin	Symbol	Remarks
I2C_DEV(0)	SCL	GPIO22	I2C0_SCL	-
I2C_DEV(0)	SDA	GPIO21	I2C0_SDA	-

Please note: The GPIOs listed in the configuration are only initialized as I2C signals when the periph_i2c module is used. Otherwise they are not allocated and can be used for other purposes.

Beside the I2C hardware implementation, a I2C bit-banging protocol software implementation can be used. This implementation allows bus speeds up to 1 Mbps (I2C_SPEED_FAST_PLUS). It can be activated by adding

USEMODULE += esp_i2c_hw

to application's makefile. The Disadvantage of the software implementation is that it uses busy waiting.

Please note: The hardware implementation seems to be very poor and faulty. I2C commands in the I2C command pipeline are sporadically not executed. A number of ACK errors and timeouts caused by protocol errors are the result. The hardware implementation is recommended only if they can be tolerated. Therefore, the software implementation is used by default.

PWM Channels  [TOC]

ESP supports two types of PWM generators

• one LED PWM controller (LEDPWM) with 16 channels, and
• two high-speed Motor Control PWM controllers (MCPWM) with 6 channels each.

The PWM implementation uses the ESP32's high-speed MCPWM modules. Reason is that the LED PWM controller only supports resolutions of powers of two.

ESP32 has 2 MCPWM modules, each with up to 6 channels (PWM_CHANNEL_NUM_DEV_MAX). Thus, the maximum number of PWM devices is 2 and the maximum total number of PWM channels is 12. These 2 MCPWM devices are used as RIOT PWM devices PWM_DEV(0) and PWM_DEV(1).

The GPIOs that can be used as PWM channels of RIOT's PWM devices are defined by the PWM0_GPIOS and PWM1_GPIOS macros in the board-specific peripheral configuration. This configuration can be changed by application specific configurations.

Example:

#define PWM0_GPIOS { GPIO9, GPIO10 }
#define PWM1_GPIOS { }

The order of the listed GPIOs determines the mapping between RIOT's PWM channels and the GPIOs. Board definitions usually declare a number of GPIOs as PWM channels.

Please note: The definition of PWM0_GPIOS and PWM1_GPIOS can be omitted or empty. In the latter case, they must at least contain the curly braces. The corresponding PWM device can not be used in this case.

PWM_NUMOF is determined automatically from the PWM0_GPIOS and PWM1_GPIOS definitions and must not be changed.

Please note: As long as the GPIOs listed in PWM0_GPIOS and PMW1_GPIOS are not initialized as PWM channels with the pwm_init function, they are not allocated and can be used other purposes.

SPI Interfaces  [TOC]

ESP32 integrates four SPI controllers:

• controller SPI0 is reserved for accessing flash memory
• controller SPI1 realizes interface FSPI and shares its signals with SPI0
• controller SPI2 realizes interface HSPI that can be used for peripherals
• controller SPI3 realizes interface VSPI that can be used for peripherals

Since controller SPI0 is used to access flash and other external memories, at most three interfaces can be used:

• VSPI: with configurable pin definitions
• HSPI: with configurable pin definitions
• FSPI: with fixed pin definitions except the CS signal.

All SPI interfaces could be used in quad SPI mode, but RIOT's low level device driver doesn't support it.

Please note:

• Since the FSPI interface shares its bus signals with the controller that implements the flash memory interface, we use the name FSPI for this interface. In the technical reference, this interface is misleadingly simply referred to as SPI.
• Since the FSPI interface shares its bus signals with flash memory interface and optionally other external memories, you can only use this SPI interface to attach external memory with same SPI mode and same bus speed but with a different CS. It is strictly not recommended to use this interface for other peripherals.
• Using FSPI for anything else can disturb flash memory access which causes a number of problems. If not really necessary, you should not use this interface.

The board-specific configuration of the SPI interface SPI_DEV(n) requires the definition of

• SPIn_DEV, the interface used for SPI_DEV(n), can be VSPI, HSPI, or FSPI,
• SPIn_SCK, the GPIO used as clock signal for SPI_DEV(n) (fixed for FSPI),
• SPIn_MISO, the GPIO used as MISO signal for SPI_DEV(n) (fixed for FSPI),
• SPIn_MOSI, the GPIO used as MOSI signal for SPI_DEV(n) (fixed for FSPI), and
• SPIn_CS0, the GPIO used as CS signal for SPI_DEV(n) when cs parameter in spi_acquire is GPIO_UNDEF,

where n can be 0, 1 or 2. If they are not defined, the SPI interface SPI_DEV(n) is not used.

Example:

#define SPI0_DEV    VSPI
#define SPI0_SCK    GPIO18      /* SCK  Periphery */
#define SPI0_MISO   GPIO19      /* MISO Periphery */
#define SPI0_MOSI   GPIO23      /* MOSI Periphery */
#define SPI0_CS0    GPIO5       /* CS0  Periphery */

#define SPI1_DEV    HSPI
#define SPI1_SCK    GPIO14      /* SCK  Camera */
#define SPI1_MISO   GPIO12      /* MISO Camera */
#define SPI1_MOSI   GPIO13      /* MOSI Camera */
#define SPI1_CS0    GPIO15      /* CS0  Camera */

The pin configuration of VSPI interface and the HSPI interface can be changed by application specific configurations.

Please note:

• The configuration of the SPI interfaces SPI_DEV(n) must be in continuous ascending order of n.
• The order in which the interfaces VSPI, HSPI, and FSPI are used doesn't matter. For example, while one board may only use the HSPI interface as SPI_DEV(0), another board may use the VSPI interface as SPI_DEV(0) and the HSPI interface as SPI_DEV(1).
• The GPIOs listed in the configuration are first initialized as SPI signals when the corresponding SPI interface is used by calling either the spi_init_cs function or the spi_acquire function. That is, they are not allocated as SPI signals before and can be used for other purposes as long as the SPI interface is not used.
• GPIO2 becomes the MISO signal in SPI mode on boards that use the HSPI as the SD card interface in 4-bit SD mode. Because of the bootstrapping functionality of the GPIO2, it can be necessary to either press the Boot button, remove the SD card or remove the peripheral hardware to flash RIOT.

SPI_NUMOF is determined automatically from the board-specific peripheral definitions of SPI_DEV(n).

The following table shows the pin configuration used for most boards, even though it can vary from board to board.

Device	Signal	Pin	Symbol	Remarks
VSPI	SCK	GPIO18	SPI0_SCK	optional, can be overridden
VSPI	MISO	GPIO19	SPI0_MISO	optional, can be overridden
VSPI	MOSI	GPIO23	SPI0_MOSI	optional, can be overridden
VSPI	CS0	GPIO18	SPI0_CS0	optional, can be overridden
HSPI	SCK	GPIO14	SPI1_SCK	optional, can be overridden
HSPI	MISO	GPIO12	SPI1_MISO	optional, can be overridden
HSPI	MOSI	GPIO13	SPI1_MOSI	optional, can be overridden
HSPI	CS0	GPIO15	SPI1_CS0	optional, can be overridden
FSPI	SCK	GPIO6	-	not configurable
FSPI	CMD	GPIO11	-	not configurable
FSPI	SD0	GPIO7	-	not configurable
FSPI	SD1	GPIO8	-	not configurable
FSPI	SD2	GPIO9	-	not configurable, only used in qio or qout mode
FSPI	SD3	GPIO10	-	not configurable, only used in qio or qout mode

Some boards use the HSPI as SD-Card interface (SDIO) in 4-bit SD mode.

Device|Pin | SD 4-bit mode | SPI mode :-----|:------:|:-------------:|:----------: HSPI | GPIO14 | CLK | SCK HSPI | GPIO15 | CMD | CS0 HSPI | GPIO2 | DAT0 | MISO HSPI | GPIO4 | DAT1 | - HSPI | GPIO12 | DAT2 | - HSPI | GPIO13 | DAT3 | MOSI

On these boards, all these signals are pulled up. This may cause flashing problems due to the bootstrap function of the GPIO2 pin, see section GPIO pins.

Timers  [TOC]

There are two different implementations for hardware timers.

• Timer Module implementation It provides 4 high-speed timers, where 1 timer is used for system time. The remaining 3 timer devices with 1 channel each can be used as RIOT timer devices with a clock rate of 1 MHz.
• Counter implementation It uses CCOUNT/CCOMPARE registers to implement 2 timer devices with 1 channel each and a clock rate of 1 MHz.

By default, the hardware timer module is used. To use the hardware counter implementation, add

USEMODULE += esp_hw_counter

to application's makefile.

Timers are MCU built-in features and not board-specific. There is nothing to be configured.

UART Interfaces  [TOC]

ESP32 supports up to three UART devices. UART_DEV(0) has a fixed pin configuration and is always available. All ESP32 boards use it as standard configuration for the console.

The pin configuration of UART_DEV(1) and UART_DEV(2) are defined in board specific peripheral configuration by

• UARTn_TXD, the GPIO used as TxD signal, and
• UARTn_RXD, the GPIO used as RxD signal,

where n can be 2 or 3. If they are not defined, the UART interface UART_DEV(n) is not used.

UART_NUMOF is determined automatically from the board-specific peripheral definitions of UARTn_TXD and UARTn_RXD and must not be changed.

The following default pin configuration of UART interfaces as used by a most boards can be overridden by the application, see section Application-Specific Configurations.

Device	Signal	Pin	Symbol	Remarks
UART_DEV(0)	TxD	GPIO1	UART0_TXD	cannot be changed
UART_DEV(0)	RxD	GPIO3	UART0_RXD	cannot be changed
UART_DEV(1)	TxD	GPIO10	UART1_TXD	optional, can be overridden
UART_DEV(1)	RxD	GPIO9	UART1_RXD	optional, can be overridden
UART_DEV(2)	TxD	GPIO17	UART2_TXD	optional, can be overridden
UART_DEV(2)	RxD	GPIO16	UART2_RXD	optional, can be overridden

Example:

#define UART1_TXD   GPIO10      /* UART_DEV(1) TxD */
#define UART1_RXD   GPIO9       /* UART_DEV(1) RxD */

CAN Interfaces  [TOC]

The ESP32 intregates a CAN controller which is compatible with the NXP SJA1000 CAN controller. Thus, it is CAN 2.0B specification compliant and supports two message formats:

• Base Frame Format (11-bit ID)
• Extended Frame Format (29-bit ID)

Please note:

• ESP32 CAN does not support CAN-FD and is not CAN-FD tolerant.
• ESP32 CAN does not support SJA1000's sleep mode and wake-up functionality.

As with the SJA1000, the ESP32 CAN controller provides only the data link layer and physical layer signaling sublayer. Therefore, depending on the physical layer requirements, an external transceiver module is required which converts the CAN-RX and CAN-TX signals of the ESP32 into CAN_H and CAN_L bus signals, e.g., the MCP2551 or SN65HVD23X transceiver for compatibility with ISO 11898-2.

The esp_can module realizes a low-level CAN driver interface for the ESP32 CAN controller and provides a CAN DLL device that can be used with RIOT's CAN protocol stack. It uses the ESP32 CAN controller in SJA1000 PeliCAN mode. Please refer the SJA1000 Datasheet for detailed information about the CAN controller and its programming.

The pin configuration of the CAN interface is usually defined in board specific peripheral configuration by

• CAN_TX, the GPIO used as TX tranceiver signal, and
• CAN_RX, the GPIO used as RX tranceiver signal.

If the pin configuration is not defined, the following default configuration is used which can be overridden by the application, see section Application-Specific Configurations.

Device	Signal	Pin	Symbol	Remarks
CAN	TX	GPIO5	CAN_TX	optional, can be overridden
CAN	RX	GPIO35	CAN_RX	optional, can be overridden

Example:

#define CAN_TX      GPIO10      /* CAN TX tranceiver signal */
#define CAN_RX      GPIO9       /* CAN RX tranceiver signal */

CAN_DLL_NUMOF is not defined by the esp_can module. It uses the default value of 1. If you have further CAN interfaces, make sure to define the correct value of CAN_DLL_NUMOF.

If the board has an external transceiver module connected to the ESP32 on board, the esp_can module should be enabled by default in board's Makefile.dep when module can is used.

ifneq (,$(filter can,$(USEMODULE)))
    USEMODULE += esp_can
endif

Otherwise, the application has to add the esp_can module in its makefile when needed.

Other Peripherals  [TOC]

The ESP32 port of RIOT also supports:

• hardware number generator with 32 bit
• RTC device
• CPU-ID function
• Vref measurement function
• power management functions

Special On-board Peripherals  [TOC]

SPI RAM Modules  [TOC]

The ESP32 can use external SPI RAM connected through the FSPI interface. For example, all boards that use the ESP32-WROVER modules have already integrated such SPI RAM.

However, the external SPI RAM requires 4 data lines and thus can only be used in QOUT (quad output) or QIO (quad input/output) flash mode, which makes GPIO9 and GPIO10 unavailable for other purposes. Therefore, if needed, the SPI RAM must be explicitly enabled in the makefile of the application.

USEMODULE += esp_spi_ram

Please note:

• When the SPI RAM is enabled using the esp_spi_ram, the ESP32 uses four data lines to access the external SPI RAM in QOUT (quad output) flash mode. Therefore, GPIO9 and GPIO10 are used as SPI data lines and are not available for other purposes.
• Enabling SPI RAM for modules that don't have SPI RAM may lead to boot problems for some modules. For others is simply throws an error message.

SPIFFS Device  [TOC]

The RIOT port for ESP32 implements a MTD system drive mtd0 using the on-board SPI flash memory. This MTD system drive can be used together with SPIFFS and VFS to realize a persistent file system.

To use the MTD system drive with SPIFFS, the esp_spiffs module has to be enabled in the makefile of the application:

USEMODULE += esp_spiffs

When SPIFFS is enabled, the MTD system drive is formatted with SPIFFS the first time the system is started. The start address of the MTD system drive in the SPI flash memory is defined by the board configuration:

#define SPI_FLASH_DRIVE_START  0x200000

If this start address is set to 0, as in the default board configuration, the first possible multiple of 0x100000 (1 MByte) will be used in the free SPI flash memory determined from the partition table.

Please refer file $RIOTBASE/tests/unittests/test-spiffs/tests-spiffs.c for more information on how to use SPIFFS and VFS together with a MTD device mtd0 alias MTD_0.

Network Interfaces  [TOC]

ESP32 provides different built-in possibilities to realize network devices:

• EMAC, an Ethernet MAC implementation (requires an external PHY module)
• ESP WiFi, usual AP-based wireless LAN (not yet supported)
• ESP-NOW, a WiFi based AP-less and connectionless peer to peer communication protocol
• ESP-MESH, a WiFi based mesh technology (not yet supported)

Ethernet MAC Network Interface  [TOC]

ESP32 provides an Ethernet MAC layer module (EMAC) according to the IEEE 802.3 standard which can be used together with an external physical layer chip (PHY) to realize a 100/10 Mbps Ethernet interface. Supported PHY chips are the Microchip LAN8710/LAN8720 and the Texas Instruments TLK110.

The RIOT port for ESP32 realizes with module esp_eth a netdev driver for the EMAC which uses RIOT's standard Ethernet interface.

If the board has one of the supported PHY layer chips connected to the ESP32, the esp_eth module should be enabled by default in board's Makefile.dep when module netdev_default is used.

ifneq (,$(filter netdev_default gnrc_netdev_default,$(USEMODULE)))
    USEMODULE += esp_eth
endif

Otherwise, the application has to add the esp_eth module in its makefile when needed.

Please note: The board has to have one of the supported PHY modules to be able to use the Ethernet MAC module.

ESP-NOW Network Interface  [TOC]

With ESP-NOW, the ESP32 provides a connectionless communication technology, featuring short packet transmission. It applies the IEEE802.11 Action Vendor frame technology, along with the IE function developed by Espressif, and CCMP encryption technology, realizing a secure, connectionless communication solution.

The RIOT port for ESP32 implements in module esp_now a netdev driver which uses ESP-NOW to provide a link layer interface to a meshed network of ESP32 nodes. In this network, each node can send short packets with up to 250 data bytes to all other nodes that are visible in its range.

Please note: Due to symbol conflicts in the esp_idf_wpa_supplicant_crypto module used by the esp_now with RIOT's crypto and hashes modules, ESP-NOW cannot be used for application that use these modules. Therefore, the module esp_now is not enabled automatically if the netdev_default module is used. Instead, the application has to add the esp_now module in its makefile when needed.

USEMODULE += esp_now

For ESP-NOW, ESP32 nodes are used in WiFi SoftAP + Station mode to advertise their SSID and become visible to other ESP32 nodes. The SSID of an ESP32 node is the concatenation of the prefix RIOT_ESP_ with the MAC address of its SoftAP WiFi interface. The driver periodically scans all visible ESP32 nodes.

The following parameters are defined for ESP-NOW nodes. These parameters can be overriden by application-specific board configurations.

Parameter	Default	Description
ESP_NOW_SCAN_PERIOD	10000000UL	Defines the period in us at which an node scans for other nodes in its range. The default period is 10 s.
ESP_NOW_SOFT_AP_PASSPHRASE	ThisistheRIOTporttoESP	Defines the passphrase (max. 64 chars) that is used for the SoftAP interface of an nodes. It has to be same for all nodes in one network.
ESP_NOW_CHANNEL	6	Defines the channel that is used as the broadcast medium by all nodes together.
ESP_NOW_KEY	NULL	Defines a key that is used for encrypted communication between nodes. If it is NULL, encryption is disabled. The key has to be of type uint8_t[16] and has to be exactly 16 bytes long.

Other Network Devices  [TOC]

RIOT provides a number of driver modules for different types of network devices, e.g., IEEE 802.15.4 radio modules and Ethernet modules. The RIOT port for ESP32 has been tested with the following network devices:

• mrf24j40 (driver for Microchip MRF24j40 based IEEE 802.15.4
• enc28j60 (driver for Microchip ENC28J60 based Ethernet modules)

Using MRF24J40 (module mrf24j40)  [TOC]

To use MRF24J40 based IEEE 802.15.4 modules as network device, the mrf24j40 driver module has to be added to the makefile of the application:

USEMODULE += mrf24j40

The driver parameters that have to be defined by the board configuration for the MRF24J40 driver module are:

Parameter	Description
MRF24J40_PARAM_CS	GPIO used as CS signal
MRF24J40_PARAM_INT	GPIO used as interrupt signal
MRF24J40_PARAM_RESET	GPIO used as reset signal

Since each board has different GPIO configurations, refer to the board documentation for the GPIOs recommended for the MRF24J40.

Please note: The reset signal of the MRF24J40 based network device can be connected with the ESP32 RESET/EN pin which is broken out on most boards. This keeps the GPIO free defined by MRF24J40_PARAM_RESET free for other purposes.

Using ENC28J60 (module enc28j60)  [TOC]

To use ENC28J60 Ethernet modules as network device, the enc28j60 driver module has to be added to the makefile of the application:

USEMODULE += enc28j60

The parameters that have to be defined by board configuration for the ENC28J60 driver module are:

Parameter	Description
ENC28J60_PARAM_CS	GPIO used as CS signal
ENC28J60_PARAM_INT	GPIO used as interrupt signal
ENC28J60_PARAM_RESET	GPIO used as reset signal

Since each board has different GPIO configurations, refer to the board documentation for the GPIOs recommended for the ENC28J60.

Please note: The reset signal of the ENC28J60 based network device can be connected with the ESP32 RESET/EN pin which is broken out on most boards. This keeps the GPIO free defined by ENC28J60_PARAM_RESET free for other purposes.

Application-Specific Configurations  [TOC]

The board-specific configuration files board.h and periph_conf.h as well well as the driver parameter configuration files <driver>_params.h define the default configurations for peripherals and device driver modules. These are, for example, the GPIOs used, bus interfaces used or available bus speeds. Because there are many possible configurations and many different application requirements, these default configurations are usually only a compromise between different requirements.

Therefore, it is often necessary to change some of these default configurations for individual applications. For example, while many PWM channels are needed in one application, another application does not need PWM channels, but many ADC channels.

There are two ways to give the application the ability to change some of these default configurations:

• make variable CONFIGS
• application-specific board or driver configuration file

Make Variable CONFIGS  [TOC]

Using the CONFIGS make variable at the command line, board or driver parameter definitions can be overridden.

Example:

CONFIGS='-DESP_LCD_PLUGGED_IN=1 -DLIS3DH_PARAM_INT2=GPIO4'

When a larger number of board definitions needs be overridden, this approach becomes impractical. In that case, an application-specific board configuration file located in application directory can be used, see sections below.

Application-Specific Board Configuration  [TOC]

To override default board configurations, simply create an application-specific board configuration file $APPDIR/board.h in the source directory $APPDIR of the application and add the definitions to be overridden. To force the preprocessor to include board's original board.h after that, add the include_next preprocessor directive as the last line.

For example to override the default definition of the GPIOs that are used as PWM channels, the application-specific board configuration file $APPDIR/board.h could look like the following:

#ifdef CPU_ESP32
#define PWM0_CHANNEL_GPIOS { GPIO12, GPIO13, GPIO14, GPIO15 }
#endif

#include_next "board.h"

It is important to ensure that the application-specific board configuration $APPDIR/board.h is included first. Insert the following line as the first line to the application makefile $APPDIR/Makefile.

INCLUDES += -I$(APPDIR)

Please note: To make such application-specific board configurations dependent on the ESP32 MCU or a particular ESP32 board, you should always enclose these definitions in the following constructs

#ifdef CPU_ESP32
...
#endif

#ifdef BOARD_ESP32_WROVER_KIT
...
#endif

Application-Specific Driver Configuration  [TOC]

Using the approach for overriding board configurations, the parameters of drivers that are typically defined in drivers/<device>/include/<device>_params.h can be overridden. For that purpose just create an application-specific driver parameter file $APPDIR/<device>_params.h in the source directory $APPDIR of the application and add the definitions to be overridden. To force the preprocessor to include driver's original <device>_params.h after that, add the include_next preprocessor directive as the last line.

For example, to override a GPIO used for LIS3DH sensor, the application-specific driver parameter file $APPDIR/<device>_params.h could look like the following:

#ifdef CPU_ESP32
#define LIS3DH_PARAM_INT2           (GPIO_PIN(0, 4))
#endif

#include_next "lis3dh_params.h"

It is important to ensure that the application-specific driver parameter file $APPDIR/<device>_params.h is included first. Insert the following line as the first line to the application makefile $APPDIR/Makefile.

INCLUDES += -I$(APPDIR)

Pleae note: To make such application-specific board configurations dependent on the ESP32 MCU or a particular ESP32 board, you should always enclose these definitions in the following constructs:

#ifdef CPU_ESP32
...
#endif

#ifdef BOARD_ESP32_WROVER_KIT
...
#endif

Debugging  [TOC]

JTAG Debugging  [TOC]

ESP32 provides a JTAG interface at GPIOs 12 ... 15 for On-Chip Debugging.

ESP32 Pin	ESP32 signal name JTAG Signal
CHIP_PU	TRST_N
GPIO15 (MTDO)	TDO
GPIO12 (MTDI)	TDI
GPIO13 (MTCK)	TCK
GPIO14 (MTMS)	TMS
GND	GND

This JTAG interface can be used with OpenOCD and GDB to debug your software on instruction level. When you compile your software with debugging information (module esp_gdb) you can also debug on source code level as well.

Please note: When debugging, the GPIOs used for the JTAG interface must not be used for anything else.

Detailed information on how to configure the JTAG interface of the ESP32 and to setup of OpenOCD and GDB can be found in section JTAG Debugging in the ESP-IDF Programming Guide.

QEMU Mode and GDB  [TOC]

When you execute command make flash with QEMU mode enabled (QEMU=1), instead of loading the image to the target hardware, a binary image called esp32flash.bin is created in the target directory. Furthermore, two ROM binary files rom.bin and rom1.bin are copied to the target directory. This files file can then be used together with QEMU to debug the code in GDB.

The binary image can be compiled with debugging information using module esp_gdb or optimized without debugging information (default). The latter one is the default. The version with debugging information can be debugged in source code while the optimized version can only be debugged in assembler mode.

To use QEMU, you have to install QEMU for Xtensa with ESP32 machine implementation as following.

cd $HOME/src
git clone git://github.com/Ebiroll/qemu_esp32
cp qemu_esp32/bin/xtensa-esp32-elf-gdb $HOME/esp/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb.qemu
rm -rf qemu_esp32

git clone git://github.com/Ebiroll/qemu-xtensa-esp32
cd qemu-xtensa-esp32
./configure --disable-werror --prefix=$HOME/esp/qemu-esp32 --target-list=xtensa-softmmu,xtensaeb-softmmu
make install
cd ..; rm -rf qemu-xtensa-esp32 # optional

Once the compilation has been finished, QEMU for Xtensa with ESP32 machine implementation should be available in $HOME/esp/qemu-esp32 and you can change to your application target directory to start it in one terminal window , for example

cd $HOME/src/RIOT-Xtensa-ESP/tests/shell/bin/esp32-generic
$HOME/esp/qemu-esp32/bin/qemu-system-xtensa -d guest_errors,unimp -cpu esp32 -M esp32 -m 4M -S -s > io.txt

where $HOME/src/RIOT-Xtensa-ESP is the root directory of RIOT and tests/shell is the application.

Please note: QEMU starts always the files esp32flash.bin, rom.bin and rom1.bin in local directory. Therefore, Please make sure that you are in the correct destination directory before starting QEMU.

In the second terminal window, you can then start GDB and connect to the emulation for the example.

xtensa-esp32-elf-gdb.qemu $HOME/src/RIOT-Xtensa-ESP/tests/shell/bin/esp32-generic/tests_shell.elf

To start debugging, you have to connect to QEMU with command:

(gdb) target remote :1234

Please note: QEMU for Xtensa ESP32 does not support interrupts. That is, once your application uses interrupts, e.g., timers, the application cannot be debugged using QEMU together with GDB.