Build Profiles

Build profiles combine two independent choices:

1. the maximum logical iDotMatrix/media profile compiled into the Usermod;
2. the actual WLED hardware environment controlling MCU, flash, PSRAM and physical output.

Current development identification:

release=0.9.4
build=0.9.4

0.9.4 is the current qualified production release; 0.9.3 is the previous stable baseline.

PlatformIO templates live under overrides/; custom partition tables live under partitions/.

Waveshare ESP32-S3-RGB-Matrix — primary 0.9.4 qualification / PSRAM-optimization profile

Override: overrides/waveshare-s3-hub75.ini
Environment: waveshare
Base WLED: 17.0.0-devV5
Base environment: env:waveshare_esp32s3_32MB_hub75
Logical profiles: 16x16, 32x32, 64x64
Legacy low-memory Rescale: hidden/forced off; physical output scaling is automatic.
Physical output: WLED native HUB75
Board: Waveshare ESP32-S3-RGB-Matrix / ESP32-S3-N32R16
Flash / PSRAM: 32 MB / 16 MB

This profile extends the WLED 17.0.0-devV5 Waveshare environment instead of copying its board definition. It inherits the upstream HUB75 pinout/backend, PSRAM configuration, 32 MB partition table, OTA policy, ES8311 audio pins and SD-card flags.

The upstream devV5 Waveshare environment currently declares SHTC3_v2 with a GitHub /commit/ page URL. PlatformIO cannot clone that URL, so the 0.9.4 Waveshare profile intentionally does not inherit the upstream custom_usermods string. It reproduces the same Internal_Temperature and pinned AudioReactive entries, pins SHTC3_v2 with the cloneable form git+https://github.com/lost-hope/SHTC3_v2.git#1f6e3fc..., then adds iDotMatrix.

The iDotMatrix profile adds the 64x64/LZW12 media capacity, default 64x64 logical screen type, NimBLE-Arduino 2.5.1, AnimatedGIF 1.4.7 and Waveshare-specific compile-time/diagnostic guards. It does not replace the WLED partition table or disable OTA.

The physical board/panel baseline passed with the official WLED 16.0.1 Waveshare firmware and one 64x64 HUB75 Half-Scan panel. The iDotMatrix 0.9.4 runtime targets WLED 17.0.0-devV5. The final Waveshare policy is hardware-qualified with a 2 MiB transient GIF stage maximum, 4 MiB PSRAM reserve, 1 MiB persistent source cache, 512 KiB per admitted source, 12 metadata entries, LRU reuse and one-item look-ahead. Hardware qualification also covers native 64x64 plus logical 16x16 and 32x32 automatic scaling with the obsolete low-memory Rescale control disabled.

The old Waveshare entry has been removed from overrides/hub75-legacy.ini; waveshare-s3-hub75.ini is now the single authoritative project recipe for this board.

Qualified MatrixPortal profile

Override: overrides/matrixportal-s3-hub75.ini
Environment: adafruit_matrixportal_esp32s3_idotmatrix_64x64
Logical profiles: 16x16, 32x32, 64x64
Legacy low-memory Rescale: hidden/forced off; physical output scaling is automatic.
Physical output: WLED native HUB75
WLED: 17.0.0-devV5 / 06ae26db67107cb3f6a3d107a92340035991a063

The MatrixPortal profile remains the qualified 0.9.x S3/HUB75 reference. It has 8 MB flash / 2 MiB PSRAM and uses direct AnimatedGIF/PSRAM playback. The final MatrixPortal policy is hardware-qualified with IDOT_GIF_PSRAM_STAGE_MAX=262144, IDOT_GIF_PSRAM_STAGE_RESERVE=1048576, IDOT_GIF_PSRAM_SOURCE_CACHE_MAX_BYTES=393216, IDOT_GIF_PSRAM_SOURCE_CACHE_ENTRY_MAX=262144, IDOT_GIF_PSRAM_SOURCE_CACHE_MAX_ENTRIES=8 and one-item look-ahead enabled. The seven-GIF qualification corpus occupied 249,267 bytes and passed staging, cache reuse, prefetch and mixed invalidation/eviction testing with zero playback fallback. The larger Waveshare 4 MiB reserve / 1 MiB cache policy remains separate.

Optional WLED Buzzer Usermod 0.1.0 / final

Sound support remains an optional second out-of-tree Usermod. Add both repositories to custom_usermods when sound is required. The iDotMatrix profiles do not force this dependency; without it the Buzzer Enable control is disabled and the rest of iDotMatrix continues normally.

ESP32-C3 profiles

All C3 profiles inherit env:esp32c3dev from the pinned WLED baseline:

d55037f7510541eddc390c8f3d01afc5787aa44a
Arduino 3.3.8 / ESP-IDF 5.5.4
WLED shared-RMT
NimBLE-Arduino 2.5.1

iDotMatrix-only / no OTA

Override: overrides/esp32c3-16x16.ini
Environment: esp32c3dev_idotmatrix_16x16
Partition: partitions/WLED_ESP32_4MB_IDOT_NO_OTA.csv

AudioReactive / no OTA

Override: overrides/esp32c3-16x16-audio.ini
Environment: esp32c3dev_idotmatrix_audio_16x16
Partition: partitions/WLED_ESP32_4MB_IDOT_NO_OTA.csv

AudioReactive + dual-slot OTA

Override: overrides/esp32c3-16x16-audio-ota.ini
Environment: esp32c3dev_idotmatrix_audio_16x16_ota
Partition: partitions/WLED_ESP32_4MB_IDOT_OTA.csv

This profile is hardware-validated on ESP32-C3 SuperMini 4 MB + WS2812B ECO 16x16. The exact validated Usermod set is:

custom_usermods =
  audioreactive
  animartrix
  wled-usermod-idotmatrix = symlink://../wled-usermod-idotmatrix

The validated firmware.bin measured 1,551,008 bytes.

Validated 4 MB OTA partition table

partitions/WLED_ESP32_4MB_IDOT_OTA.csv:

nvs       0x009000  0x005000
otadata   0x00E000  0x002000
app0      0x010000  0x1A0000
app1      0x1B0000  0x1A0000
LittleFS  0x350000  0x0A0000
coredump  0x3F0000  0x010000

This provides two 1,703,936-byte application slots, 640 KiB nominal LittleFS and a 64 KiB coredump partition. The validated image leaves 152,928 bytes (about 149 KiB) free in each OTA slot.

Hardware validation completed three consecutive WLED OTA cycles with 12 Carousel assets, six Preset assets, a three-activity Schedule, BLE, shared-RMT output, GIF cache and AudioReactive active in the same build.

Legacy no-OTA partition tables

Flash	Partition table	Application slot	Filesystem
4 MB	partitions/WLED_ESP32_4MB_IDOT_NO_OTA.csv	0x2F0000	0x0F0000
8 MB	partitions/WLED_ESP32_8MB_IDOT_NO_OTA.csv	0x400000	0x3E0000
16 MB	partitions/WLED_ESP32_16MB_IDOT_NO_OTA.csv	0x600000	0x9E0000
32 MB	partitions/WLED_ESP32_32MB_IDOT_NO_OTA.csv	0x600000	0x19E0000

Their matching legacy overrides define WLED_DISABLE_OTA.

Generic media profiles

The repository also supplies:

overrides/16x16.ini
overrides/32x32.ini
overrides/64x64.ini
overrides/64x64-lite.ini
overrides/hub75-legacy.ini

Availability of an environment does not automatically mean that every board/display combination is physically qualified.

Reproducibility rule

When reporting or qualifying hardware, always record Usermod release/build, WLED version and full SHA, exact PlatformIO environment, override file, board/flash/PSRAM details and the tests performed. See Hardware Compatibility Report.