1.. zephyr:board:: esp32c3_supermini
2
3Overview
4********
5
6ESP32-C3-SUPERMINI is based on the ESP32-C3, a single-core Wi-Fi and Bluetooth 5 (LE) microcontroller SoC,
7based on the open-source RISC-V architecture. This board also includes a Type-C USB Serial/JTAG port.
8There may be multiple variations depending on the specific vendor. For more information a reasonbly well documented version of this board can be found at `ESP32-C3-SUPERMINI`_
9
10Hardware
11********
12
13SoC Features:
14
15- IEEE 802.11 b/g/n-compliant
16- Bluetooth 5, Bluetooth mesh
17- 32-bit RISC-V single-core processor, up to 160MHz
18- 384 KB ROM
19- 400 KB SRAM (16 KB for cache)
20- 8 KB SRAM in RTC
21- 22 x programmable GPIOs
22- 3 x SPI
23- 2 x UART
24- 1 x I2C
25- 1 x I2S
26- 2 x 54-bit general-purpose timers
27- 3 x watchdog timers
28- 1 x 52-bit system timer
29- Remote Control Peripheral (RMT)
30- LED PWM controller (LEDC)
31- Full-speed USB Serial/JTAG controller
32- General DMA controller (GDMA)
33- 1 x TWAI®
34- 2 x 12-bit SAR ADCs, up to 6 channels
35- 1 x soc core temperature sensor
36
37For more information on the ESP32-C3 SOC, check the datasheet at `ESP32-C3 Datasheet`_ or the technical reference
38manual at `ESP32-C3 Technical Reference Manual`_.
39
40Supported Features
41==================
42
43Currently Zephyr's ``esp32c3_supermini`` board target supports the following features:
44
45+------------+------------+-------------------------------------+
46| Interface  | Controller | Driver/Component                    |
47+============+============+=====================================+
48| UART       | on-chip    | serial port                         |
49+------------+------------+-------------------------------------+
50| GPIO       | on-chip    | gpio                                |
51+------------+------------+-------------------------------------+
52| PINMUX     | on-chip    | pinmux                              |
53+------------+------------+-------------------------------------+
54| USB-JTAG   | on-chip    | hardware interface                  |
55+------------+------------+-------------------------------------+
56| SPI Master | on-chip    | spi                                 |
57+------------+------------+-------------------------------------+
58| Timers     | on-chip    | counter                             |
59+------------+------------+-------------------------------------+
60| Watchdog   | on-chip    | watchdog                            |
61+------------+------------+-------------------------------------+
62| TRNG       | on-chip    | entropy                             |
63+------------+------------+-------------------------------------+
64| LEDC       | on-chip    | pwm                                 |
65+------------+------------+-------------------------------------+
66| SPI DMA    | on-chip    | spi                                 |
67+------------+------------+-------------------------------------+
68| TWAI       | on-chip    | can                                 |
69+------------+------------+-------------------------------------+
70| USB-CDC    | on-chip    | serial                              |
71+------------+------------+-------------------------------------+
72| ADC        | on-chip    | adc                                 |
73+------------+------------+-------------------------------------+
74| Wi-Fi      | on-chip    |                                     |
75+------------+------------+-------------------------------------+
76| Bluetooth  | on-chip    |                                     |
77+------------+------------+-------------------------------------+
78
79System requirements
80*******************
81
82Prerequisites
83=============
84
85Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
86below to retrieve those files.
87
88.. code-block:: console
89
90   west blobs fetch hal_espressif
91
92.. note::
93
94   It is recommended running the command above after :file:`west update`.
95
96Building & Flashing
97*******************
98
99Simple boot
100===========
101
102The board could be loaded using the single binary image, without 2nd stage bootloader.
103It is the default option when building the application without additional configuration.
104
105.. note::
106
107   Simple boot does not provide any security features nor OTA updates.
108
109MCUboot bootloader
110==================
111
112User may choose to use MCUboot bootloader instead. In that case the bootloader
113must be built (and flashed) at least once.
114
115There are two options to be used when building an application:
116
1171. Sysbuild
1182. Manual build
119
120.. note::
121
122   User can select the MCUboot bootloader by adding the following line
123   to the board default configuration file.
124
125   .. code:: cfg
126
127      CONFIG_BOOTLOADER_MCUBOOT=y
128
129Sysbuild
130========
131
132The sysbuild makes possible to build and flash all necessary images needed to
133bootstrap the board with the ESP32 SoC.
134
135To build the sample application using sysbuild use the command:
136
137.. zephyr-app-commands::
138   :tool: west
139   :zephyr-app: samples/hello_world
140   :board: esp32c3_supermini
141   :goals: build
142   :west-args: --sysbuild
143   :compact:
144
145By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
146images. But it can be configured to create other kind of images.
147
148Build directory structure created by sysbuild is different from traditional
149Zephyr build. Output is structured by the domain subdirectories:
150
151.. code-block::
152
153  build/
154  ├── hello_world
155  │   └── zephyr
156  │       ├── zephyr.elf
157  │       └── zephyr.bin
158  ├── mcuboot
159  │    └── zephyr
160  │       ├── zephyr.elf
161  │       └── zephyr.bin
162  └── domains.yaml
163
164.. note::
165
166   With ``--sysbuild`` option the bootloader will be re-build and re-flash
167   every time the pristine build is used.
168
169For more information about the system build please read the :ref:`sysbuild` documentation.
170
171Manual build
172============
173
174During the development cycle, it is intended to build & flash as quickly possible.
175For that reason, images can be built one at a time using traditional build.
176
177The instructions following are relevant for both manual build and sysbuild.
178The only difference is the structure of the build directory.
179
180.. note::
181
182   Remember that bootloader (MCUboot) needs to be flash at least once.
183
184Build and flash applications as usual (see :ref:`build_an_application` and
185:ref:`application_run` for more details).
186
187.. zephyr-app-commands::
188   :zephyr-app: samples/hello_world
189   :board: esp32c3_supermini
190   :goals: build
191
192The usual ``flash`` target will work with the ``esp32c3_supermini`` board
193configuration. Here is an example for the :zephyr:code-sample:`hello_world`
194application.
195
196.. zephyr-app-commands::
197   :zephyr-app: samples/hello_world
198   :board: esp32c3_supermini
199   :goals: flash
200
201Open the serial monitor using the following command:
202
203.. code-block:: shell
204
205   west espressif monitor
206
207After the board has automatically reset and booted, you should see the following
208message in the monitor:
209
210.. code-block:: console
211
212   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
213   Hello World! esp32c3_supermini
214
215Debugging
216*********
217
218As with much custom hardware, the ESP32-C3 modules require patches to
219OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
220the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_.
221
222The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
223``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
224parameter when building.
225
226Here is an example for building the :zephyr:code-sample:`hello_world` application.
227
228.. zephyr-app-commands::
229   :zephyr-app: samples/hello_world
230   :board: esp32c3_supermini
231   :goals: build flash
232   :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
233
234You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
235
236.. zephyr-app-commands::
237   :zephyr-app: samples/hello_world
238   :board: esp32c3_supermini
239   :goals: debug
240
241References
242**********
243
244.. target-notes::
245
246.. _`ESP32-C3-SUPERMINI`: https://www.nologo.tech/product/esp32/esp32c3SuperMini/esp32C3SuperMini.html
247.. _`ESP32-C3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
248.. _`ESP32-C3 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf
249.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
250