1.. zephyr:board:: m5stack_cores3 2 3Overview 4******** 5 6M5Stack CoreS3 is an ESP32-based development board from M5Stack. It is the third generation of the M5Stack Core series. 7M5Stack CoreS3 SE is the compact version of CoreS3. It has the same form factor as the original M5Stack, 8and some features were reduced from CoreS3. 9 10M5Stack CoreS3/CoreS3 SE features consist of: 11 12- ESP32-S3 chip (dual-core Xtensa LX7 processor @240MHz, WIFI, OTG and CDC functions) 13- PSRAM 8MB 14- Flash 16MB 15- LCD ISP 2", 320x240 pixel ILI9342C 16- Capacitive multi touch FT6336U 17- Speaker 1W AW88298 18- Dual Microphones ES7210 Audio decoder 19- RTC BM8563 20- USB-C 21- SD-Card slot 22- PMIC AXP2101 23- Battery 500mAh 3.7 V (Not available for CoreS3 SE) 24- Camera 30W pixel GC0308 (Not available for CoreS3 SE) 25- Geomagnetic sensor BMM150 (Not available for CoreS3 SE) 26- Proximity sensor LTR-553ALS-WA (Not available for CoreS3 SE) 27- 6-Axis IMU BMI270 (Not available for CoreS3 SE) 28 29Start Application Development 30***************************** 31 32Before powering up your M5Stack CoreS3, please make sure that the board is in good 33condition with no obvious signs of damage. 34 35System requirements 36=================== 37 38Prerequisites 39------------- 40 41Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command 42below to retrieve those files. 43 44.. code-block:: console 45 46 west blobs fetch hal_espressif 47 48.. note:: 49 50 It is recommended running the command above after :file:`west update`. 51 52Building & Flashing 53******************* 54 55Simple boot 56=========== 57 58The board could be loaded using the single binary image, without 2nd stage bootloader. 59It is the default option when building the application without additional configuration. 60 61.. note:: 62 63 Simple boot does not provide any security features nor OTA updates. 64 65MCUboot bootloader 66================== 67 68User may choose to use MCUboot bootloader instead. In that case the bootloader 69must be built (and flashed) at least once. 70 71There are two options to be used when building an application: 72 731. Sysbuild 742. Manual build 75 76.. note:: 77 78 User can select the MCUboot bootloader by adding the following line 79 to the board default configuration file. 80 81 .. code:: cfg 82 83 CONFIG_BOOTLOADER_MCUBOOT=y 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.. tabs:: 94 95 .. group-tab:: M5Stack CoreS3 96 97 .. zephyr-app-commands:: 98 :tool: west 99 :zephyr-app: samples/hello_world 100 :board: m5stack_cores3/esp32s3/procpu 101 :goals: build 102 :west-args: --sysbuild 103 :compact: 104 105 .. group-tab:: M5Stack CoreS3 SE 106 107 .. zephyr-app-commands:: 108 :tool: west 109 :zephyr-app: samples/hello_world 110 :board: m5stack_cores3/esp32s3/procpu/se 111 :goals: build 112 :west-args: --sysbuild 113 :compact: 114 115By default, the ESP32 sysbuild creates bootloader (MCUboot) and application 116images. But it can be configured to create other kind of images. 117 118Build directory structure created by sysbuild is different from traditional 119Zephyr build. Output is structured by the domain subdirectories: 120 121.. code-block:: 122 123 build/ 124 ├── hello_world 125 │ └── zephyr 126 │ ├── zephyr.elf 127 │ └── zephyr.bin 128 ├── mcuboot 129 │ └── zephyr 130 │ ├── zephyr.elf 131 │ └── zephyr.bin 132 └── domains.yaml 133 134.. note:: 135 136 With ``--sysbuild`` option the bootloader will be re-build and re-flash 137 every time the pristine build is used. 138 139For more information about the system build please read the :ref:`sysbuild` documentation. 140 141Manual build 142============ 143 144During the development cycle, it is intended to build & flash as quickly possible. 145For that reason, images can be built one at a time using traditional build. 146 147The instructions following are relevant for both manual build and sysbuild. 148The only difference is the structure of the build directory. 149 150.. note:: 151 152 Remember that bootloader (MCUboot) needs to be flash at least once. 153 154Build and flash applications as usual (see :ref:`build_an_application` and 155:ref:`application_run` for more details). 156 157.. tabs:: 158 159 .. group-tab:: M5Stack CoreS3 160 161 .. zephyr-app-commands:: 162 :zephyr-app: samples/hello_world 163 :board: m5stack_cores3/esp32s3/procpu 164 :goals: build 165 166 .. group-tab:: M5Stack CoreS3 SE 167 168 .. zephyr-app-commands:: 169 :zephyr-app: samples/hello_world 170 :board: m5stack_cores3/esp32s3/procpu/se 171 :goals: build 172 173The usual ``flash`` target will work with the ``m5stack_cores3/esp32s3/procpu`` board 174configuration. Here is an example for the :zephyr:code-sample:`hello_world` 175application. 176 177.. tabs:: 178 179 .. group-tab:: M5Stack CoreS3 180 181 .. zephyr-app-commands:: 182 :zephyr-app: samples/hello_world 183 :board: m5stack_cores3/esp32s3/procpu 184 :goals: flash 185 186 .. group-tab:: M5Stack CoreS3 SE 187 188 .. zephyr-app-commands:: 189 :zephyr-app: samples/hello_world 190 :board: m5stack_cores3/esp32s3/procpu/se 191 :goals: flash 192 193The baud rate of 921600bps is set by default. If experiencing issues when flashing, 194try using different values by using ``--esp-baud-rate <BAUD>`` option during 195``west flash`` (e.g. ``west flash --esp-baud-rate 115200``). 196 197You can also open the serial monitor using the following command: 198 199.. code-block:: shell 200 201 west espressif monitor 202 203After the board has automatically reset and booted, you should see the following 204message in the monitor: 205 206.. code-block:: console 207 208 *** Booting Zephyr OS build vx.x.x-xxx-gxxxxxxxxxxxx *** 209 Hello World! m5stack_cores3/esp32s3/procpu 210 211Debugging 212********* 213 214ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_. 215 216ESP32-S3 has a built-in JTAG circuitry and can be debugged without any additional chip. Only an USB cable connected to the D+/D- pins is necessary. 217 218Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32-S3`_. 219 220Here is an example for building the :zephyr:code-sample:`hello_world` application. 221 222.. tabs:: 223 224 .. group-tab:: M5Stack CoreS3 225 226 .. zephyr-app-commands:: 227 :zephyr-app: samples/hello_world 228 :board: m5stack_cores3/esp32s3/procpu 229 :goals: debug 230 231 .. group-tab:: M5Stack CoreS3 SE 232 233 .. zephyr-app-commands:: 234 :zephyr-app: samples/hello_world 235 :board: m5stack_cores3/esp32s3/procpu/se 236 :goals: debug 237 238You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application. 239 240.. tabs:: 241 242 .. group-tab:: M5Stack CoreS3 243 244 .. zephyr-app-commands:: 245 :zephyr-app: samples/hello_world 246 :board: m5stack_cores3/esp32s3/procpu 247 :goals: debug 248 249 .. group-tab:: M5Stack CoreS3 SE 250 251 .. zephyr-app-commands:: 252 :zephyr-app: samples/hello_world 253 :board: m5stack_cores3/esp32s3/procpu/se 254 :goals: debug 255 256References 257********** 258 259.. target-notes:: 260 261.. _`M5Stack CoreS3 Documentation`: http://docs.m5stack.com/en/core/CoreS3 262.. _`M5Stack CoreS3 Schematic`: https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/datasheet/core/K128%20CoreS3/Sch_M5_CoreS3_v1.0.pdf 263.. _`M5Stack CoreS3 SE Documentation`: https://docs.m5stack.com/en/core/M5CoreS3%20SE 264.. _`M5Stack CoreS3 SE Schematic`: https://m5stack.oss-cn-shenzhen.aliyuncs.com/resource/docs/products/core/M5CORES3%20SE/M5_CoreS3SE.pdf 265.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases 266.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/ 267
