Troubleshooting

gifStage remains state:fs on a PSRAM-staging target

Build 0.9.4 has target-specific PSRAM policies. Waveshare keeps the qualified 2 MiB stage maximum, 4 MiB reserve, 1 MiB persistent source cache and one-item look-ahead. MatrixPortal keeps its qualified 256 KiB stage maximum / 1 MiB reserve and 384 KiB persistent source cache with 256 KiB per-entry / 8-entry limits, together with the qualified one-item / approximately 250 ms Carousel look-ahead. gifPrefetch fail should remain zero under the qualified workload. If a source is too large, the reserve/largest-block guard fails, allocation fails or the source copy fails, iDotMatrix intentionally falls back to the original LittleFS decoder path.

Check /json/info for gifStage=...: attempts shows staging decisions, ok successful PSRAM stages and fallback guarded fallbacks. A fallback is not itself a GIF playback failure.

gifSourceCache shows misses but no hits

Persistent source reuse is enabled by default only on the Waveshare profile and only for durable stored GIFs queued by Carousel. App-upload/transient /idot_play.gif is intentionally not retained. A stored GIF larger than 512 KiB can still use normal PSRAM staging but is not admitted to the persistent 1 MiB source cache.

During the first Carousel traversal, misses and stores should increase. On later traversals, hits should increase for resident slots and those hits should not increment gifStage attempts. If evict rises quickly, the active Carousel set is larger than the 1 MiB resident-byte budget; this is measurable policy pressure rather than a playback failure.

If Carousel content is replaced or reconfigured, invalid can increase and resident entries may be cleared. This is expected and prevents stale same-path media from being replayed.

gifPrefetch shows failures

gifPrefetch is an optimization diagnostic, not a playback-failure counter. Dev.11 issues at most one look-ahead after the current Carousel item becomes visible, waits 250 ms, and considers only the immediately following playable GIF.

attempts counts look-ahead copies that actually needed filesystem I/O, ok counts successful admissions, cached counts next sources already resident, and fail counts background copies that could not be completed. A prefetch failure is allowed: when the next GIF is actually played, the normal source-cache/stage/filesystem fallback path remains authoritative. Investigate only if fail grows together with visible transition regressions or playback gifStage fallback.

Waveshare build stops while cloning SHTC3_v2

Symptom:

remote: Not Found
fatal: repository 'https://github.com/lost-hope/SHTC3_v2/commit/1f6e3fc7d6135b704aa41fadf09a36cbf6712834/' not found

This occurs before C++ compilation. The WLED 17.0.0-devV5 Waveshare environment points PlatformIO at a GitHub commit web page instead of a cloneable Git repository URL. iDotMatrix 0.9.4 retains the local waveshare profile fix without modifying WLED by using:

SHTC3_v2 = git+https://github.com/lost-hope/SHTC3_v2.git#1f6e3fc7d6135b704aa41fadf09a36cbf6712834

Do not inherit the upstream Waveshare custom_usermods list unchanged in this build, otherwise the malformed URL is pulled back in. The 0.9.4 Waveshare profile explicitly preserves Internal Temperature and AudioReactive and adds iDotMatrix after the corrected SHTC3 entry.

Waveshare AudioReactive stays on UDP sound sync

On the Waveshare ESP32-S3-RGB-Matrix, the onboard audio hardware was physically detected as ES8311 @ 0x18 plus ES7210 @ 0x40 on the shared SDA 47 / SCL 48 bus. The working I2S pins are SD 39, WS 38, SCK 43, MCLK 12.

If /json/info shows:

Audio Source: UDP sound sync
Sound Processing: suspended
UDP Sound Sync: receive mode

disable UDP Sound Sync receive mode in the AudioReactive settings and reboot. This restores local microphone processing. The state above is a source-selection condition, not evidence that the codec or I2S pins are absent.

The temporary IDOT_WAVESHARE_AUDIO_DIAG probe used during hardware bring-up is not part of the stable release.

The official app connects but content does not appear

Check that WLED exposes the iDotMatrix effect, logical ScreenType matches the intended profile, the physical WLED matrix is configured correctly, no autonomous player is reclaiming ownership, and /json/info reports the expected release/build.

A live TEXT screen is replaced after a few seconds

The current 0.9.3 stable release retains the 0.9.2 live-TEXT ownership fix. Verify:

release=0.9.3
build=0.9.3

If the problem persists, collect /json/info and serial logs.

Font 64 is selectable but large text fails

0.9.3 retains support for the complete 16654-byte 64-glyph / 32x64 TEXT object. Older builds with a 4096-byte transport limit can fail on long font-64 content.

Large Graffiti images fail while small ones work

0.9.3 retains the original full-raster multipart path. A 64x64 raster is normally three complete FA02 packets carrying 4096 RGB bytes each. Verify that the device is actually running the expected 0.9.3 build and that the client is receiving intermediate 05 00 00 00 02 ACKs followed by final 05 00 00 00 01.

Compact inline PNG is a separate single-logical-packet format and should not be confused with full-raster Graffiti.

PlatformIO says UndefinedEnvPlatformError for the C3

A custom environment that defines only the board but neither platform = ... nor extends = ... is incomplete. Use a supplied C3 override, all of which inherit env:esp32c3dev.

Example:

overrides/esp32c3-16x16.ini
env:esp32c3dev_idotmatrix_16x16

C3 OTA profile

Use:

overrides/esp32c3-16x16-audio-ota.ini
env:esp32c3dev_idotmatrix_audio_16x16_ota

The first installation of the new dual-slot partition table must be done over USB/serial. After that, the validated profile supports normal WLED OTA updates.

OTA source/firmware version check unexpectedly fails

The update helper should extract the exact IDOTMATRIX_BUILD string from source and search for that exact substring in firmware.bin. Do not hard-code a regex tied to a development-version naming pattern.

With Bash set -o pipefail, avoid strings ... | grep -q ... because grep -q can exit early and cause strings to receive SIGPIPE. A safe check is:

if strings "$firmware" | grep -F -- "$expected" >/dev/null; then
  printf '%s\n' "$expected"
fi

Stale Usermod path/link

If WLED was moved, remove stale .pio/libdeps/<environment> and .pio/build/<environment> directories so PlatformIO recreates the Usermod link with the current path.

GIF allocation problems

Check logical dimensions, selected media profile, PSRAM availability, free heap diagnostics and whether the target uses direct decode or LittleFS frame cache.

Reset removed iDotMatrix content but not PixelForge files

Expected behavior. iDotMatrix reset deletes only Usermod-owned media and leaves unrelated WLED/PixelForge files intact.

Buzzer Enable is disabled

In 0.9.3 this is expected when the standalone WLED Buzzer Usermod is not compiled into the same firmware. Add WLED Buzzer Usermod release 0.1.0 / build final or newer to custom_usermods and rebuild WLED. iDotMatrix no longer contains its own buzzer GPIO or Active/Passive configuration.

If the checkbox is available but no sound is produced, check the Buzzer Usermod configuration and its /json/info / /json/state diagnostics. The external Usermod must report its hardware service as ready.

PlatformIO still compiles the Buzzer repository when it is not selected

0.9.3 removes the direct external-header include that could trigger PlatformIO LDF auto-discovery. After changing the Buzzer Usermod integration or removing it from custom_usermods, clean the selected PlatformIO environment once so stale library objects/dependency metadata are discarded. The clean iDotMatrix-only build must not compile wled-usermod-buzzer.