1.. zephyr:board:: xiao_esp32c3
2
3Overview
4********
5
6Seeed Studio XIAO ESP32C3 is an IoT mini development board based on the
7Espressif ESP32-C3 WiFi/Bluetooth dual-mode chip.
8
9For more details see the `Seeed Studio XIAO ESP32C3`_ wiki page.
10
11Hardware
12********
13
14This board is based on the ESP32-C3 with 4MB of flash, WiFi and BLE support. It
15has an USB-C port for programming and debugging, integrated battery charging
16and an U.FL external antenna connector. It is based on a standard XIAO 14 pin
17pinout.
18
19Supported Features
20==================
21
22The XIAO ESP32C3 board configuration supports the following hardware features:
23
24+-----------+------------+------------------+
25| Interface | Controller | Driver/Component |
26+===========+============+==================+
27| PMP       | on-chip    | arch/riscv       |
28+-----------+------------+------------------+
29| INTMTRX   | on-chip    | intc_esp32c3     |
30+-----------+------------+------------------+
31| PINMUX    | on-chip    | pinctrl_esp32    |
32+-----------+------------+------------------+
33| USB UART  | on-chip    | serial_esp32_usb |
34+-----------+------------+------------------+
35| GPIO      | on-chip    | gpio_esp32       |
36+-----------+------------+------------------+
37| UART      | on-chip    | uart_esp32       |
38+-----------+------------+------------------+
39| I2C       | on-chip    | i2c_esp32        |
40+-----------+------------+------------------+
41| SPI       | on-chip    | spi_esp32_spim   |
42+-----------+------------+------------------+
43| TWAI      | on-chip    | can_esp32_twai   |
44+-----------+------------+------------------+
45
46Connections and IOs
47===================
48
49The board uses a standard XIAO pinout, the default pin mapping is the following:
50
51.. figure:: img/xiao_esp32c3_pinout.jpg
52   :align: center
53   :alt: XIAO ESP32C3 Pinout
54
55   XIAO ESP32C3 Pinout
56
57Prerequisites
58=============
59
60Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
61below to retrieve those files.
62
63.. code-block:: console
64
65   west blobs fetch hal_espressif
66
67.. note::
68
69   It is recommended running the command above after :file:`west update`.
70
71Building & Flashing
72*******************
73
74Simple boot
75===========
76
77The board could be loaded using the single binary image, without 2nd stage bootloader.
78It is the default option when building the application without additional configuration.
79
80.. note::
81
82   Simple boot does not provide any security features nor OTA updates.
83
84MCUboot bootloader
85==================
86
87User may choose to use MCUboot bootloader instead. In that case the bootloader
88must be built (and flashed) at least once.
89
90There are two options to be used when building an application:
91
921. Sysbuild
932. Manual build
94
95.. note::
96
97   User can select the MCUboot bootloader by adding the following line
98   to the board default configuration file.
99
100   .. code:: cfg
101
102      CONFIG_BOOTLOADER_MCUBOOT=y
103
104Sysbuild
105========
106
107The sysbuild makes possible to build and flash all necessary images needed to
108bootstrap the board with the ESP32 SoC.
109
110To build the sample application using sysbuild use the command:
111
112.. zephyr-app-commands::
113   :tool: west
114   :zephyr-app: samples/hello_world
115   :board: xiao_esp32c3
116   :goals: build
117   :west-args: --sysbuild
118   :compact:
119
120By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
121images. But it can be configured to create other kind of images.
122
123Build directory structure created by Sysbuild is different from traditional
124Zephyr build. Output is structured by the domain subdirectories:
125
126.. code-block::
127
128  build/
129  ├── hello_world
130  │   └── zephyr
131  │       ├── zephyr.elf
132  │       └── zephyr.bin
133  ├── mcuboot
134  │    └── zephyr
135  │       ├── zephyr.elf
136  │       └── zephyr.bin
137  └── domains.yaml
138
139.. note::
140
141   With ``--sysbuild`` option the bootloader will be re-build and re-flash
142   every time the pristine build is used.
143
144For more information about the system build please read the :ref:`sysbuild` documentation.
145
146Manual build
147============
148
149During the development cycle, it is intended to build & flash as quickly possible.
150For that reason, images can be built one at a time using traditional build.
151
152The instructions following are relevant for both manual build and sysbuild.
153The only difference is the structure of the build directory.
154
155.. note::
156
157   Remember that bootloader (MCUboot) needs to be flash at least once.
158
159For the :code:`Hello, world!` application, follow the instructions below.
160
161.. zephyr-app-commands::
162   :zephyr-app: samples/hello_world
163   :board: xiao_esp32c3
164   :goals: build flash
165
166Since the Zephyr console is by default on the ``usb_serial`` device, we use
167the espressif monitor to view.
168
169.. code-block:: console
170
171   $ west espressif monitor
172
173After the board has automatically reset and booted, you should see the following
174message in the monitor:
175
176.. code-block:: console
177
178   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
179   Hello World! xiao_esp32c3
180
181Debugging
182*********
183
184As with much custom hardware, the ESP32 modules require patches to
185OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
186the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_.
187
188The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
189``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
190parameter when building.
191
192Here is an example for building the :zephyr:code-sample:`hello_world` application.
193
194.. zephyr-app-commands::
195   :zephyr-app: samples/hello_world
196   :board: xiao_esp32c3
197   :goals: build flash
198   :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
199
200You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
201
202.. zephyr-app-commands::
203   :zephyr-app: samples/hello_world
204   :board: xiao_esp32c3
205   :goals: debug
206
207References
208**********
209
210.. target-notes::
211
212.. _`Seeed Studio XIAO ESP32C3`: https://wiki.seeedstudio.com/XIAO_ESP32C3_Getting_Started
213.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
214