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