1.. zephyr:board:: esp32s2_devkitc
2
3Overview
4********
5
6ESP32-S2-DevKitC is an entry-level development board. This board integrates complete Wi-Fi functions.
7Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing.
8Developers can either connect peripherals with jumper wires or mount ESP32-S2-DevKitC on a breadboard.
9For more information, check `ESP32-S2-DevKitC`_.
10
11Hardware
12********
13
14ESP32-S2 is a highly integrated, low-power, single-core Wi-Fi Microcontroller SoC, designed to be secure and
15cost-effective, with a high performance and a rich set of IO capabilities.
16
17The features include the following:
18
19- RSA-3072-based secure boot
20- AES-XTS-256-based flash encryption
21- Protected private key and device secrets from software access
22- Cryptographic accelerators for enhanced performance
23- Protection against physical fault injection attacks
24- Various peripherals:
25
26  - 43x programmable GPIOs
27  - 14x configurable capacitive touch GPIOs
28  - USB OTG
29  - LCD interface
30  - camera interface
31  - SPI
32  - I2S
33  - UART
34  - ADC
35  - DAC
36  - LED PWM with up to 8 channels
37
38For more information, check the datasheet at `ESP32-S2 Datasheet`_ or the technical reference
39manual at `ESP32-S2 Technical Reference Manual`_.
40
41Supported Features
42==================
43
44Current Zephyr's ESP32-S2-devkitc board supports the following features:
45
46+------------+------------+-------------------------------------+
47| Interface  | Controller | Driver/Component                    |
48+============+============+=====================================+
49| UART       | on-chip    | serial port                         |
50+------------+------------+-------------------------------------+
51| GPIO       | on-chip    | gpio                                |
52+------------+------------+-------------------------------------+
53| PINMUX     | on-chip    | pinmux                              |
54+------------+------------+-------------------------------------+
55| USB-JTAG   | on-chip    | hardware interface                  |
56+------------+------------+-------------------------------------+
57| SPI Master | on-chip    | spi                                 |
58+------------+------------+-------------------------------------+
59| Timers     | on-chip    | counter                             |
60+------------+------------+-------------------------------------+
61| Watchdog   | on-chip    | watchdog                            |
62+------------+------------+-------------------------------------+
63| TRNG       | on-chip    | entropy                             |
64+------------+------------+-------------------------------------+
65| LEDC       | on-chip    | pwm                                 |
66+------------+------------+-------------------------------------+
67| PCNT       | on-chip    | qdec                                |
68+------------+------------+-------------------------------------+
69| SPI DMA    | on-chip    | spi                                 |
70+------------+------------+-------------------------------------+
71| ADC        | on-chip    | adc                                 |
72+------------+------------+-------------------------------------+
73| DAC        | on-chip    | dac                                 |
74+------------+------------+-------------------------------------+
75| Wi-Fi      | on-chip    |                                     |
76+------------+------------+-------------------------------------+
77
78System requirements
79===================
80
81Prerequisites
82-------------
83
84Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
85below to retrieve those files.
86
87.. code-block:: console
88
89   west blobs fetch hal_espressif
90
91.. note::
92
93   It is recommended running the command above after :file:`west update`.
94
95Building & Flashing
96*******************
97
98Simple boot
99===========
100
101The board could be loaded using the single binary image, without 2nd stage bootloader.
102It is the default option when building the application without additional configuration.
103
104.. note::
105
106   Simple boot does not provide any security features nor OTA updates.
107
108MCUboot bootloader
109==================
110
111User may choose to use MCUboot bootloader instead. In that case the bootloader
112must be built (and flashed) at least once.
113
114There are two options to be used when building an application:
115
1161. Sysbuild
1172. Manual build
118
119.. note::
120
121   User can select the MCUboot bootloader by adding the following line
122   to the board default configuration file.
123
124   .. code:: cfg
125
126      CONFIG_BOOTLOADER_MCUBOOT=y
127
128Sysbuild
129========
130
131The sysbuild makes possible to build and flash all necessary images needed to
132bootstrap the board with the ESP32 SoC.
133
134To build the sample application using sysbuild use the command:
135
136.. zephyr-app-commands::
137   :tool: west
138   :zephyr-app: samples/hello_world
139   :board: esp32s2_devkitc
140   :goals: build
141   :west-args: --sysbuild
142   :compact:
143
144By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
145images. But it can be configured to create other kind of images.
146
147Build directory structure created by sysbuild is different from traditional
148Zephyr build. Output is structured by the domain subdirectories:
149
150.. code-block::
151
152  build/
153  ├── hello_world
154  │   └── zephyr
155  │       ├── zephyr.elf
156  │       └── zephyr.bin
157  ├── mcuboot
158  │    └── zephyr
159  │       ├── zephyr.elf
160  │       └── zephyr.bin
161  └── domains.yaml
162
163.. note::
164
165   With ``--sysbuild`` option the bootloader will be re-build and re-flash
166   every time the pristine build is used.
167
168For more information about the system build please read the :ref:`sysbuild` documentation.
169
170Manual build
171============
172
173During the development cycle, it is intended to build & flash as quickly possible.
174For that reason, images can be built one at a time using traditional build.
175
176The instructions following are relevant for both manual build and sysbuild.
177The only difference is the structure of the build directory.
178
179.. note::
180
181   Remember that bootloader (MCUboot) needs to be flash at least once.
182
183Build and flash applications as usual (see :ref:`build_an_application` and
184:ref:`application_run` for more details).
185
186.. zephyr-app-commands::
187   :zephyr-app: samples/hello_world
188   :board: esp32s2_devkitc
189   :goals: build
190
191The usual ``flash`` target will work with the ``esp32s2_devkitc`` board
192configuration. Here is an example for the :zephyr:code-sample:`hello_world`
193application.
194
195.. zephyr-app-commands::
196   :zephyr-app: samples/hello_world
197   :board: esp32s2_devkitc
198   :goals: flash
199
200Open the serial monitor using the following command:
201
202.. code-block:: shell
203
204   west espressif monitor
205
206After the board has automatically reset and booted, you should see the following
207message in the monitor:
208
209.. code-block:: console
210
211   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
212   Hello World! esp32s2_devkitc
213
214Debugging
215*********
216
217ESP32-S2 support on OpenOCD is available at `OpenOCD ESP32`_.
218
219The following table shows the pin mapping between ESP32-S2 board and JTAG interface.
220
221+---------------+-----------+
222| ESP32 pin     | JTAG pin  |
223+===============+===========+
224| MTDO / GPIO40 | TDO       |
225+---------------+-----------+
226| MTDI / GPIO41 | TDI       |
227+---------------+-----------+
228| MTCK / GPIO39 | TCK       |
229+---------------+-----------+
230| MTMS / GPIO42 | TMS       |
231+---------------+-----------+
232
233Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32-S2`_.
234
235Here is an example for building the :zephyr:code-sample:`hello_world` application.
236
237.. zephyr-app-commands::
238   :zephyr-app: samples/hello_world
239   :board: esp32s2_devkitc
240   :goals: build flash
241
242You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
243
244.. zephyr-app-commands::
245   :zephyr-app: samples/hello_world
246   :board: esp32s2_devkitc
247   :goals: debug
248
249References
250**********
251
252.. target-notes::
253
254.. _`ESP32-S2-DevKitC`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html
255.. _`ESP32-S2 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf
256.. _`ESP32-S2 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf
257.. _`JTAG debugging for ESP32-S2`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-guides/jtag-debugging/index.html
258.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
259