<commit_before>/*
 * Copyright (C) 2018 <NAME>
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */

/**
@defgroup   cpu_esp32 ESP32
@ingroup    cpu
@brief      Implementation for Espressif ESP32 MCUs
@author     <NAME> <<EMAIL>>

\section esp32_riot  RIOT-OS on ESP32 boards

## <a name="esp32_toc"> Table of Contents </a>

1. [Overview](#esp32_overview)
2. [Short Configuration Reference](#esp32_short_configuration_reference)
3. [MCU ESP32](#esp32_mcu_esp32)
    1. [Features of ESP32](#esp32_features)
    2. [Features Supported by RIOT-OS](#esp32_supported_features)
    3. [Limitations of the RIOT-port](#esp32_limitations)
4. [Toolchain](#esp32_toolchain)
    1. [RIOT Docker Toolchain (riotdocker)](#esp32_riot_docker_toolchain)
    2. [Manual Toolchain Installation](#esp32_manual_toolchain_installation)
5. [Flashing the Device](#esp32_flashing_the_device)
    1. [Toolchain Usage](#esp32_toolchain_usage)
    2. [Compile Options](#esp32_compile_options)
    3. [Flash Modes](#esp32_flash_modes)
    4. [ESP-IDF Heap Implementation](#esp32_esp_idf_heap_implementation)
6. [Common Peripherals](#esp32_peripherals)
    1. [GPIO pins](#esp32_gpio_pins)
    2. [ADC Channels](#esp32_adc_channels)
    3. [DAC Channels](#esp32_dac_channels)
    4. [I2C Interfaces](#esp32_i2c_interfaces)
    5. [PWM Channels](#esp32_pwm_channels)
    6. [SPI Interfaces](#esp32_spi_interfaces)
    7. [Timers](#esp32_timers)
    8. [RTC Timer](#esp32_rtc_timer)
    9. [UART Interfaces](#esp32_uart_interfaces)
    10. [CAN Interfaces](#esp32_can_interfaces)
    11. [Other Peripherals](#esp32_other_peripherals)
7. [Special On-board Peripherals](#esp32_special_on_board_peripherals)
    1. [SPI RAM Modules](#esp32_spi_ram)
    2. [SPIFFS Device](#esp32_spiffs_device)
8. [Network Interfaces](#esp32_network_interfaces)
    1. [Ethernet MAC Network Interface](#esp32_ethernet_network_interface)
    2. [WiFi Network Interface](#esp32_wifi_network_interface)
    3. [ESP-NOW Network Interface](#esp32_esp_now_network_interface)
    4. [Other Network Devices](#esp32_other_network_devices)
10. [Application-Specific Configurations](#esp32_application_specific_configurations)
    1. [Make Variable ```CONFIGS```](#esp32_config_make_variable)
    2. [Application-Specific Board Configuration](#esp32_application_specific_board_configuration)
    3. [Application-Specific Driver Configuration](#esp32_application_specific_driver_configuration)
11. [Debugging](#esp32_debugging)
    1. [JTAG Debugging](#esp32_jtag_debugging)
    2. [QEMU Mode and GDB](#esp32_qemu_mode_and_gdb)


# <a name="esp32_overview"> Overview </a> &nbsp;[[TOC](#esp32_toc)]

<b>RIOT-Xtensa-ESP</b> is a bare metal implementation of <b>RIOT-OS</b> for <b>ESP32</b> 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 <b>ESP-IDF</b> (Espresso IoT Development Framework) SDK, it must be installed for compilation. The reason is that the port uses most of the <b>ESP32 SOC definitions</b> provided by the ESP-IDF header files. In addition, it needs the hardware abstraction library (libhal), and the <b>ESP32 WiFi stack binary</b> libraries which are part of the ESP-IDF SDK.

# <a name="esp32_short_configuration_reference"> Short Configuration Reference </a> &nbsp;[[TOC](#esp32_toc)]

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

<center>

Parameter | Short Description                      | Type*
----------|----------------------------------------|------
[ADC_GPIOS](#esp32_adc_channels)        | GPIOs that can be used as ADC channels | m
[CAN_TX](#esp32_can_interfaces) | GPIO used as CAN transceiver TX signal | o
[CAN_RX](#esp32_can_interfaces) | GPIO used as CAN transceiver RX signal | o
[DAC_GPIOS](#esp32_adc_channels)        | GPIOs that can be used as DAC channels | m
[I2C0_SPEED](#esp32_i2c_interfaces)| Bus speed of I2C_DEV(0)         | o
[I2C0_SCL](#esp32_i2c_interfaces)  | GPIO used as SCL for I2C_DEV(0) | o
[I2C0_SDA](#esp32_i2c_interfaces)  | GPIO used as SCL for I2C_DEV(0 | o
[I2C1_SPEED](#esp32_i2c_interfaces)| Bus speed of I2C_DEV(1)        | o
[I2C1_SCL](#esp32_i2c_interfaces)  | GPIO used as SCL for I2C_DEV(1) | o
[I2C1_SDA](#esp32_i2c_interfaces)  | GPIO used as SCL for I2C_DEV(1) | o
[PWM0_GPIOS](#esp32_pwm_channels)       | GPIOs that can be used at channels of PWM_DEV(0) | o
[PWM1_GPIOS](#esp32_pwm_channels)       | GPIOs that can be used at channels of PWM_DEV(1) | o
[SPI0_CTRL](#esp32_spi_interfaces)  | SPI Controller used for SPI_DEV(0), can be ```VSPI``` ```HSPI``` | o
[SPI0_SCK](#esp32_spi_interfaces)  | GPIO used as SCK for SPI_DEV(0)        | o
[SPI0_MOSI](#esp32_spi_interfaces) | GPIO used as MOSI for SPI_DEV(0)       | o
[SPI0_MISO](#esp32_spi_interfaces) | GPIO used as MISO for SPI_DEV(0)       | o
[SPI0_CS0](#esp32_spi_interfaces)  | GPIO used as default CS for SPI_DEV(0) | o
[SPI1_CTRL](#esp32_spi_interfaces)  | SPI Controller used for SPI_DEV(1), can be ```VSPI``` ```HSPI``` | o
[SPI1_SCK](#esp32_spi_interfaces)  | GPIO used as SCK for SPI_DEV(1)        | o
[SPI1_MOSI](#esp32_spi_interfaces) | GPIO used as MOSI for SPI_DEV(1)       | o
[SPI1_MISO](#esp32_spi_interfaces) | GPIO used as MISO for SPI_DEV(1)       | o
[SPI1_CS0](#esp32_spi_interfaces)  | GPIO used as default CS for SPI_DEV(1) | o
[UART1_TXD](#esp32_uart_interfaces) | GPIO used as TxD for UART_DEV(1) | o
[UART1_RXD](#esp32_uart_interfaces) | GPIO used as RxD for UART_DEV(1) | o
[UART2_TXD](#esp32_uart_interfaces) | GPIO used as TxD for UART_DEV(2) | o
[UART2_RXD](#esp32_uart_interfaces) | GPIO used as RxD for UART_DEV(2) | o

</center>

<b>*Type:</b> 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```.

<center>

Module    | Default  | Short description
----------|----------|-------------------
[esp_eth](#esp32_ethernet_network_interface) | not used | enable the Ethernet MAC (EMAC) network device
[esp_gdb](#esp32_debugging) | not used | enable the compilation with debug information for debugging
[esp_hw_counter](#esp32_timers) | not used | use hardware counters for RIOT timers
[esp_i2c_hw](#esp32_i2c_interfaces) | not used  | use the i2C hardware implementation
[esp_idf_heap](#esp32_esp_idf_heap_implementation) | not used | enable ESP-IDF heap implementation
[esp_log_colored](#esp32_esp_log_module) | not used | enable colored log output
[esp_log_startup](#esp32_esp_log_module) | not used | enable additional startup information
[esp_log_tagged](#esp32_esp_log_module) | not used | add additional information to the log output
[esp_now](#esp32_esp_now_network_interface) | not used  | enable the ESP-NOW network device
[esp_rtc_timer](#esp32_rtc_timer) | not used | enable RTC hardware timer with internal 150 kHz RC oscillator
[esp_rtc_timer_32k](#esp32_rtc_timer) not used | enable RTC hardware timer with external 32.768 kHz crystal.
[esp_spi_ram](#esp32_spi_ram) | not used |  enable SPI RAM
[esp_spiffs](#esp32_spiffs_device) | not used  |  enable SPIFFS for on-board flash memory
[esp_wifi](#esp32_wifi_network_interface) | not used  | enable the Wifi network device

</center>

# <a name=esp32_mcu_esp32> MCU ESP32 </a> &nbsp;[[TOC](#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.

\anchor esp32_mcu
## <a name=esp32_features> Features of ESP32 </a> &nbsp;[[TOC](#esp32_toc)]

The key features of ESP32 are:

<center>

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 <br> 16 kByte  RTC SRAM | yes
ROM         | 448 kByte | yes
Flash       | 512 kByte ... 16 MByte |  yes
Frequency   | 240 MHz, 160 MHz, 80 MHz | yes
Power Consumption | 68 mA @ 240 MHz <br> 44 mA @ 160 MHz <br> 31 mA @ 80 MHz <br> 5 uA in deep sleep mode | yes <br> yes <br> yes <br> 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 (2)
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 | yes
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](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) <br> [Technical Reference](https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf) | |

</center><br>

@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](https://www.espressif.com/en/products/hardware/modules) 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](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html#wroom-solo-and-wrover-modules).

Most common modules used by ESP32 boards are the [ESP32-WROOM-32](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html#esp32-wroom-32) and [ESP32-WROVER](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html#esp32-wrover).

## <a name="esp32_supported_features"> Features Supported by RIOT-OS </a> &nbsp;[[TOC](#esp32_toc)]

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

- I2C interfaces
- SPI interfaces
- UART interfaces
- CAN interface
- 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

## <a name="esp32_limitations"> Limitations of the RIOT port </a> &nbsp;[[TOC](#esp32_toc)]

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

- Only <b>one core</b> (the PRO CPU) is used because RIOT does not support running multiple threads  simultaneously.
- <b>Bluetooth</b> cannot be used at the moment.
- <b>Flash encryption</b> is not yet supported.


# <a name="esp32_toolchain"> Toolchain <a>

Following software components are required for compilation:

- <b>Xtensa GCC</b> compiler suite for ESP32
- <b>ESP-IDF</b> SDK which includes all ESP32 SOC definitions, basic libraries and the hardware abstraction library <b>`libhal.a`</b>

There are two options to install the Toolchain:

- <b>riotdocker</b> image, see section [RIOT Docker Toolchain (riotdocker)](#esp32_riot_docker_toolchain)
- <b>manual installation</b>, see section [Manual Toolchain Installation](#esp32_manual_toolchain_installation)

## <a name="esp32_riot_docker_toolchain"> RIOT Docker Toolchain (riotdocker) </a> &nbsp;[[TOC](#esp32_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 ESP flash programmer `esptool.py` is installed.
Both steps can also be performed with a single command on the host system
using the `BUILD_IN_DOCKER` variable:
```
BUILD_IN_DOCKER=1 make BOARD=... flash
```

### <a name="esp32_preparing_the_environment"> Preparing the Environment </a> &nbsp;[[TOC](#esp32_toc)]

Using RIOT Docker requires at least the following software:

- <b>```Docker```</b> container virtualization software
- RIOT Docker (<b>```riotdocker```</b>) image
- ESP flash programmer tool <b>`esptool.py`</b>

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
```
For information on how to install `esptool.py`, see section
[Installation of `esptool.py`](#esp32_installation_of_esptool).

### <a name="esp32_generating_docker_image"> Generating a riotdocker Image </a> &nbsp;[[TOC](#esp32_toc)]

A ```riotdocker``` fork that only installs the ```RIOT-Xtensa-ESP32-toolchain``` is available at [GitHub](https://github.com/gschorcht/riotdocker-Xtensa-ESP.git). 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](https://github.com/RIOT-OS/riotdocker). 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
```
@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](https://github.com/RIOT-OS/RIOT/wiki/Use-Docker-to-build-RIOT) on how to use the Docker image to compile RIOT OS.

### <a name="esp32_using_existing_docker_image"> Using an Existing riotdocker Image </a> &nbsp;[[TOC](#esp32_toc)]

Alternatively, an existing Docker image from Docker Hub can be used. You can either pull and start the [schorcht/riotbuild_esp32](https://hub.docker.com/r/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](https://hub.docker.com/r/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
```
### <a name="esp32_flashing_using_docker"> Make Process with Docker Image </a> &nbsp;[[TOC](#esp32_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.

@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
```



## <a name="esp32_manual_toolchain_installation"> Manual Toolchain Installation </a> &nbsp;[[TOC](#esp32_toc)]

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

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

### <a name="esp32_installation_of_xtensa_gcc"> Installation of Xtensa GCC compiler suite </a> &nbsp;[[TOC](#esp32_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
```

### <a name="esp32_installation_of_esp_idf"> Installation of ESP-IDF (Espressif IoT Development Framework) </a> &nbsp;[[TOC](#esp32_toc)]

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

```
cd $HOME/esp
git clone https://github.com/espressif/esp-idf.git
cd esp-idf
git checkout f198339ec09e90666150672884535802304d23ec
git submodule init
git submodule update
```

@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
```

### <a name="esp32_installation_of_esptool"> Installation of `esptool.py` (ESP flash programmer tool) </a> &nbsp;[[TOC](#esp32_toc)]

The RIOT port does not work with the `esptool.py` ESP flasher program
available on [GitHub](https://github.com/espressif/esptool) or
as a package for your OS. Instead, a modified version is required.

To avoid the installation of the complete ESP-IDF SDK, for example,
because RIOT Docker `riotdocker` is used for compilation, `esptool.py`
has been extracted from the SDK and placed in RIOT's
directory `dist/tools/esptool`.
For convenience, the build system uses always the version from this directory.

Therefore, it is **not necessary to install** `esptool.py` explicitly. However
`esptool.py` depends on `pySerial` which can be installed either
using `pip`

```
sudo pip install pyserial
```
or the package manager of your OS, for example on Debian/Ubuntu systems:
```
apt install python-pyserial
```
For more information on `esptool.py`, please refer to the
[git repository](https://github.com/espressif/esptool).


# <a name="esp32_flashing_the_device"> Flashing the Device </a> &nbsp;[[TOC](#esp32_toc)]

## <a name="esp32_toolchain_usage"> Toolchain Usage </a> &nbsp;[[TOC](#esp32_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.

## <a name="esp32_compile_options"> Compile Options </a> &nbsp;[[TOC](#esp32_toc)]

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

<center>

Option | Values | Default | Description
-------|--------|---------|------------
CONFIGS | string | empty | Override default board and driver configurations, see section [Application-Specific Configurations](#esp32_application_specific_configurations).
FLASH_MODE | dout, dio, qout, qio | dout | Set the flash mode, see section [Flash Modes](#esp32_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](#esp32_qemu_mode_and_gdb).

</center><br>

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

<center>

Module | Description
-------|------------
esp_eth | Enable the Ethernet MAC (EMAC) interface as `netdev` network device, see section [Ethernet Network Interface](#esp32_ethernet_network_interface).
esp_gdb | Enable the compilation with debug information for debugging with [QEMU and GDB](#esp32_qemu_mode_and_gdb) (```QEMU=1```) or via [JTAG interface with OpenOCD](#esp32_jtag_debugging).
esp_i2c_hw | Use the hardware I2C implementation, see section [I2C Interfaces](#esp32_i2c_interfaces).
esp_idf_heap | Use the ESP-IDF heap implementation, see section [ESP-IDF Heap Implementation](#esp32_esp_idf_heap_implementation).
esp_log_colored | Enable colored log output, see section [Log output](#esp32_esp_log_module).
esp_log_startup | Enable additional startup information, see section [Log output](#esp32_esp_log_module).
esp_log_tagged | Add additional information to the log output, see section [Log output](#esp32_esp_log_module).
esp_now | Enable the built-in WiFi module with the ESP-NOW protocol as `netdev` network device, see section [ESP-NOW Network Interface](#esp32_esp_now_network_interface).
esp_rtc_timer | Enable RTC hardware timer with internal 150 kHz RC oscillator.
esp_rtc_timer_32k | Enable RTC hardware timer with external 32.768 kHz crystal.
esp_spiffs  | Enable the optional SPIFFS drive in on-board flash memory, see section [SPIFFS Device](#esp32_spiffs_device).
esp_spi_ram | Enable the optional SPI RAM, see section [SPI RAM Modules](#esp32_spi_ram).
esp_wifi | Enable the built-in WiFi module as `netdev` network device, see section [WiFi Network Interface](#esp32_wifi_network_interface).

</center>

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

\anchor esp32_flash_modes
## <a name="esp32_flash_modes"> Flash Modes </a> &nbsp;[[TOC](#esp32_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](https://github.com/espressif/esptool/wiki/SPI-Flash-Modes).

## <a name="esp32_esp_log_module"> Log output </a> &nbsp;[[TOC](#esp32_toc)]

The RIOT port for ESP32 implements a log module with a bunch of macros
to generate log output according to the interface as defined in
[system logging header](http://doc.riot-os.org/log_8h.html). These macros
support colored and tagged log output.

The colored log output is enabled by module `esp_log_colored`. If colored log
output is enabled, log messages are displayed in color according to their type:
Error messages are displayed in red, warnings in yellow, information
messages in green and all other message types in standard color.

When the `esp_log_tagged` module is used, all log messages are tagged with
additional information: the type of message, the system time in ms, and the
module or function in which the log message is generated. For example:

```
I (663) [main_trampoline] main(): This is RIOT! (Version: 2019.10-devel-437-gf506a)
```

Either the `LOG_*` macros as defined in
[system logging header](http://doc.riot-os.org/log_8h.html) or the tagged
version `LOG_TAG_*` of these macros can be used to produce tagged log output.
If the `LOG_*` macros are used, the function which generates the log message
is used in the tag while a `tag` parameter is used for the `LOG_TAG_*` macros.
For example,
```
LOG_ERROR("error message");
```
generates a log message in which the name of the calling function is used as
tag. With
```
LOG_TAG_ERROR("mod", "error message");
```
a log message with string `mod` in the tag is generated.

The `esp_log_startup` module can be used to enable additional information
about the boot process, the board configuration, the system configuration,
the CPU used by the system, and the available heap. These information may
help to detect problems during the startup. If the application does not
start as expected, this module should be used.

## <a name="esp32_esp_idf_heap_implementation"> ESP-IDF Heap Implementation </a> &nbsp;[[TOC](#esp32_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
```

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


\anchor esp32_comm_periph
# <a name="esp32_peripherals"> Common Peripherals </a> &nbsp;[[TOC](#esp32_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.

\anchor esp32_gpio_pins
## <a name="esp32_gpio_pins"> GPIO pins </a> &nbsp;[[TOC](#esp32_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.

<center>

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 ```qout```and ```qio```mode, see section [Flash Modes](#esp32_flash_modes)
GPIO10 | In/Out | -   | yes    | Flash SD_DATA3 | only in ```qout```and ```qio```mode, see section [Flash Modes](#esp32_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   | -

</center>

<b>ADC:</b> these pins can be used as ADC inputs<br>
<b>PU/PD:</b> these pins have software configurable pull-up/pull-down functionality.<br><commit_msg>cpu/esp32: several small doc fixes<commit_after>/*
 * Copyright (C) 2018 <NAME>
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */

/**
@defgroup   cpu_esp32 ESP32
@ingroup    cpu
@brief      Implementation for Espressif ESP32 MCUs
@author     <NAME> <<EMAIL>>

\section esp32_riot  RIOT-OS on ESP32 boards

## <a name="esp32_toc"> Table of Contents </a>

1. [Overview](#esp32_overview)
2. [Short Configuration Reference](#esp32_short_configuration_reference)
3. [MCU ESP32](#esp32_mcu_esp32)
    1. [Features of ESP32](#esp32_features)
    2. [Features Supported by RIOT-OS](#esp32_supported_features)
    3. [Limitations of the RIOT-port](#esp32_limitations)
4. [Toolchain](#esp32_toolchain)
    1. [RIOT Docker Toolchain (riotdocker)](#esp32_riot_docker_toolchain)
    2. [Manual Toolchain Installation](#esp32_manual_toolchain_installation)
5. [Flashing the Device](#esp32_flashing_the_device)
    1. [Toolchain Usage](#esp32_toolchain_usage)
    2. [Compile Options](#esp32_compile_options)
    3. [Flash Modes](#esp32_flash_modes)
    4. [ESP-IDF Heap Implementation](#esp32_esp_idf_heap_implementation)
6. [Common Peripherals](#esp32_peripherals)
    1. [GPIO pins](#esp32_gpio_pins)
    2. [ADC Channels](#esp32_adc_channels)
    3. [DAC Channels](#esp32_dac_channels)
    4. [I2C Interfaces](#esp32_i2c_interfaces)
    5. [PWM Channels](#esp32_pwm_channels)
    6. [SPI Interfaces](#esp32_spi_interfaces)
    7. [Timers](#esp32_timers)
    8. [RTC Timer](#esp32_rtc_timer)
    9. [UART Interfaces](#esp32_uart_interfaces)
    10. [CAN Interfaces](#esp32_can_interfaces)
    11. [Other Peripherals](#esp32_other_peripherals)
7. [Special On-board Peripherals](#esp32_special_on_board_peripherals)
    1. [SPI RAM Modules](#esp32_spi_ram)
    2. [SPIFFS Device](#esp32_spiffs_device)
8. [Network Interfaces](#esp32_network_interfaces)
    1. [Ethernet MAC Network Interface](#esp32_ethernet_network_interface)
    2. [WiFi Network Interface](#esp32_wifi_network_interface)
    3. [ESP-NOW Network Interface](#esp32_esp_now_network_interface)
    4. [Other Network Devices](#esp32_other_network_devices)
10. [Application-Specific Configurations](#esp32_application_specific_configurations)
    1. [Make Variable ```CONFIGS```](#esp32_config_make_variable)
    2. [Application-Specific Board Configuration](#esp32_application_specific_board_configuration)
    3. [Application-Specific Driver Configuration](#esp32_application_specific_driver_configuration)
11. [Debugging](#esp32_debugging)
    1. [JTAG Debugging](#esp32_jtag_debugging)
    2. [QEMU Mode and GDB](#esp32_qemu_mode_and_gdb)


# <a name="esp32_overview"> Overview </a> &nbsp;[[TOC](#esp32_toc)]

<b>RIOT-Xtensa-ESP</b> is a bare metal implementation of <b>RIOT-OS</b> for <b>ESP32</b> 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 <b>ESP-IDF</b> (Espresso IoT Development Framework) SDK, it must be installed for compilation. The reason is that the port uses most of the <b>ESP32 SOC definitions</b> provided by the ESP-IDF header files. In addition, it needs the hardware abstraction library (libhal), and the <b>ESP32 WiFi stack binary</b> libraries which are part of the ESP-IDF SDK.

# <a name="esp32_short_configuration_reference"> Short Configuration Reference </a> &nbsp;[[TOC](#esp32_toc)]

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

<center>

Parameter | Short Description                      | Type*
----------|----------------------------------------|------
[ADC_GPIOS](#esp32_adc_channels)        | GPIOs that can be used as ADC channels | m
[CAN_TX](#esp32_can_interfaces) | GPIO used as CAN transceiver TX signal | o
[CAN_RX](#esp32_can_interfaces) | GPIO used as CAN transceiver RX signal | o
[DAC_GPIOS](#esp32_adc_channels)        | GPIOs that can be used as DAC channels | m
[I2C0_SPEED](#esp32_i2c_interfaces)| Bus speed of I2C_DEV(0)         | o
[I2C0_SCL](#esp32_i2c_interfaces)  | GPIO used as SCL for I2C_DEV(0) | o
[I2C0_SDA](#esp32_i2c_interfaces)  | GPIO used as SCL for I2C_DEV(0 | o
[I2C1_SPEED](#esp32_i2c_interfaces)| Bus speed of I2C_DEV(1)        | o
[I2C1_SCL](#esp32_i2c_interfaces)  | GPIO used as SCL for I2C_DEV(1) | o
[I2C1_SDA](#esp32_i2c_interfaces)  | GPIO used as SCL for I2C_DEV(1) | o
[PWM0_GPIOS](#esp32_pwm_channels)       | GPIOs that can be used at channels of PWM_DEV(0) | o
[PWM1_GPIOS](#esp32_pwm_channels)       | GPIOs that can be used at channels of PWM_DEV(1) | o
[SPI0_CTRL](#esp32_spi_interfaces)  | SPI Controller used for SPI_DEV(0), can be ```VSPI``` ```HSPI``` | o
[SPI0_SCK](#esp32_spi_interfaces)  | GPIO used as SCK for SPI_DEV(0)        | o
[SPI0_MOSI](#esp32_spi_interfaces) | GPIO used as MOSI for SPI_DEV(0)       | o
[SPI0_MISO](#esp32_spi_interfaces) | GPIO used as MISO for SPI_DEV(0)       | o
[SPI0_CS0](#esp32_spi_interfaces)  | GPIO used as default CS for SPI_DEV(0) | o
[SPI1_CTRL](#esp32_spi_interfaces)  | SPI Controller used for SPI_DEV(1), can be ```VSPI``` ```HSPI``` | o
[SPI1_SCK](#esp32_spi_interfaces)  | GPIO used as SCK for SPI_DEV(1)        | o
[SPI1_MOSI](#esp32_spi_interfaces) | GPIO used as MOSI for SPI_DEV(1)       | o
[SPI1_MISO](#esp32_spi_interfaces) | GPIO used as MISO for SPI_DEV(1)       | o
[SPI1_CS0](#esp32_spi_interfaces)  | GPIO used as default CS for SPI_DEV(1) | o
[UART1_TXD](#esp32_uart_interfaces) | GPIO used as TxD for UART_DEV(1) | o
[UART1_RXD](#esp32_uart_interfaces) | GPIO used as RxD for UART_DEV(1) | o
[UART2_TXD](#esp32_uart_interfaces) | GPIO used as TxD for UART_DEV(2) | o
[UART2_RXD](#esp32_uart_interfaces) | GPIO used as RxD for UART_DEV(2) | o

</center>

<b>*Type:</b> 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```.

<center>

Module    | Default  | Short description
----------|----------|-------------------
[esp_eth](#esp32_ethernet_network_interface) | not used | enable the Ethernet MAC (EMAC) network device
[esp_gdb](#esp32_debugging) | not used | enable the compilation with debug information for debugging
[esp_hw_counter](#esp32_timers) | not used | use hardware counters for RIOT timers
[esp_i2c_hw](#esp32_i2c_interfaces) | not used  | use the i2C hardware implementation
[esp_idf_heap](#esp32_esp_idf_heap_implementation) | not used | enable ESP-IDF heap implementation
[esp_log_colored](#esp32_esp_log_module) | not used | enable colored log output
[esp_log_startup](#esp32_esp_log_module) | not used | enable additional startup information
[esp_log_tagged](#esp32_esp_log_module) | not used | add additional information to the log output
[esp_now](#esp32_esp_now_network_interface) | not used  | enable the ESP-NOW network device
[esp_rtc_timer](#esp32_rtc_timer) | not used | enable RTC hardware timer with internal 150 kHz RC oscillator
[esp_rtc_timer_32k](#esp32_rtc_timer) | not used | enable RTC hardware timer with external 32.768 kHz crystal.
[esp_spi_ram](#esp32_spi_ram) | not used |  enable SPI RAM
[esp_spiffs](#esp32_spiffs_device) | not used  |  enable SPIFFS for on-board flash memory
[esp_wifi](#esp32_wifi_network_interface) | not used  | enable the Wifi network device

</center>

# <a name=esp32_mcu_esp32> MCU ESP32 </a> &nbsp;[[TOC](#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.

\anchor esp32_mcu
## <a name=esp32_features> Features of ESP32 </a> &nbsp;[[TOC](#esp32_toc)]

The key features of ESP32 are:

<center>

MCU         | ESP32     | Supported by RIOT
------------|-----------|------------------
Vendor      | Espressif | |
Cores       | 1 or 2 x Tensilica Xtensa LX6 | 1 core
FPU         | ULP - Ultra low power co-processor | no
RAM         | 520 kByte SRAM <br> 16 kByte  RTC SRAM | yes
ROM         | 448 kByte | yes
Flash       | 512 kByte ... 16 MByte |  yes
Frequency   | 240 MHz, 160 MHz, 80 MHz | yes
Power Consumption | 68 mA @ 240 MHz <br> 44 mA @ 160 MHz <br> 31 mA @ 80 MHz <br> 5 uA in deep sleep mode | yes <br> yes <br> yes <br> 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 are only inputs, 18 are RTC GPIOs) | yes
I2Cs        | 2 | yes
SPIs        | 4 | yes (2)
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 | yes
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](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) <br> [Technical Reference](https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf) | |

</center><br>

@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](https://www.espressif.com/en/products/hardware/modules) 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](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html#wroom-solo-and-wrover-modules).

Most common modules used by ESP32 boards are the [ESP32-WROOM-32](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html#esp32-wroom-32) and [ESP32-WROVER](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html#esp32-wrover).

## <a name="esp32_supported_features"> Features Supported by RIOT-OS </a> &nbsp;[[TOC](#esp32_toc)]

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

- I2C interfaces
- SPI interfaces
- UART interfaces
- CAN interface
- 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

## <a name="esp32_limitations"> Limitations of the RIOT port </a> &nbsp;[[TOC](#esp32_toc)]

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

- Only <b>one core</b> (the PRO CPU) is used because RIOT does not support running multiple threads  simultaneously.
- <b>Bluetooth</b> cannot be used at the moment.
- <b>Flash encryption</b> is not yet supported.


# <a name="esp32_toolchain"> Toolchain <a>

Following software components are required for compilation:

- <b>Xtensa GCC</b> compiler suite for ESP32
- <b>ESP-IDF</b> SDK which includes all ESP32 SOC definitions, basic libraries and the hardware abstraction library <b>`libhal.a`</b>

There are two options to install the Toolchain:

- <b>riotdocker</b> image, see section [RIOT Docker Toolchain (riotdocker)](#esp32_riot_docker_toolchain)
- <b>manual installation</b>, see section [Manual Toolchain Installation](#esp32_manual_toolchain_installation)

## <a name="esp32_riot_docker_toolchain"> RIOT Docker Toolchain (riotdocker) </a> &nbsp;[[TOC](#esp32_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 ESP flash programmer `esptool.py` is installed.
Both steps can also be performed with a single command on the host system
using the `BUILD_IN_DOCKER` variable:
```
BUILD_IN_DOCKER=1 make BOARD=... flash
```

### <a name="esp32_preparing_the_environment"> Preparing the Environment </a> &nbsp;[[TOC](#esp32_toc)]

Using RIOT Docker requires at least the following software:

- <b>```Docker```</b> container virtualization software
- RIOT Docker (<b>```riotdocker```</b>) image
- ESP flash programmer tool <b>`esptool.py`</b>

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
```
For information on how to install `esptool.py`, see section
[Installation of `esptool.py`](#esp32_installation_of_esptool).

### <a name="esp32_generating_docker_image"> Generating a riotdocker Image </a> &nbsp;[[TOC](#esp32_toc)]

A ```riotdocker``` fork that only installs the ```RIOT-Xtensa-ESP32-toolchain``` is available at [GitHub](https://github.com/gschorcht/riotdocker-Xtensa-ESP.git). 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](https://github.com/RIOT-OS/riotdocker). 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
```
@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](https://github.com/RIOT-OS/RIOT/wiki/Use-Docker-to-build-RIOT) on how to use the Docker image to compile RIOT OS.

### <a name="esp32_using_existing_docker_image"> Using an Existing riotdocker Image </a> &nbsp;[[TOC](#esp32_toc)]

Alternatively, an existing Docker image from Docker Hub can be used. You can either pull and start the [schorcht/riotbuild_esp32](https://hub.docker.com/r/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](https://hub.docker.com/r/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
```
### <a name="esp32_flashing_using_docker"> Make Process with Docker Image </a> &nbsp;[[TOC](#esp32_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.

@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
```



## <a name="esp32_manual_toolchain_installation"> Manual Toolchain Installation </a> &nbsp;[[TOC](#esp32_toc)]

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

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

### <a name="esp32_installation_of_xtensa_gcc"> Installation of Xtensa GCC compiler suite </a> &nbsp;[[TOC](#esp32_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
```

### <a name="esp32_installation_of_esp_idf"> Installation of ESP-IDF (Espressif IoT Development Framework) </a> &nbsp;[[TOC](#esp32_toc)]

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

```
cd $HOME/esp
git clone https://github.com/espressif/esp-idf.git
cd esp-idf
git checkout f198339ec09e90666150672884535802304d23ec
git submodule init
git submodule update
```

@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
```

### <a name="esp32_installation_of_esptool"> Installation of `esptool.py` (ESP flash programmer tool) </a> &nbsp;[[TOC](#esp32_toc)]

The RIOT port does not work with the `esptool.py` ESP flasher program
available on [GitHub](https://github.com/espressif/esptool) or
as a package for your OS. Instead, a modified version is required.

To avoid the installation of the complete ESP-IDF SDK, for example,
because RIOT Docker `riotdocker` is used for compilation, `esptool.py`
has been extracted from the SDK and placed in RIOT's
directory `dist/tools/esptool`.
For convenience, the build system uses always the version from this directory.

Therefore, it is **not necessary to install** `esptool.py` explicitly. However
`esptool.py` depends on `pySerial` which can be installed either
using `pip`

```
sudo pip install pyserial
```
or the package manager of your OS, for example on Debian/Ubuntu systems:
```
apt install python-pyserial
```
For more information on `esptool.py`, please refer to the
[git repository](https://github.com/espressif/esptool).


# <a name="esp32_flashing_the_device"> Flashing the Device </a> &nbsp;[[TOC](#esp32_toc)]

## <a name="esp32_toolchain_usage"> Toolchain Usage </a> &nbsp;[[TOC](#esp32_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.

## <a name="esp32_compile_options"> Compile Options </a> &nbsp;[[TOC](#esp32_toc)]

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

<center>

Option | Values | Default | Description
-------|--------|---------|------------
CONFIGS | string | empty | Override default board and driver configurations, see section [Application-Specific Configurations](#esp32_application_specific_configurations).
FLASH_MODE | dout, dio, qout, qio | dout | Set the flash mode, see section [Flash Modes](#esp32_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](#esp32_qemu_mode_and_gdb).

</center><br>

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

<center>

Module | Description
-------|------------
esp_eth | Enable the Ethernet MAC (EMAC) interface as `netdev` network device, see section [Ethernet Network Interface](#esp32_ethernet_network_interface).
esp_gdb | Enable the compilation with debug information for debugging with [QEMU and GDB](#esp32_qemu_mode_and_gdb) (```QEMU=1```) or via [JTAG interface with OpenOCD](#esp32_jtag_debugging).
esp_i2c_hw | Use the hardware I2C implementation, see section [I2C Interfaces](#esp32_i2c_interfaces).
esp_idf_heap | Use the ESP-IDF heap implementation, see section [ESP-IDF Heap Implementation](#esp32_esp_idf_heap_implementation).
esp_log_colored | Enable colored log output, see section [Log output](#esp32_esp_log_module).
esp_log_startup | Enable additional startup information, see section [Log output](#esp32_esp_log_module).
esp_log_tagged | Add additional information to the log output, see section [Log output](#esp32_esp_log_module).
esp_now | Enable the built-in WiFi module with the ESP-NOW protocol as `netdev` network device, see section [ESP-NOW Network Interface](#esp32_esp_now_network_interface).
esp_rtc_timer | Enable RTC hardware timer with internal 150 kHz RC oscillator.
esp_rtc_timer_32k | Enable RTC hardware timer with external 32.768 kHz crystal.
esp_spiffs  | Enable the optional SPIFFS drive in on-board flash memory, see section [SPIFFS Device](#esp32_spiffs_device).
esp_spi_ram | Enable the optional SPI RAM, see section [SPI RAM Modules](#esp32_spi_ram).
esp_wifi | Enable the built-in WiFi module as `netdev` network device, see section [WiFi Network Interface](#esp32_wifi_network_interface).

</center>

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

\anchor esp32_flash_modes
## <a name="esp32_flash_modes"> Flash Modes </a> &nbsp;[[TOC](#esp32_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](https://github.com/espressif/esptool/wiki/SPI-Flash-Modes).

## <a name="esp32_esp_log_module"> Log output </a> &nbsp;[[TOC](#esp32_toc)]

The RIOT port for ESP32 implements a log module with a bunch of macros
to generate log output according to the interface as defined in
[system logging header](http://doc.riot-os.org/log_8h.html). These macros
support colored and tagged log output.

The colored log output is enabled by module `esp_log_colored`. If colored log
output is enabled, log messages are displayed in color according to their type:
Error messages are displayed in red, warnings in yellow, information
messages in green and all other message types in standard color.

When the `esp_log_tagged` module is used, all log messages are tagged with
additional information: the type of message, the system time in ms, and the
module or function in which the log message is generated. For example:

```
I (663) [main_trampoline] main(): This is RIOT! (Version: 2019.10-devel-437-gf506a)
```

Either the `LOG_*` macros as defined in
[system logging header](http://doc.riot-os.org/log_8h.html) or the tagged
version `LOG_TAG_*` of these macros can be used to produce tagged log output.
If the `LOG_*` macros are used, the function which generates the log message
is used in the tag while a `tag` parameter is used for the `LOG_TAG_*` macros.
For example,
```
LOG_ERROR("error message");
```
generates a log message in which the name of the calling function is used as
tag. With
```
LOG_TAG_ERROR("mod", "error message");
```
a log message with string `mod` in the tag is generated.

The `esp_log_startup` module can be used to enable additional information
about the boot process, the board configuration, the system configuration,
the CPU used by the system, and the available heap. These information may
help to detect problems during the startup. If the application does not
start as expected, this module should be used.

## <a name="esp32_esp_idf_heap_implementation"> ESP-IDF Heap Implementation </a> &nbsp;[[TOC](#esp32_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
```

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


\anchor esp32_comm_periph
# <a name="esp32_peripherals"> Common Peripherals </a> &nbsp;[[TOC](#esp32_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.

\anchor esp32_gpio_pins
## <a name="esp32_gpio_pins"> GPIO pins </a> &nbsp;[[TOC](#esp32_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.

<center>

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 ```qout```and ```qio```mode, see section [Flash Modes](#esp32_flash_modes)
GPIO10 | In/Out | -   | yes    | Flash SD_DATA3 | only in ```qout```and ```qio```mode, see section [Flash Modes](#esp32_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
GPIO39 | In     | yes | -      | SENSOR_VN   | -

</center>

<b>ADC:</b> these pins can be used as ADC inputs<br>
<b>PU/PD:</b> these pins have software configurable pull-up/pull-down functionality.<br>
{'fraction_non_alphanumeric': 0.11479432120073776, 'fraction_numerical': 0.027852513663976175, 'mean_word_length': 4.211923450039686, 'pattern_counts': {'":': 0, '<': 241, '<?xml version=': 0, '>': 241, 'https://': 34, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '184221', 'n_tokens_mistral': 20575, 'n_tokens_neox': 18485, 'n_words': 6852}