1.. _esp32c3_luatos_core:
2
3ESP32C3_LUATOS_CORE
4###################
5
6Overview
7********
8
9ESP32-C3 is a single-core Wi-Fi and Bluetooth 5 (LE) microcontroller SoC,
10based on the open-source RISC-V architecture. It strikes the right balance of power,
11I/O capabilities and security, thus offering the optimal cost-effective
12solution for connected devices.
13The availability of Wi-Fi and Bluetooth 5 (LE) connectivity not only makes the device configuration easy,
14but it also facilitates a variety of use-cases based on dual connectivity. [1]_
15
16The features include the following:
17
18- 32-bit core RISC-V microcontroller with a maximum clock speed of 160 MHz
19- 400 KB of internal RAM
20- 802.11b/g/n/e/i
21- A Bluetooth LE subsystem that supports features of Bluetooth 5 and Bluetooth Mesh
22- Various peripherals:
23
24  - 12-bit ADC with up to 6 channels
25  - TWAI compatible with CAN bus 2.0
26  - Temperature sensor
27  - 3x SPI
28  - 1x I2S
29  - 1x I2C
30  - 2x UART
31  - LED PWM with up to 6 channels
32
33- Cryptographic hardware acceleration (RNG, ECC, RSA, SHA-2, AES)
34
35There are two version hardware of this board. The difference between them is the ch343 chip.
36
371. USB-C connect to UART over CH343 chip(esp32c3_luatos_core)
38
39.. image:: img/esp32c3_luatos_core.jpg
40     :align: center
41     :alt: esp32c3_luatos_core
42
432. USB-C connect to esp32 chip directly(esp32c3_luatos_core/esp32c3/usb)
44
45.. image:: img/esp32c3_luatos_core_usb.jpg
46     :align: center
47     :alt: esp32c3_luatos_core/esp32c3/usb
48
49Supported Features
50==================
51
52Current Zephyr's ESP32C3_LUATOS_CORE board supports the following features:
53
54+------------+------------+-------------------------------------+
55| Interface  | Controller | Driver/Component                    |
56+============+============+=====================================+
57| UART       | on-chip    | serial port                         |
58+------------+------------+-------------------------------------+
59| GPIO       | on-chip    | gpio                                |
60+------------+------------+-------------------------------------+
61| PINMUX     | on-chip    | pinmux                              |
62+------------+------------+-------------------------------------+
63| USB-JTAG   | on-chip    | hardware interface                  |
64+------------+------------+-------------------------------------+
65| SPI Master | on-chip    | spi                                 |
66+------------+------------+-------------------------------------+
67| Timers     | on-chip    | counter                             |
68+------------+------------+-------------------------------------+
69| Watchdog   | on-chip    | watchdog                            |
70+------------+------------+-------------------------------------+
71| TRNG       | on-chip    | entropy                             |
72+------------+------------+-------------------------------------+
73| LEDC       | on-chip    | pwm                                 |
74+------------+------------+-------------------------------------+
75| SPI DMA    | on-chip    | spi                                 |
76+------------+------------+-------------------------------------+
77| TWAI       | on-chip    | can                                 |
78+------------+------------+-------------------------------------+
79| USB-CDC    | on-chip    | serial                              |
80+------------+------------+-------------------------------------+
81| ADC        | on-chip    | adc                                 |
82+------------+------------+-------------------------------------+
83| Wi-Fi      | on-chip    |                                     |
84+------------+------------+-------------------------------------+
85| Bluetooth  | on-chip    |                                     |
86+------------+------------+-------------------------------------+
87
88.. image:: img/esp32c3_luatos_core_pinfunc.jpg
89     :align: center
90     :alt: esp32c3_luatos_core_pinfunc
91
92System requirements
93*******************
94
95Prerequisites
96=============
97
98Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
99below to retrieve those files.
100
101.. code-block:: console
102
103   west blobs fetch hal_espressif
104
105.. note::
106
107   It is recommended running the command above after :file:`west update`.
108
109Building & Flashing
110*******************
111
112Simple boot
113===========
114
115The board could be loaded using the single binary image, without 2nd stage bootloader.
116It is the default option when building the application without additional configuration.
117
118.. note::
119
120   Simple boot does not provide any security features nor OTA updates.
121
122MCUboot bootloader
123==================
124
125User may choose to use MCUboot bootloader instead. In that case the bootloader
126must be build (and flash) at least once.
127
128There are two options to be used when building an application:
129
1301. Sysbuild
1312. Manual build
132
133.. note::
134
135   User can select the MCUboot bootloader by adding the following line
136   to the board default configuration file.
137
138   .. code:: cfg
139
140      CONFIG_BOOTLOADER_MCUBOOT=y
141
142Sysbuild
143========
144
145The sysbuild makes possible to build and flash all necessary images needed to
146bootstrap the board with the ESP32 SoC.
147
148To build the sample application using sysbuild use the command:
149
150.. zephyr-app-commands::
151   :tool: west
152   :app: samples/hello_world
153   :board: esp32c3_luatos_core
154   :goals: build
155   :west-args: --sysbuild
156   :compact:
157
158By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
159images. But it can be configured to create other kind of images.
160
161Build directory structure created by sysbuild is different from traditional
162Zephyr build. Output is structured by the domain subdirectories:
163
164.. code-block::
165
166  build/
167  ├── hello_world
168  │   └── zephyr
169  │       ├── zephyr.elf
170  │       └── zephyr.bin
171  ├── mcuboot
172  │    └── zephyr
173  │       ├── zephyr.elf
174  │       └── zephyr.bin
175  └── domains.yaml
176
177.. note::
178
179   With ``--sysbuild`` option the bootloader will be re-build and re-flash
180   every time the pristine build is used.
181
182For more information about the system build please read the :ref:`sysbuild` documentation.
183
184Manual build
185============
186
187During the development cycle, it is intended to build & flash as quickly possible.
188For that reason, images can be build one at a time using traditional build.
189
190The instructions following are relevant for both manual build and sysbuild.
191The only difference is the structure of the build directory.
192
193.. note::
194
195   Remember that bootloader (MCUboot) needs to be flash at least once.
196
197Build and flash applications as usual (see :ref:`build_an_application` and
198:ref:`application_run` for more details).
199
200.. zephyr-app-commands::
201   :zephyr-app: samples/hello_world
202   :board: esp32c3_luatos_core
203   :goals: build
204
205The usual ``flash`` target will work with the ``esp32c3_luatos_core`` board
206configuration. Here is an example for the :ref:`hello_world`
207application.
208
209.. zephyr-app-commands::
210   :zephyr-app: samples/hello_world
211   :board: esp32c3_luatos_core
212   :goals: flash
213
214Open the serial monitor using the following command:
215
216.. code-block:: shell
217
218   west espressif monitor
219
220After the board has automatically reset and booted, you should see the following
221message in the monitor:
222
223.. code-block:: console
224
225   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
226   Hello World! esp32c3_luatos_core
227
228Debugging
229*********
230
231As with much custom hardware, the ESP32-C3 modules require patches to
232OpenOCD that are not upstreamed yet. Espressif maintains their own fork of
233the project. The custom OpenOCD can be obtained at `OpenOCD ESP32`_
234
235The Zephyr SDK uses a bundled version of OpenOCD by default. You can overwrite that behavior by adding the
236``-DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>``
237parameter when building.
238
239Here is an example for building the :ref:`hello_world` application.
240
241.. zephyr-app-commands::
242   :zephyr-app: samples/hello_world
243   :board: esp32c3_luatos_core
244   :goals: build flash
245   :gen-args: -DOPENOCD=<path/to/bin/openocd> -DOPENOCD_DEFAULT_PATH=<path/to/openocd/share/openocd/scripts>
246
247You can debug an application in the usual way. Here is an example for the :ref:`hello_world` application.
248
249.. zephyr-app-commands::
250   :zephyr-app: samples/hello_world
251   :board: esp32c3_luatos_core
252   :goals: debug
253
254.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases
255
256References
257**********
258
259.. [1] https://www.espressif.com/en/products/socs/esp32-c3
260.. _ESP32C3 Core Website: https://wiki.luatos.com/chips/esp32c3/board.html
261.. _ESP32C3 Technical Reference Manual: https://espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf
262.. _ESP32C3 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf
263