1.. _esp32_devkitc_wroom:
2
3ESP32-DEVKITC-WROOM
4###################
5
6Overview
7********
8
9ESP32-DEVKITC-WROOM is a series of low cost, low power system on a chip microcontrollers
10with integrated Wi-Fi & dual-mode Bluetooth.  The ESP32 series employs a
11Tensilica Xtensa LX6 microprocessor in both dual-core and single-core
12variations.  ESP32-WROOM is created and developed by Espressif Systems, a
13Shanghai-based Chinese company, and is manufactured by TSMC using their 40nm
14process. [1]_
15
16The features include the following:
17
18- Dual core Xtensa microprocessor (LX6), running at 160 or 240MHz
19- 520KB of SRAM
20- 802.11b/g/n/e/i
21- Bluetooth v4.2 BR/EDR and BLE
22- Various peripherals:
23
24  - 12-bit ADC with up to 18 channels
25  - 2x 8-bit DACs
26  - 10x touch sensors
27  - Temperature sensor
28  - 4x SPI
29  - 2x I2S
30  - 2x I2C
31  - 3x UART
32  - SD/SDIO/MMC host
33  - Slave (SDIO/SPI)
34  - Ethernet MAC
35  - CAN bus 2.0
36  - IR (RX/TX)
37  - Motor PWM
38  - LED PWM with up to 16 channels
39  - Hall effect sensor
40
41- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES)
42- 5uA deep sleep current
43
44.. figure:: img/esp32_devkitc_wroom.jpg
45    :align: center
46    :alt: ESP32-DEVKITC-WROOM
47
48    ESP32-DevKitC-WROOM-32D DK
49
50Supported Features
51==================
52
53Current Zephyr's ESP32-WROOM board supports the following features:
54
55+------------+------------+-------------------------------------+
56| Interface  | Controller | Driver/Component                    |
57+============+============+=====================================+
58+------------+------------+-------------------------------------+
59| UART       | on-chip    | serial port                         |
60+------------+------------+-------------------------------------+
61| GPIO       | on-chip    | gpio                                |
62+------------+------------+-------------------------------------+
63| PINMUX     | on-chip    | pinmux                              |
64+------------+------------+-------------------------------------+
65| USB-JTAG   | on-chip    | hardware interface                  |
66+------------+------------+-------------------------------------+
67| SPI Master | on-chip    | spi                                 |
68+------------+------------+-------------------------------------+
69| Timers     | on-chip    | counter                             |
70+------------+------------+-------------------------------------+
71| Watchdog   | on-chip    | watchdog                            |
72+------------+------------+-------------------------------------+
73| TRNG       | on-chip    | entropy                             |
74+------------+------------+-------------------------------------+
75| LEDC       | on-chip    | pwm                                 |
76+------------+------------+-------------------------------------+
77| MCPWM      | on-chip    | pwm                                 |
78+------------+------------+-------------------------------------+
79| PCNT       | on-chip    | qdec                                |
80+------------+------------+-------------------------------------+
81| SPI DMA    | on-chip    | spi                                 |
82+------------+------------+-------------------------------------+
83| TWAI       | on-chip    | can                                 |
84+------------+------------+-------------------------------------+
85| ADC        | on-chip    | adc                                 |
86+------------+------------+-------------------------------------+
87| DAC        | on-chip    | dac                                 |
88+------------+------------+-------------------------------------+
89| Wi-Fi      | on-chip    |                                     |
90+------------+------------+-------------------------------------+
91| Bluetooth  | on-chip    |                                     |
92+------------+------------+-------------------------------------+
93
94System requirements
95===================
96
97Prerequisites
98-------------
99
100Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
101below to retrieve those files.
102
103.. code-block:: console
104
105   west blobs fetch hal_espressif
106
107.. note::
108
109   It is recommended running the command above after :file:`west update`.
110
111Building & Flashing
112-------------------
113
114Build and flash applications as usual (see :ref:`build_an_application` and
115:ref:`application_run` for more details).
116
117.. zephyr-app-commands::
118   :zephyr-app: samples/hello_world
119   :board: esp32_devkitc_wroom
120   :goals: build
121
122The usual ``flash`` target will work with the ``esp32_devkitc_wroom`` board
123configuration. Here is an example for the :ref:`hello_world`
124application.
125
126.. zephyr-app-commands::
127   :zephyr-app: samples/hello_world
128   :board: esp32_devkitc_wroom
129   :goals: flash
130
131Open the serial monitor using the following command:
132
133.. code-block:: shell
134
135   west espressif monitor
136
137After the board has automatically reset and booted, you should see the following
138message in the monitor:
139
140.. code-block:: console
141
142   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
143   Hello World! esp32_devkitc_wroom
144
145Debugging
146---------
147
148ESP32-DEVKITC-WROOM support on OpenOCD is available upstream as of version 0.12.0.
149Download and install OpenOCD from `OpenOCD`_.
150
151On the ESP-WROOM-32 DevKitC board, the JTAG pins are not run to a
152standard connector (e.g. ARM 20-pin) and need to be manually connected
153to the external programmer (e.g. a Flyswatter2):
154
155+------------+-----------+
156| ESP32 pin  | JTAG pin  |
157+============+===========+
158| 3V3        | VTRef     |
159+------------+-----------+
160| EN         | nTRST     |
161+------------+-----------+
162| IO14       | TMS       |
163+------------+-----------+
164| IO12       | TDI       |
165+------------+-----------+
166| GND        | GND       |
167+------------+-----------+
168| IO13       | TCK       |
169+------------+-----------+
170| IO15       | TDO       |
171+------------+-----------+
172
173Further documentation can be obtained from the SoC vendor in `JTAG debugging
174for ESP32`_.
175
176Here is an example for building the :ref:`hello_world` application.
177
178.. zephyr-app-commands::
179   :zephyr-app: samples/hello_world
180   :board: esp32_devkitc_wroom
181   :goals: build flash
182
183You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
184
185.. zephyr-app-commands::
186   :zephyr-app: samples/hello_world
187   :board: esp32_devkitc_wroom
188   :goals: debug
189
190Note on Debugging with GDB Stub
191===============================
192
193GDB stub is enabled on ESP32.
194
195* When adding breakpoints, please use hardware breakpoints with command
196  ``hbreak``. Command ``break`` uses software breakpoints which requires
197  modifying memory content to insert break/trap instructions.
198  This does not work as the code is on flash which cannot be randomly
199  accessed for modification.
200
201.. _`JTAG debugging for ESP32`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html
202.. _`OpenOCD`: https://github.com/openocd-org/openocd
203
204References
205**********
206
207.. [1] https://en.wikipedia.org/wiki/ESP32
208.. _ESP32 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
209.. _Hardware Reference: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html
210