1.. zephyr:board:: xiao_esp32s3
2
3Overview
4********
5
6Seeed Studio XIAO ESP32S3 and XIAO ESP32S3 Sense are IoT mini development boards based on the
7Espressif ESP32-S3 WiFi/Bluetooth dual-mode chip.
8
9For more details see the `Seeed Studio XIAO ESP32S3`_ wiki page.
10
11.. figure:: img/xiao_esp32s3.jpg
12   :align: center
13   :alt: XIAO ESP32S3
14
15   XIAO ESP32S3
16
17.. figure:: img/xiao-esp32s3-sense.png
18   :align: center
19   :alt: XIAO ESP32S3 Sense
20
21   XIAO ESP32S3 Sense
22
23Hardware
24********
25
26This board is based on the ESP32-S3 with 8MB of flash, WiFi and BLE support. It
27has an USB-C port for programming and debugging, integrated battery charging
28and an U.FL external antenna connector. It is based on a standard XIAO 14 pin
29pinout.
30
31ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 2.4 GHz Wi-Fi
32and Bluetooth® Low Energy (Bluetooth LE). It consists of high-performance dual-core microprocessor
33(Xtensa® 32-bit LX7), a low power coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband,
34RF module, and numerous peripherals.
35
36Additionally, Sense variant integrates a OV2640 camera sensor, microphone and sdcard slot.
37
38Supported Features
39==================
40
41Current Zephyr's XIAO ESP32S3 board supports the following features:
42
43+------------+------------+-------------------------------------+
44| Interface  | Controller | Driver/Component                    |
45+============+============+=====================================+
46| UART       | on-chip    | serial port                         |
47+------------+------------+-------------------------------------+
48| GPIO       | on-chip    | gpio                                |
49+------------+------------+-------------------------------------+
50| PINMUX     | on-chip    | pinmux                              |
51+------------+------------+-------------------------------------+
52| USB-JTAG   | on-chip    | hardware interface                  |
53+------------+------------+-------------------------------------+
54| SPI Master | on-chip    | spi                                 |
55+------------+------------+-------------------------------------+
56| TWAI/CAN   | on-chip    | can                                 |
57+------------+------------+-------------------------------------+
58| ADC        | on-chip    | adc                                 |
59+------------+------------+-------------------------------------+
60| Timers     | on-chip    | counter                             |
61+------------+------------+-------------------------------------+
62| Watchdog   | on-chip    | watchdog                            |
63+------------+------------+-------------------------------------+
64| TRNG       | on-chip    | entropy                             |
65+------------+------------+-------------------------------------+
66| LEDC       | on-chip    | pwm                                 |
67+------------+------------+-------------------------------------+
68| MCPWM      | on-chip    | pwm                                 |
69+------------+------------+-------------------------------------+
70| PCNT       | on-chip    | qdec                                |
71+------------+------------+-------------------------------------+
72| GDMA       | on-chip    | dma                                 |
73+------------+------------+-------------------------------------+
74| LCD_CAM    | on-chip    | lcd_cam                             |
75+------------+------------+-------------------------------------+
76
77Connections and IOs
78===================
79
80The board uses a standard XIAO pinout, the default pin mapping is the following:
81
82.. figure:: img/xiao_esp32s3_pinout.jpg
83   :align: center
84   :alt: XIAO ESP32S3 Pinout
85
86   XIAO ESP32S3 and XIAO ESP32S3 Sense Pinout
87
88Prerequisites
89-------------
90
91Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
92below to retrieve those files.
93
94.. code-block:: console
95
96   west blobs fetch hal_espressif
97
98.. note::
99
100   It is recommended running the command above after :file:`west update`.
101
102Building & Flashing
103*******************
104
105Simple boot
106===========
107
108The board could be loaded using the single binary image, without 2nd stage bootloader.
109It is the default option when building the application without additional configuration.
110
111.. note::
112
113   Simple boot does not provide any security features nor OTA updates.
114
115MCUboot bootloader
116==================
117
118User may choose to use MCUboot bootloader instead. In that case the bootloader
119must be built (and flashed) at least once.
120
121There are two options to be used when building an application:
122
1231. Sysbuild
1242. Manual build
125
126.. note::
127
128   User can select the MCUboot bootloader by adding the following line
129   to the board default configuration file.
130
131   .. code:: cfg
132
133      CONFIG_BOOTLOADER_MCUBOOT=y
134
135Sysbuild
136========
137
138The sysbuild makes possible to build and flash all necessary images needed to
139bootstrap the board with the ESP32 SoC.
140
141To build the sample application using sysbuild use the command:
142
143.. zephyr-app-commands::
144   :tool: west
145   :zephyr-app: samples/hello_world
146   :board: xiao_esp32s3
147   :goals: build
148   :west-args: --sysbuild
149   :compact:
150
151By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
152images. But it can be configured to create other kind of images.
153
154Build directory structure created by sysbuild is different from traditional
155Zephyr build. Output is structured by the domain subdirectories:
156
157.. code-block::
158
159  build/
160  ├── hello_world
161  │   └── zephyr
162  │       ├── zephyr.elf
163  │       └── zephyr.bin
164  ├── mcuboot
165  │    └── zephyr
166  │       ├── zephyr.elf
167  │       └── zephyr.bin
168  └── domains.yaml
169
170.. note::
171
172   With ``--sysbuild`` option the bootloader will be re-build and re-flash
173   every time the pristine build is used.
174
175For more information about the system build please read the :ref:`sysbuild` documentation.
176
177Manual build
178============
179
180During the development cycle, it is intended to build & flash as quickly possible.
181For that reason, images can be built one at a time using traditional build.
182
183The instructions following are relevant for both manual build and sysbuild.
184The only difference is the structure of the build directory.
185
186.. note::
187
188   Remember that bootloader (MCUboot) needs to be flash at least once.
189
190Build and flash applications as usual (see :ref:`build_an_application` and
191:ref:`application_run` for more details).
192
193.. tabs::
194
195   .. group-tab:: XIAO ESP32S3
196
197      .. zephyr-app-commands::
198         :zephyr-app: samples/hello_world
199         :board: xiao_esp32s3/esp32s3/procpu
200         :goals: build
201
202   .. group-tab:: XIAO ESP32S3 Sense
203
204      .. zephyr-app-commands::
205         :zephyr-app: samples/hello_world
206         :board: xiao_esp32s3/esp32s3/procpu/sense
207         :goals: build
208
209The usual ``flash`` target will work with the ``xiao_esp32s3`` board
210configuration. Here is an example for the :zephyr:code-sample:`hello_world`
211application.
212
213.. tabs::
214
215   .. group-tab:: XIAO ESP32S3
216
217      .. zephyr-app-commands::
218         :zephyr-app: samples/hello_world
219         :board: xiao_esp32s3/esp32s3/procpu
220         :goals: flash
221
222   .. group-tab:: XIAO ESP32S3 Sense
223
224      .. zephyr-app-commands::
225         :zephyr-app: samples/hello_world
226         :board: xiao_esp32s3/esp32s3/procpu/sense
227         :goals: flash
228
229Open the serial monitor using the following command:
230
231.. code-block:: shell
232
233   west espressif monitor
234
235After the board has automatically reset and booted, you should see the following
236message in the monitor:
237
238.. code-block:: console
239
240   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
241   Hello World! xiao_esp32s3
242
243Debugging
244*********
245
246ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_.
247
248ESP32-S3 has a built-in JTAG circuitry and can be debugged without any additional chip. Only an USB cable connected to the D+/D- pins is necessary.
249
250Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32-S3`_.
251
252Here is an example for building the :zephyr:code-sample:`hello_world` application.
253
254.. tabs::
255
256   .. group-tab:: XIAO ESP32S3
257
258      .. zephyr-app-commands::
259         :zephyr-app: samples/hello_world
260         :board: xiao_esp32s3/esp32s3/procpu
261         :goals: debug
262
263   .. group-tab:: XIAO ESP32S3 Sense
264
265      .. zephyr-app-commands::
266         :zephyr-app: samples/hello_world
267         :board: xiao_esp32s3/esp32s3/procpu/sense
268         :goals: debug
269
270You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
271
272.. tabs::
273
274   .. group-tab:: XIAO ESP32S3
275
276      .. zephyr-app-commands::
277         :zephyr-app: samples/hello_world
278         :board: xiao_esp32s3/esp32s3/procpu
279         :goals: debug
280
281   .. group-tab:: XIAO ESP32S3 Sense
282
283      .. zephyr-app-commands::
284         :zephyr-app: samples/hello_world
285         :board: xiao_esp32s3/esp32s3/procpu/sense
286         :goals: debug
287
288References
289**********
290
291.. target-notes::
292
293.. _`Seeed Studio XIAO ESP32S3`: https://wiki.seeedstudio.com/xiao_esp32s3_getting_started/
294.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/
295.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
296