Skip to content

Commit d4e302c

Browse files
xingrzkartben
xingrz
authored and
kartben
committed
boards: waveshare: esp32s3_matrix: Bring up board for ESP32-S3-Matrix
ESP32-S3-Matrix is a tiny board from Waveshare, shipped with an ESP32-S3FH4R2, a QMI8658C IMU and an 8x8 WS2812 RGB matrix. Signed-off-by: Chen Xingyu <[email protected]>
1 parent 95996c7 commit d4e302c

15 files changed

+485
-0
lines changed

‎boards/waveshare/esp32s3_matrix/Kconfig

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Copyright (c) 2024 Joel Guittet
2+
# Copyright (c) 2025 Chen Xingyu <[email protected]>
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
config HEAP_MEM_POOL_ADD_SIZE_BOARD
6+
int
7+
default 4096 if BOARD_ESP32S3_MATRIX_ESP32S3_PROCPU
8+
default 256 if BOARD_ESP32S3_MATRIX_ESP32S3_APPCPU

‎boards/waveshare/esp32s3_matrix/Kconfig.esp32s3_matrix

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Copyright (c) 2024 Joel Guittet
2+
# Copyright (c) 2025 Chen Xingyu <[email protected]>
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
config BOARD_ESP32S3_MATRIX
6+
select SOC_ESP32S3_R2
7+
select SOC_ESP32S3_PROCPU if BOARD_ESP32S3_MATRIX_ESP32S3_PROCPU
8+
select SOC_ESP32S3_APPCPU if BOARD_ESP32S3_MATRIX_ESP32S3_APPCPU

‎boards/waveshare/esp32s3_matrix/Kconfig.sysbuild

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Copyright (c) 2024 Espressif Systems (Shanghai) Co., Ltd.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
choice BOOTLOADER
5+
default BOOTLOADER_MCUBOOT
6+
endchoice
7+
8+
choice BOOT_SIGNATURE_TYPE
9+
default BOOT_SIGNATURE_TYPE_NONE
10+
endchoice

‎boards/waveshare/esp32s3_matrix/board.cmake

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Copyright (c) 2024 Joel Guittet
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
if(NOT "${OPENOCD}" MATCHES "^${ESPRESSIF_TOOLCHAIN_PATH}/.*")
5+
set(OPENOCD OPENOCD-NOTFOUND)
6+
endif()
7+
find_program(OPENOCD openocd PATHS ${ESPRESSIF_TOOLCHAIN_PATH}/openocd-esp32/bin NO_DEFAULT_PATH)
8+
9+
include(${ZEPHYR_BASE}/boards/common/esp32.board.cmake)
10+
include(${ZEPHYR_BASE}/boards/common/openocd.board.cmake)

‎boards/waveshare/esp32s3_matrix/board.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
board:
2+
name: esp32s3_matrix
3+
full_name: ESP32-S3-Matrix
4+
vendor: waveshare
5+
socs:
6+
- name: esp32s3

‎boards/waveshare/esp32s3_matrix/doc/img/esp32s3_matrix.webp

22.5 KB
Binary file not shown.

‎boards/waveshare/esp32s3_matrix/doc/index.rst

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
.. zephyr:board:: esp32s3_matrix
2+
3+
Overview
4+
********
5+
6+
The ESP32-S3-Matrix is an ESP32S3 development board from Waveshare with a 8x8
7+
RGB LED matrix. This board integrates complete Wi-Fi and Bluetooth Low Energy
8+
functions, an accelerometer and gyroscope, a battery charger and GPIO extension
9+
port.
10+
11+
Hardware
12+
********
13+
14+
ESP32-S3 is a low-power MCU-based system on a chip (SoC) with integrated 2.4 GHz Wi-Fi
15+
and Bluetooth® Low Energy (Bluetooth LE). It consists of high-performance dual-core microprocessor
16+
(Xtensa® 32-bit LX7), a low power coprocessor, a Wi-Fi baseband, a Bluetooth LE baseband,
17+
RF module, and numerous peripherals.
18+
19+
ESP32-S3-Matrix includes the following features:
20+
21+
- Dual core 32-bit Xtensa Microprocessor (Tensilica LX7), running up to 240MHz
22+
- Additional vector instructions support for AI acceleration
23+
- 512KB of SRAM
24+
- 2MB of PSRAM
25+
- 4MB of FLASH
26+
- Wi-Fi 802.11b/g/n
27+
- Bluetooth LE 5.0 with long-range support and up to 2Mbps data rate
28+
- 8x8 RGB LED matrix
29+
- Accelerometer/gyroscope
30+
31+
Digital interfaces:
32+
33+
- 15 programmable GPIOs
34+
35+
Low Power:
36+
37+
- Power Management Unit with five power modes
38+
- Ultra-Low-Power (ULP) coprocessors: ULP-RISC-V and ULP-FSM
39+
40+
Security:
41+
42+
- Secure boot
43+
- Flash encryption
44+
- 4-Kbit OTP, up to 1792 bits for users
45+
- Cryptographic hardware acceleration: (AES-128/256, Hash, RSA, RNG, HMAC, Digital signature)
46+
47+
Asymmetric Multiprocessing (AMP)
48+
********************************
49+
50+
ESP32-S3 allows 2 different applications to be executed in ESP32-S3 SoC. Due to its dual-core
51+
architecture, each core can be enabled to execute customized tasks in stand-alone mode
52+
and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference.
53+
54+
For more information, check the datasheet at `ESP32-S3 Datasheet`_ or the technical reference
55+
manual at `ESP32-S3 Technical Reference Manual`_.
56+
57+
Supported Features
58+
==================
59+
60+
.. zephyr:board-supported-hw::
61+
62+
Prerequisites
63+
-------------
64+
65+
Espressif HAL requires WiFi and Bluetooth binary blobs in order work. Run the command
66+
below to retrieve those files.
67+
68+
.. code-block:: console
69+
70+
west blobs fetch hal_espressif
71+
72+
.. note::
73+
74+
It is recommended running the command above after :file:`west update`.
75+
76+
Building & Flashing
77+
*******************
78+
79+
.. zephyr:board-supported-runners::
80+
81+
Simple boot
82+
===========
83+
84+
The board could be loaded using the single binary image, without 2nd stage bootloader.
85+
It is the default option when building the application without additional configuration.
86+
87+
.. note::
88+
89+
Simple boot does not provide any security features nor OTA updates.
90+
91+
MCUboot bootloader
92+
==================
93+
94+
User may choose to use MCUboot bootloader instead. In that case the bootloader
95+
must be built (and flashed) at least once.
96+
97+
There are two options to be used when building an application:
98+
99+
1. Sysbuild
100+
2. Manual build
101+
102+
.. note::
103+
104+
User can select the MCUboot bootloader by adding the following line
105+
to the board default configuration file.
106+
107+
.. code:: cfg
108+
109+
CONFIG_BOOTLOADER_MCUBOOT=y
110+
111+
Sysbuild
112+
========
113+
114+
The sysbuild makes possible to build and flash all necessary images needed to
115+
bootstrap the board with the ESP32-S3 SoC.
116+
117+
To build the sample application using sysbuild use the command:
118+
119+
.. zephyr-app-commands::
120+
:tool: west
121+
:zephyr-app: samples/hello_world
122+
:board: esp32s3_matrix/esp32s3/procpu
123+
:goals: build
124+
:west-args: --sysbuild
125+
:compact:
126+
127+
By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
128+
images. But it can be configured to create other kind of images.
129+
130+
Build directory structure created by sysbuild is different from traditional
131+
Zephyr build. Output is structured by the domain subdirectories:
132+
133+
.. code-block::
134+
135+
build/
136+
├── hello_world
137+
│   └── zephyr
138+
│   ├── zephyr.elf
139+
│   └── zephyr.bin
140+
├── mcuboot
141+
│ └── zephyr
142+
│ ├── zephyr.elf
143+
│ └── zephyr.bin
144+
└── domains.yaml
145+
146+
.. note::
147+
148+
With ``--sysbuild`` option the bootloader will be re-build and re-flash
149+
every time the pristine build is used.
150+
151+
For more information about the system build please read the :ref:`sysbuild` documentation.
152+
153+
Manual build
154+
============
155+
156+
During the development cycle, it is intended to build & flash as quickly possible.
157+
For that reason, images can be built one at a time using traditional build.
158+
159+
The instructions following are relevant for both manual build and sysbuild.
160+
The only difference is the structure of the build directory.
161+
162+
.. note::
163+
164+
Remember that bootloader (MCUboot) needs to be flash at least once.
165+
166+
Build and flash applications as usual (see :ref:`build_an_application` and
167+
:ref:`application_run` for more details).
168+
169+
.. zephyr-app-commands::
170+
:zephyr-app: samples/hello_world
171+
:board: esp32s3_matrix/esp32s3/procpu
172+
:goals: build
173+
174+
The usual ``flash`` target will work with the ``esp32s3_matrix`` board
175+
configuration. Here is an example for the :zephyr:code-sample:`hello_world`
176+
application.
177+
178+
.. zephyr-app-commands::
179+
:zephyr-app: samples/hello_world
180+
:board: esp32s3_matrix/esp32s3/procpu
181+
:goals: flash
182+
183+
Open the serial monitor using the following command:
184+
185+
.. code-block:: shell
186+
187+
west espressif monitor
188+
189+
After the board has automatically reset and booted, you should see the following
190+
message in the monitor:
191+
192+
.. code-block:: console
193+
194+
***** Booting Zephyr OS vx.x.x-xxx-gxxxxxxxxxxxx *****
195+
Hello World! esp32s3_matrix
196+
197+
Debugging
198+
*********
199+
200+
ESP32-S3 support on OpenOCD is available at `OpenOCD ESP32`_.
201+
202+
ESP32-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.
203+
204+
Further documentation can be obtained from the SoC vendor in `JTAG debugging for ESP32-S3`_.
205+
206+
Here is an example for building the :zephyr:code-sample:`hello_world` application.
207+
208+
.. zephyr-app-commands::
209+
:zephyr-app: samples/hello_world
210+
:board: esp32s3_matrix/esp32s3/procpu
211+
:goals: build flash
212+
213+
You can debug an application in the usual way. Here is an example for the :zephyr:code-sample:`hello_world` application.
214+
215+
.. zephyr-app-commands::
216+
:zephyr-app: samples/hello_world
217+
:board: esp32s3_matrix/esp32s3/procpu
218+
:goals: debug
219+
220+
References
221+
**********
222+
223+
.. target-notes::
224+
225+
.. _ESP32-S3-Matrix Waveshare Wiki: https://www.waveshare.com/wiki/ESP32-S3-Matrix
226+
.. _ESP32-S3 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf
227+
.. _ESP32-S3 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf
228+
.. _`JTAG debugging for ESP32-S3`: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/
229+
.. _`OpenOCD ESP32`: https://github.com/espressif/openocd-esp32/releases

‎boards/waveshare/esp32s3_matrix/esp32s3_matrix-pinctrl.dtsi

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/*
2+
* Copyright (c) 2024 Joel Guittet
3+
* Copyright (c) 2025 Chen Xingyu <[email protected]>
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
#include <dt-bindings/pinctrl/esp32s3-pinctrl.h>
8+
#include <zephyr/dt-bindings/pinctrl/esp-pinctrl-common.h>
9+
#include <zephyr/dt-bindings/pinctrl/esp32s3-gpio-sigmap.h>
10+
11+
&pinctrl {
12+
spim2_ws2812_led: spim2_ws2812_led {
13+
group1 {
14+
pinmux = <SPIM2_MOSI_GPIO14>;
15+
output-low;
16+
};
17+
};
18+
};

‎boards/waveshare/esp32s3_matrix/esp32s3_matrix_esp32s3_appcpu.dts

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
/*
2+
* Copyright (c) 2024 Joel Guittet
3+
* Copyright (c) 2025 Chen Xingyu <[email protected]>
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
/dts-v1/;
8+
#include <espressif/esp32s3/esp32s3_r2.dtsi>
9+
#include <espressif/partitions_0x0_amp_4M.dtsi>
10+
11+
/ {
12+
model = "ESP32-S3-Matrix APPCPU";
13+
compatible = "waveshare,esp32-s3-matrix";
14+
15+
chosen {
16+
zephyr,sram = &sram1;
17+
zephyr,ipc_shm = &shm0;
18+
zephyr,ipc = &ipm0;
19+
zephyr,flash = &flash0;
20+
zephyr,code-partition = &slot0_appcpu_partition;
21+
};
22+
};
23+
24+
&flash0 {
25+
reg = <0x0 DT_SIZE_M(4)>;
26+
};
27+
28+
&trng0 {
29+
status = "okay";
30+
};

‎boards/waveshare/esp32s3_matrix/esp32s3_matrix_esp32s3_appcpu.yaml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
identifier: esp32s3_matrix/esp32s3/appcpu
2+
name: ESP32-S3-Matrix APPCPU
3+
type: mcu
4+
arch: xtensa
5+
toolchain:
6+
- zephyr
7+
supported:
8+
- uart
9+
testing:
10+
ignore_tags:
11+
- net
12+
- bluetooth
13+
- flash
14+
- cpp
15+
- posix
16+
- watchdog
17+
- logging
18+
- kernel
19+
- pm
20+
- gpio
21+
- crypto
22+
- eeprom
23+
- heap
24+
- cmsis_rtos
25+
- jwt
26+
- zdsp
27+
vendor: waveshare

0 commit comments

Comments
 (0)