.. _esp32:

ESP32
#####

Overview
********

From Wikipedia:

::

   ESP32 is a series of low cost, low power system on a chip microcontrollers
   with integrated Wi-Fi & dual-mode Bluetooth.  The ESP32 series employs a
   Tensilica Xtensa LX6 microprocessor in both dual-core and single-core
   variations.  ESP32 is created and developed by Espressif Systems, a
   Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm
   process. [1]_

The features include the following:

- Dual core Xtensa microprocessor (LX6), running at 160 or 240MHz
- 520KB of SRAM
- 802.11b/g/n/e/i
- Bluetooth v4.2 BR/EDR and BLE
- Various peripherals:

  - 12-bit ADC with up to 18 channels
  - 2x 8-bit DACs
  - 10x touch sensors
  - Temperature sensor
  - 4x SPI
  - 2x I2S
  - 2x I2C
  - 3x UART
  - SD/SDIO/MMC host
  - Slave (SDIO/SPI)
  - Ethernet MAC
  - CAN bus 2.0
  - IR (RX/TX)
  - Motor PWM
  - LED PWM with up to 16 channels
  - Hall effect sensor

- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES)
- 5uA deep sleep current

System requirements
*******************

Prerequisites
=============

Two components are required in order to build this port: the `toolchain`_
and the `SDK`_.  Both are provided by the SoC manufacturer.

The SDK contains headers and a hardware abstraction layer library
(provided only as object files) that are required for the port to
function.

The toolchain is available for Linux, Windows, and Mac hosts and
instructions to obtain and set them up are available in the ESP-IDF
repository, using the toolchain and SDK links above.

Set up build environment
========================

With both the toolchain and SDK installed, the Zephyr build system must be
instructed to use this particular variant by setting the
``ZEPHYR_GCC_VARIANT`` shell variable.  Two other environment variables
should also be set, pointing to, respectively, the path where ESP-IDF can be
located, and where the toolchain has been installed:

.. code-block:: console

   export ZEPHYR_GCC_VARIANT="espressif"
   export ESP_IDF_PATH="/path/to/esp-idf"
   export ESPRESSIF_TOOLCHAIN_PATH="/path/to/xtensa-esp32-elf/"

Since ESP-IDF is an external project in constant development, it's possible
that files that Zephyr depends on will be moved, removed, or renamed.  Those
files are mostly header files containing hardware definitions, which are
unlikely to change and require fixes from the vendor.  In addition to
setting the environment variables above, also check out an earlier version
of ESP-IDF:

.. code-block:: console

   cd ${ESP_IDF_PATH}
   git checkout dc8c33892e0

Flashing
========

Issuing ``make BOARD=esp32 flash`` should work as usual.  Environment
variables can be set to set the serial port device, baud rate, and
other options.  Please refer to the following table for details.

+----------------+---------------+
| Variable       | Default value |
+================+===============+
| ESP_DEVICE     | /dev/ttyUSB0  |
+----------------+---------------+
| ESP_BAUD_RATE  | 921600        |
+----------------+---------------+
| ESP_FLASH_SIZE | detect        |
+----------------+---------------+
| ESP_FLASH_FREQ | 40m           |
+----------------+---------------+
| ESP_FLASH_MODE | dio           |
+----------------+---------------+
| ESP_TOOL       | espidf        |
+----------------+---------------+

It's impossible to determine which serial port the ESP32 board is
connected to, as it uses a generic RS232-USB converter.  The default of
``/dev/ttyUSB0`` is provided as that's often the assigned name on a Linux
machine without any other such converters.

The baud rate of 921600bps is recommended.  If experiencing issues when
flashing, try halving the value a few times (460800, 230400, 115200,
etc).  It might be necessary to change the flash frequency or the flash
mode; please refer to the `esptool documentation`_ for guidance on these
settings.

If ``ESP_TOOL`` is set to "espidf", the `esptool.py`_ script found within
ESP-IDF will be used.  Otherwise, this variable is handled as a path to
the tool.


Using JTAG
==========

In addition to the SoC vendor and SDK, this board also requires a build of
OpenOCD with patches supporting the SoC.  The source code and build
instructions can be obtained from GitHub:

.. code-block:: console

   git clone https://github.com/espressif/openocd-esp32

After building OpenOCD, one should proceed as usual with the setup process.
Since JTAG adapters may be different, this will most likely require editing
the ``esp32.cfg`` file that's in the ``openocd-esp32`` directory.  For
instance, to use a Flyswatter 2 JTAG adapter, one would modify the file so
that the "source" line would read:

.. code-block:: tcl

   source [find interface/ftdi/flyswatter2.cfg]

It might be a good idea to comment the line setting ``ESP32_RTOS`` and
increasing ``adapter_khz`` to 400.  (Or higher, if using another JTAG
adapter, but this value is known to be stable with the Flyswatter.)

After the file has been properly edited, connect the JTAG pins according to
the table below.  Please consult your JTAG adapter manual for the proper
pinout.  Power to the ESP32 board should be provided by a USB cable.

+------------+-----------+
| ESP32 pin  | JTAG pin  |
+============+===========+
| 3V3        | VTRef     |
+------------+-----------+
| EN         | nTRST     |
+------------+-----------+
| IO14       | TMS       |
+------------+-----------+
| IO12       | TDI       |
+------------+-----------+
| GND        | GND       |
+------------+-----------+
| IO13       | TCK       |
+------------+-----------+
| IO15       | TDO       |
+------------+-----------+

Further documentation can be obtained from the SoC vendor in `JTAG debugging
for ESP32`_.

References
**********

.. [1] https://en.wikipedia.org/wiki/ESP32
.. _`ESP32 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
.. _`JTAG debugging for ESP32`: https://espressif.com/sites/default/files/documentation/jtag_debugging_for_esp32_en.pdf
.. _`toolchain`: https://esp-idf.readthedocs.io/en/latest/get-started/index.html#get-started-setup-toochain
.. _`SDK`: https://esp-idf.readthedocs.io/en/latest/get-started/index.html#get-started-get-esp-idf
.. _`Hardware Referecne`: https://esp-idf.readthedocs.io/en/latest/hw-reference/index.html
.. _`esptool documentation`: https://github.com/espressif/esptool/blob/master/README.md
.. _`esptool.py`: https://github.com/espressif/esptool