Release 0.9.4 dev.12

Release 0.9.4-dev.12

Release: 0.9.4
Build: 0.9.4-dev.12
Stable behavioral baseline: 0.9.3
Primary optimization target: Waveshare ESP32-S3-RGB-Matrix / WLED 17.0.0-devV5

0.9.4-dev.12 is a narrow telemetry-consolidation build. It keeps the real-device-qualified dev.11 persistent source cache and one-item Carousel GIF look-ahead unchanged and fixes only one diagnostic semantic exposed by cached/prefetched playback.

Dev.11 qualification carried forward

The reported Waveshare hardware run passed both cold-cache and lifecycle checks:

• cold sample: one normal gifStage copy plus three successful look-ahead prefetches;
• later mixed Carousel/Preset activity: gifStage attempts=9 ok=9 fallback=0;
• prefetch: 12/12 successful copies, cached=19, fail=0, bytes=496706;
• source-cache lifecycle: stores=21, invalid=21, final entries=0 bytes=0;
• current largest PSRAM block recovered to 14155776 bytes after the cache was emptied, while historical minLargest remained 13893632;
• final PSRAM snapshot: total=14352384 free=14240004 minFree=13910912 peakUsed=441472;
• no visible animation/dwell delay was reported; Matrix Auto Rotation and AudioReactive remained healthy.

This closes the dev.11 one-item look-ahead gate for the qualified Waveshare configuration.

Telemetry correction

In dev.11, gifStage bytes already described the current AnimatedGIF PSRAM source, including a source activated from persistent/prefetched cache. gifStage peak, however, was updated only after a normal filesystem-to-PSRAM stage copy.

That allowed a valid but misleading snapshot such as:

gifStage=state:psram bytes:49799 peak:1981 attempts:1 ok:1 fallback:0 ...

Dev.12 updates the high-water mark whenever a cached source becomes active. gifStage peak now means the largest whole-file PSRAM source that has actually been active for AnimatedGIF since boot, independent of whether it arrived through normal staging or source-cache reuse.

The diagnostic invariant is therefore restored:

gifStage peak >= gifStage bytes

Cache hits and look-ahead still do not increment normal playback attempts/ok.

Existing telemetry

gifStage=state:<psram|fs> bytes:<current> peak:<active-peak> attempts:<n> ok:<n> fallback:<n> max:<bytes> reserve:<bytes>
gifSourceCache=state:<off|idle|active> entries:<n> bytes:<n> hits:<n> misses:<n> stores:<n> evict:<n> invalid:<n> maxEntries:<n> maxBytes:<bytes> entryMax:<bytes>
gifPrefetch=attempts:<n> ok:<n> cached:<n> fail:<n> bytes:<n>

The dev.8 PSRAM snapshot invariants remain unchanged:

minFree <= free
minLargest <= largest
peakUsed = total - minFree

Waveshare-only optimization policy

The whole-file source stage, persistent source cache and one-item look-ahead remain enabled by default only for IDOT_WAVESHARE_S3_RGB_MATRIX.

Current Waveshare defaults remain unchanged:

• normal stage maximum: 2 MiB;
• free-PSRAM reserve before source allocation: 4 MiB;
• persistent source-cache budget: 1 MiB;
• maximum admitted persistent source: 512 KiB;
• metadata capacity: 12 entries;
• replacement: LRU;
• copy chunk: 4096 bytes with scheduler yield.

MatrixPortal evaluation

Adafruit MatrixPortal ESP32-S3 remains a qualified native 64x64/direct-AnimatedGIF target, but it has only 2 MiB PSRAM. The Waveshare 4 MiB reserve / 1 MiB persistent-cache policy therefore cannot be copied unchanged.

Dev.12 leaves source staging/cache/look-ahead disabled on MatrixPortal. The MatrixPortal S3 profile already emits psram=total/free/minFree/peakUsed/largest/minLargest, so the correct next step is a physical measurement baseline under BLE + native 64x64 HUB75 + GIF/Carousel load, followed by smaller target-specific limits only if the measured headroom justifies them.

Hardware smoke

A long soak is not required. After flashing dev.12 on Waveshare:

1. verify release=0.9.4 and build=0.9.4-dev.12;
2. allow a small source to stage normally and a larger prefetched source to become active;
3. verify gifStage peak >= gifStage bytes in every observed snapshot;
4. verify cache hits still do not increment normal gifStage attempts/ok;
5. verify gifPrefetch fail=0, gifStage fallback=0 and the dev.8 PSRAM invariants;
6. confirm no visible playback regression.

No BLE protocol, AnimatedGIF callback/frame timing, Carousel order/dwell, source-cache limit, prefetch policy, renderer/scaling, automation or external-buzzer behavior changes in dev.12.