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