1.. zephyr:board:: m5stickc_plus
2
3Overview
4********
5
6M5StickC PLUS, one of the core devices in M5Stacks product series, is an ESP32-based development board.
7
8M5StickC PLUS features the following integrated components:
9
10- ESP32-PICO-D4 chip (240MHz dual core, 600 DMIPS, 520KB SRAM, Wi-Fi)
11- ST7789v2, LCD TFT 1.14", 135x240 px screen
12- IMU MPU-6886
13- SPM-1423 microphone
14- RTC BM8563
15- PMU AXP192
16- 120 mAh 3,7 V battery
17
18Some of the ESP32 I/O pins are broken out to the board's pin headers for easy access.
19
20Functional Description
21**********************
22
23The following table below describes the key components, interfaces, and controls
24of the M5StickC PLUS board.
25
26.. _ST7789v2: https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/core/ST7789V.pdf
27.. _MPU-6886: https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/core/MPU-6886-000193%2Bv1.1_GHIC_en.pdf
28.. _ESP32-PICO-D4: https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/core/esp32-pico-d4_datasheet_en.pdf
29.. _SPM-1423: https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/core/SPM1423HM4H-B_datasheet_en.pdf
30
31+------------------+-------------------------------------------------------------------------+
32| Key Component    | Description                                                             |
33+==================+=========================================================================+
34| 32.768 kHz RTC   | External precision 32.768 kHz crystal oscillator serves as a clock with |
35|                  | low-power consumption while the chip is in Deep-sleep mode.             |
36+------------------+-------------------------------------------------------------------------+
37| ESP32-PICO-D4    | This `ESP32-PICO-D4`_ module provides complete Wi-Fi and Bluetooth      |
38| module           | functionalities and integrates a 4-MB SPI flash.                        |
39+------------------+-------------------------------------------------------------------------+
40| Diagnostic LED   | One user LED connected to the GPIO pin.                                 |
41+------------------+-------------------------------------------------------------------------+
42| USB Port         | USB interface. Power supply for the board as well as the                |
43|                  | communication interface between a computer and the board.               |
44|                  | Contains: TypeC x 1, GROVE(I2C+I/O+UART) x 1                            |
45+------------------+-------------------------------------------------------------------------+
46| Power Switch     | Power on/off button.                                                    |
47+------------------+-------------------------------------------------------------------------+
48| A/B user buttons | Two push buttons intended for any user use.                             |
49+------------------+-------------------------------------------------------------------------+
50| LCD screen       | Built-in LCD TFT display \(`ST7789v2`_, 1.14", 135x240 px\) controlled  |
51|                  | by the SPI interface                                                    |
52+------------------+-------------------------------------------------------------------------+
53| MPU-6886         | The `MPU-6886`_ is a 6-axis MotionTracking device that combines a       |
54|                  | 3-axis gyroscope and a 3-axis accelerometer.                            |
55+------------------+-------------------------------------------------------------------------+
56| Built-in         | The `SPM-1423`_ I2S driven microphone.                                  |
57| microphone       |                                                                         |
58+------------------+-------------------------------------------------------------------------+
59
60
61Start Application Development
62*****************************
63
64Before powering up your M5StickC PLUS, please make sure that the board is in good
65condition with no obvious signs of damage.
66
67System requirements
68===================
69
70Prerequisites
71-------------
72
73Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
74below to retrieve those files.
75
76.. code-block:: console
77
78   west blobs fetch hal_espressif
79
80.. note::
81
82   It is recommended running the command above after :file:`west update`.
83
84Building & Flashing
85*******************
86
87Simple boot
88===========
89
90The board could be loaded using the single binary image, without 2nd stage bootloader.
91It is the default option when building the application without additional configuration.
92
93.. note::
94
95   Simple boot does not provide any security features nor OTA updates.
96
97MCUboot bootloader
98==================
99
100User may choose to use MCUboot bootloader instead. In that case the bootloader
101must be built (and flashed) at least once.
102
103There are two options to be used when building an application:
104
1051. Sysbuild
1062. Manual build
107
108.. note::
109
110   User can select the MCUboot bootloader by adding the following line
111   to the board default configuration file.
112
113   .. code:: cfg
114
115      CONFIG_BOOTLOADER_MCUBOOT=y
116
117Sysbuild
118========
119
120The sysbuild makes possible to build and flash all necessary images needed to
121bootstrap the board with the ESP32 SoC.
122
123To build the sample application using sysbuild use the command:
124
125.. zephyr-app-commands::
126   :tool: west
127   :zephyr-app: samples/hello_world
128   :board: m5stickc_plus
129   :goals: build
130   :west-args: --sysbuild
131   :compact:
132
133By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
134images. But it can be configured to create other kind of images.
135
136Build directory structure created by sysbuild is different from traditional
137Zephyr build. Output is structured by the domain subdirectories:
138
139.. code-block::
140
141  build/
142  ├── hello_world
143  │  └── zephyr
144  │       ├── zephyr.elf
145  │       └── zephyr.bin
146  ├── mcuboot
147  │    └── zephyr
148  │       ├── zephyr.elf
149  │       └── zephyr.bin
150  └── domains.yaml
151
152.. note::
153
154   With ``--sysbuild`` option the bootloader will be re-build and re-flash
155   every time the pristine build is used.
156
157For more information about the system build please read the :ref:`sysbuild` documentation.
158
159Manual build
160============
161
162During the development cycle, it is intended to build & flash as quickly possible.
163For that reason, images can be built one at a time using traditional build.
164
165The instructions following are relevant for both manual build and sysbuild.
166The only difference is the structure of the build directory.
167
168.. note::
169
170   Remember that bootloader (MCUboot) needs to be flash at least once.
171
172Build and flash applications as usual (see :ref:`build_an_application` and
173:ref:`application_run` for more details).
174
175.. zephyr-app-commands::
176   :zephyr-app: samples/hello_world
177   :board: m5stickc_plus/esp32/procpu
178   :goals: build
179
180The usual ``flash`` target will work with the ``m5stickc_plus`` board
181configuration. Here is an example for the :zephyr:code-sample:`hello_world`
182application.
183
184.. zephyr-app-commands::
185   :zephyr-app: samples/hello_world
186   :board: m5stickc_plus/esp32/procpu
187   :goals: flash
188
189The default baud rate for the M5StickC PLUS is set to 1500000bps. If experiencing issues when flashing,
190try using different values by using ``--esp-baud-rate <BAUD>`` option during
191``west flash`` (e.g. ``west flash --esp-baud-rate 115200``).
192
193You can also open the serial monitor using the following command:
194
195.. code-block:: shell
196
197   west espressif monitor
198
199After the board has automatically reset and booted, you should see the following
200message in the monitor:
201
202.. code-block:: console
203
204   ***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
205   Hello World! m5stickc_plus
206
207Debugging
208*********
209
210M5StickC PLUS debugging is not supported due to pinout limitations.
211
212Related Documents
213*****************
214
215- `M5StickC PLUS schematic <https://static-cdn.m5stack.com/resource/docs/products/core/m5stickc_plus/m5stickc_plus_sch_03.webp>`_ (WEBP)
216- `ESP32-PICO-D4 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf>`_ (PDF)
217- `M5StickC PLUS docs <https://docs.m5stack.com/en/core/m5stickc_plus>`_
218- `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
219- `ESP32 Hardware Reference <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/index.html>`_
220