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