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
43.. zephyr:board-supported-hw::
44
45System requirements
46*******************
47
48Prerequisites
49=============
50
51Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
52below to retrieve those files.
53
54.. code-block:: console
55
56   west blobs fetch hal_espressif
57
58.. note::
59
60   It is recommended running the command above after :file:`west update`.
61
62Building & Flashing
63*******************
64
65.. zephyr:board-supported-runners::
66
67Simple boot
68===========
69
70The board could be loaded using the single binary image, without 2nd stage bootloader.
71It is the default option when building the application without additional configuration.
72
73.. note::
74
75   Simple boot does not provide any security features nor OTA updates.
76
77MCUboot bootloader
78==================
79
80User may choose to use MCUboot bootloader instead. In that case the bootloader
81must be built (and flashed) at least once.
82
83There are two options to be used when building an application:
84
851. Sysbuild
862. Manual build
87
88.. note::
89
90   User can select the MCUboot bootloader by adding the following line
91   to the board default configuration file.
92
93   .. code:: cfg
94
95      CONFIG_BOOTLOADER_MCUBOOT=y
96
97Sysbuild
98========
99
100The sysbuild makes possible to build and flash all necessary images needed to
101bootstrap the board with the ESP32 SoC.
102
103To build the sample application using sysbuild use the command:
104
105.. zephyr-app-commands::
106   :tool: west
107   :zephyr-app: samples/hello_world
108   :board: esp32c3_supermini
109   :goals: build
110   :west-args: --sysbuild
111   :compact:
112
113By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
114images. But it can be configured to create other kind of images.
115
116Build directory structure created by sysbuild is different from traditional
117Zephyr build. Output is structured by the domain subdirectories:
118
119.. code-block::
120
121  build/
122  ├── hello_world
123  │   └── zephyr
124  │       ├── zephyr.elf
125  │       └── zephyr.bin
126  ├── mcuboot
127  │    └── zephyr
128  │       ├── zephyr.elf
129  │       └── zephyr.bin
130  └── domains.yaml
131
132.. note::
133
134   With ``--sysbuild`` option the bootloader will be re-build and re-flash
135   every time the pristine build is used.
136
137For more information about the system build please read the :ref:`sysbuild` documentation.
138
139Manual build
140============
141
142During the development cycle, it is intended to build & flash as quickly possible.
143For that reason, images can be built one at a time using traditional build.
144
145The instructions following are relevant for both manual build and sysbuild.
146The only difference is the structure of the build directory.
147
148.. note::
149
150   Remember that bootloader (MCUboot) needs to be flash at least once.
151
152Build and flash applications as usual (see :ref:`build_an_application` and
153:ref:`application_run` for more details).
154
155.. zephyr-app-commands::
156   :zephyr-app: samples/hello_world
157   :board: esp32c3_supermini
158   :goals: build
159
160The usual ``flash`` target will work with the ``esp32c3_supermini`` board
161configuration. Here is an example for the :zephyr:code-sample:`hello_world`
162application.
163
164.. zephyr-app-commands::
165   :zephyr-app: samples/hello_world
166   :board: esp32c3_supermini
167   :goals: flash
168
169Open the serial monitor using the following command:
170
171.. code-block:: shell
172
173   west espressif monitor
174
175After the board has automatically reset and booted, you should see the following
176message in the monitor:
177
178.. code-block:: console
179
180   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
181   Hello World! esp32c3_supermini
182
183Debugging
184*********
185
186As with much custom hardware, the ESP32-C3 modules require patches to
187OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
188the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_.
189
190The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
191``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
192parameter when building.
193
194Here is an example for building the :zephyr:code-sample:`hello_world` application.
195
196.. zephyr-app-commands::
197   :zephyr-app: samples/hello_world
198   :board: esp32c3_supermini
199   :goals: build flash
200   :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
201
202You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
203
204.. zephyr-app-commands::
205   :zephyr-app: samples/hello_world
206   :board: esp32c3_supermini
207   :goals: debug
208
209References
210**********
211
212.. target-notes::
213
214.. _`ESP32-C3-SUPERMINI`: https://www.nologo.tech/product/esp32/esp32c3SuperMini/esp32C3SuperMini.html
215.. _`ESP32-C3 Datasheet`: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
216.. _`ESP32-C3 Technical Reference Manual`: https://espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf
217.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
218