Getting Started

This page describes the 0.9.4 stable native-S3 qualification path for the Waveshare ESP32-S3-RGB-Matrix and Adafruit MatrixPortal S3. The release includes the hardware-qualified PSRAM staging, persistent source-cache and one-item look-ahead policies documented in Build Profiles and Testing and Qualification.

Reference hardware

• Waveshare ESP32-S3-RGB-Matrix / ESP32-S3-N32R16
• one 64x64 HUB75 RGB panel
• 32 MB flash / 16 MB PSRAM
• stable 5 V panel power supply sized for the panel

WLED baseline

WLED version: 17.0.0-devV5
Base environment: waveshare_esp32s3_32MB_hub75
iDotMatrix environment: waveshare

The board/panel baseline was physically verified with the official WLED 16.0.1 Waveshare binary before iDotMatrix was added. The current iDotMatrix build target is WLED 17.0.0-devV5.

Repository layout

Place the repositories next to each other:

~/repo/
├── WLED/
└── wled-usermod-idotmatrix/

Build Waveshare 64x64 qualification firmware

From the WLED 17.0.0-devV5 source tree, merge the [env:waveshare] section from overrides/waveshare-s3-hub75.ini into your project-wide platformio_override.ini. If Waveshare is the only local target, the supplied file may also be used as the complete override. Then build with:

pio run -e waveshare -t clean
pio run -e waveshare

The profile inherits the upstream Waveshare partition table, OTA policy, HUB75 pinout/backend and PSRAM setup. It locally reproduces the Waveshare custom-usermod list only to replace the non-cloneable SHTC3_v2 /commit/ URL with the equivalent pinned Git URL.

First WLED configuration

For the verified single-panel baseline:

LED output: HUB75 (Half Scan)
Panel: 64 x 64
No. of Panels: 1
rows x cols: 1 x 1

Also configure WLED's 2D Matrix geometry as 64x64. A 16x16 value there can make only the first four groups of rows appear active even though the HUB75 output itself is correctly configured.

Verify the Usermod

After boot, /json/info should include iDotMatrix lines equivalent to:

release=0.9.4
build=0.9.4
framework=WLED IDF5/HUB75
target=Waveshare-ESP32-S3-RGB-Matrix
wledRelease=17.0.0-devV5
wledBase=devV5

Then verify BLE advertising and original-app connection, Clock, TEXT, static image, GIF, Carousel, native 64x64, reboot/persistence and AudioReactive coexistence. The 16x16/32x32 -> 64x64 scaling gates are hardware-qualified. On native S3 profiles the obsolete low-memory Rescale control is intentionally hidden; 16x16, 32x32 and 64x64 logical profiles fill the physical 64x64 matrix automatically.

Stable MatrixPortal reference

The previously qualified MatrixPortal profile remains available unchanged:

overrides/matrixportal-s3-hub75.ini
adafruit_matrixportal_esp32s3_idotmatrix_64x64
WLED 17.0.0-devV5
06ae26db67107cb3f6a3d107a92340035991a063

ESP32-C3 SuperMini / WS2812B 16x16

Qualified WLED C3 baseline:

d55037f7510541eddc390c8f3d01afc5787aa44a

Conservative no-OTA profile:

cp ../wled-usermod-idotmatrix/overrides/esp32c3-16x16.ini platformio_override.ini
pio run -e esp32c3dev_idotmatrix_16x16 -t clean
pio run -e esp32c3dev_idotmatrix_16x16

AudioReactive no-OTA profile:

cp ../wled-usermod-idotmatrix/overrides/esp32c3-16x16-audio.ini platformio_override.ini
pio run -e esp32c3dev_idotmatrix_audio_16x16 -t clean
pio run -e esp32c3dev_idotmatrix_audio_16x16

Hardware-validated AudioReactive + OTA profile:

cp ../wled-usermod-idotmatrix/overrides/esp32c3-16x16-audio-ota.ini platformio_override.ini
pio run -e esp32c3dev_idotmatrix_audio_16x16_ota -t clean
pio run -e esp32c3dev_idotmatrix_audio_16x16_ota

The first installation of the dual-slot OTA partition table must be done over USB/serial. Subsequent updates can use WLED OTA with firmware.bin from the same profile.

The C3 environments deliberately inherit env:esp32c3dev. A hand-written environment containing only board = esp32-c3-devkitm-1 is incomplete unless it also defines a PlatformIO platform or extends a valid WLED environment.

Build-support directories

Release 0.9.2 keeps build-support files out of the repository root:

overrides/   PlatformIO override templates
partitions/  custom partition tables

See Build Profiles for all supplied environments and partition policies.

Optional sound support in 0.9.3 and later

To enable iDotMatrix sounds, place the standalone Buzzer repository beside the iDotMatrix repository and add it to WLED custom_usermods:

<workdir>/WLED/
<workdir>/wled-usermod-idotmatrix/
<workdir>/wled-usermod-buzzer/

custom_usermods =
  symlink://../wled-usermod-buzzer
  symlink://../wled-usermod-idotmatrix

If the Buzzer Usermod is omitted, iDotMatrix remains functional but the Buzzer Enable control is disabled and no sound is produced.

Waveshare onboard microphone

For the Waveshare ESP32-S3-RGB-Matrix AudioReactive profile, use SD 39, WS 38, SCK 43, MCLK 12. Disable UDP Sound Sync receive mode when local microphone processing is required; with UDP receive enabled, AudioReactive intentionally suspends the local processing path.