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