1.. zephyr:board:: m5stack_stamps3
2
3Overview
4********
5
6M5Stack StampS3 is an ESP32-based development board from M5Stack.
7It features the following integrated components:
8
9- ESP32-S3FN8 chip (240MHz dual core)
10- 512KB SRAM
11- 384KB ROM
12- 8MB Flash
13- Wi-Fi
14- Bluetooth
15- User-Button
16
17Functional Description
18**********************
19
20The following table below describes the key components, interfaces, and controls
21of the M5Stack StampS3 module.
22
23+---------------+-----------------------------------------------------------------+-----------+
24| Key Component | Description                                                     | Status    |
25+===============+=================================================================+===========+
26| ESP32-S3FN8   | This MPU-ESP32S3 module provides complete Wi-Fi and Bluetooth   | supported |
27| module        | functionalities and integrates a 8MB flash.                     |           |
28+---------------+-----------------------------------------------------------------+-----------+
29| Status LED    | One user LED connected via :dtcompatible:`worldsemi,ws2812-spi` | supported |
30|               | interface (``led-strip``).                                      |           |
31+---------------+-----------------------------------------------------------------+-----------+
32| USB Port      | USB interface. Power supply for the board as well as the        | supported |
33|               | communication interface between a computer and the board.       |           |
34+---------------+-----------------------------------------------------------------+-----------+
35| User button   | User button (``sw0``)                                           | supported |
36+---------------+-----------------------------------------------------------------+-----------+
37
38Main connector header
39=====================
40
41The Zephyr m5stack_stamps3 board can be used on various applications. It
42therefore publishes a header definition to be used in different shields:
43:dtcompatible:`m5stack,stamps3-header`.
44
45.. figure:: img/m5stack_stamps3_header.webp
46        :align: center
47        :alt: M5Stack StampS3 Header
48        :width: 400 px
49
50        M5Stack StampS3 connector header
51
52Following interfaces are being exported for this header:
53
54- ``m5stack_stamps3_clkout0``: PWM output with 2 channels (0 and 2).
55- ``m5stack_stamps3_spilcd``: SPI interface for interfacing LCDs. Consists of a
56  CLK, MOSI and CS signal.
57- ``m5stack_stamps3_i2c0`` and ``m5stack_stamps3_i2c1``: I2C interfaces (SDA, SCL).
58- ``m5stack_stamps3_uart0``: UART interface (RXD, TXD).
59- ``m5stack_stamps3_header``: All GPIOs are of course accessible via main header
60  definition.
61
62+-----+-----------------------------------------+-----+---------------------------------+
63| Pin | Functions                               | Pin | Functions                       |
64+=====+=========================================+=====+=================================+
65| 1   |                                         |     |                                 |
66+-----+-----------------------------------------+-----+---------------------------------+
67| 2   |                                         |     |                                 |
68+-----+-----------------------------------------+-----+---------------------------------+
69| 3   | ``m5stack_stamps3_clkout0`` - Channel 0 |     |                                 |
70+-----+-----------------------------------------+-----+---------------------------------+
71| 4   |                                         |     |                                 |
72+-----+-----------------------------------------+-----+---------------------------------+
73| 5   | ``m5stack_stamps3_spilcd`` - MOSI       |     |                                 |
74+-----+-----------------------------------------+-----+---------------------------------+
75| 6   | ``m5stack_stamps3_spilcd`` - CLK        |     |                                 |
76+-----+-----------------------------------------+-----+---------------------------------+
77| 7   | ``m5stack_stamps3_spilcd`` - CS         | 28  | **3V3**                         |
78+-----+-----------------------------------------+-----+---------------------------------+
79| 8   |                                         | 27  | ``m5stack_stamps3_uart0`` - TXD |
80+-----+-----------------------------------------+-----+---------------------------------+
81| 9   | ``m5stack_stamps3_clkout0`` - Channel 2 | 26  |                                 |
82+-----+-----------------------------------------+-----+---------------------------------+
83| 10  |                                         | 25  | ``m5stack_stamps3_uart0`` - RXD |
84+-----+-----------------------------------------+-----+---------------------------------+
85| 11  | **GND**                                 | 24  |                                 |
86+-----+-----------------------------------------+-----+---------------------------------+
87| 12  | ``m5stack_stamps3_i2c1`` - SDA          | 23  |                                 |
88+-----+-----------------------------------------+-----+---------------------------------+
89| 13  | **5V**                                  | 22  | **EN**                          |
90+-----+-----------------------------------------+-----+---------------------------------+
91| 14  | ``m5stack_stamps3_i2c1`` - SCL          | 21  |                                 |
92+-----+-----------------------------------------+-----+---------------------------------+
93| 15  | ``m5stack_stamps3_i2c0`` - SDA          | 20  |                                 |
94+-----+-----------------------------------------+-----+---------------------------------+
95| 16  |                                         | 19  |                                 |
96+-----+-----------------------------------------+-----+---------------------------------+
97| 17  | ``m5stack_stamps3_i2c0`` - SCL          | 18  | **GND**                         |
98+-----+-----------------------------------------+-----+---------------------------------+
99
100Power supply
101============
102
103M5Stack StampS3 requires a single 5V input power supply. The module internally
104features a DCDC (MUN3CAD01-SC) to generate the 3.3V needed for the MCU.
105
106The **EN** signal (Pin 22) is an active low signal to enable the **3V3** power
107supply. If this pin is pulled low this main 3.3V power supply for the MCU will be
108deactivated. It is internally equipped with a pull-up and can hence be left open
109if unused.
110
111Start Application Development
112*****************************
113
114Before powering up your M5Stack StampS3, please make sure that the board is in good
115condition with no obvious signs of damage.
116
117System requirements
118===================
119
120Prerequisites
121-------------
122
123Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
124below to retrieve those files.
125
126.. code-block:: console
127
128   west blobs fetch hal_espressif
129
130.. note::
131
132   It is recommended running the command above after :file:`west update`.
133
134Building & Flashing
135-------------------
136
137Build and flash applications as usual (see :ref:`build_an_application` and
138:ref:`application_run` for more details).
139
140.. zephyr-app-commands::
141   :zephyr-app: samples/hello_world
142   :board: m5stack_stamps3/esp32s3/procpu
143   :goals: build
144
145The usual ``flash`` target will work with the ``m5stack_stamps3`` board
146configuration. Here is an example for the :zephyr:code-sample:`hello_world`
147application.
148
149.. zephyr-app-commands::
150   :zephyr-app: samples/hello_world
151   :board: m5stack_stamps3/esp32s3/procpu
152   :goals: flash
153
154The baud rate of 921600bps is set by default. If experiencing issues when flashing,
155try using different values by using ``--esp-baud-rate <BAUD>`` option during
156``west flash`` (e.g. ``west flash --esp-baud-rate 115200``).
157
158You can also open 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! m5stack_stamps3
171
172Debugging
173---------
174
175M5Stack StampS3 exports a JTAG-interface via Pins 19 (MTCK), 21 (MTDO), 23
176(MTDI), 25 (MTMS).
177
178.. note::
179
180   Please note that additional JTAG equipment is needed to utilize JTAG. Refer to
181   the ESP32S3 datasheet and the M5Stack StampS3 documentation for details.
182
183Related Documents
184*****************
185
186- `M5Stack StampS3 schematic <https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/Stamp/S007%20StampS3/Sch_M5StampS3_v0.2.pdf>`_
187- `M5Stack StampS3 <https://docs.m5stack.com/en/core/StampS3>`_
188- `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
189- `ESP32 Hardware Reference <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html>`_
190