Media Storage

The Usermod uses WLED's LittleFS for persistent or staged media while keeping file ownership scoped to iDotMatrix-managed namespaces.

Carousel

Carousel / Device Assets is persistent:

• 12 slots (0..11);
• GIF and TEXT supported;
• survives BLE disconnect;
• can resume at boot when the iDotMatrix effect is selected as the WLED boot content;
• replacement uses transactional/rollback behavior;
• frame caches may be retained for unchanged GIF content on low-memory backends;
• on the Waveshare direct-decoder path, compressed stored-GIF source images can remain in a bounded PSRAM reuse cache (1 MiB total, 512 KiB per source, 12 metadata entries, LRU), and the immediately following playable GIF can be warmed into that same cache; gifStage peak tracks the largest source actually activated since boot.
• on MatrixPortal S3, the qualified policy uses transient whole-file source staging (256 KiB maximum, 1 MiB reserve), a 384 KiB persistent cache for durable Carousel sources with a 256 KiB per-entry limit and 8 metadata entries, and one-item / approximately 250 ms look-ahead.

Waveshare PSRAM source reuse

The source cache is not a second media store and does not replace LittleFS. Carousel files remain authoritative on disk. The first eligible play stages the source to PSRAM; the same allocation may then remain resident for later Carousel visits. Full Carousel reset/reconfiguration clears the resident cache, and a successful slot replacement invalidates that slot even when the new file has the same size. App-upload/transient GIFs are not retained across playback boundaries.

Dev.11 adds one-item look-ahead only. After the current Carousel item is visible, the player waits 250 ms and considers the immediately following playable item. If that item is a GIF, its source may be copied into the existing persistent source cache before the transition. The active AnimatedGIF source remains untouched, the whole bank is never scanned/preloaded, and a failed look-ahead has no playback side effect.

Cache reuse is observable in /json/info through gifSourceCache=...; a hit avoids a whole-file LittleFS copy and therefore does not increment gifStage attempts.

Preset / Default

Preset is intentionally volatile:

• protocol slots 14..19;
• up to 6 entries;
• pending uploads are staged;
• activation is atomic within the current session;
• temporary files and metadata are cleared at reboot/reset;
• no Preset recovery is attempted after reboot.

Alarm and Program/Schedule

Alarm and Program media may use multipart assembly above normal FA02 reassembly. Committed automation state is kept separate from an in-progress replacement so failed transfers do not destroy the previous valid object.

LittleFS coexistence with WLED / PixelForge

The filesystem is shared with WLED. As a result, media written by iDotMatrix can be visible to other WLED tools such as PixelForge.

The reverse direction is intentionally isolated: iDotMatrix manages only files belonging to its own namespaces and does not perform a blanket filesystem wipe.

Hardware validation confirmed the following behavior on the MatrixPortal 64x64 target:

1. two independent images were added through WLED/PixelForge;
2. a new iDotMatrix Carousel was uploaded;
3. iDotMatrix Presets were uploaded;
4. an iDotMatrix reset was executed;
5. both independently stored WLED/PixelForge images remained present.

This means useful coexistence is possible:

PixelForge/WLED can see compatible iDotMatrix media files
while
iDotMatrix cleanup/reset preserves unrelated WLED files

The official iDotMatrix mobile app does not enumerate arbitrary media already stored on the matrix. Its media library is app-side, so WLED/PixelForge files will not automatically appear inside the iDotMatrix app.

ESP32-C3 OTA filesystem profile

The hardware-validated 4 MB C3 OTA profile uses two 0x1A0000 application slots and a nominal 640 KiB LittleFS partition. The validated firmware binary is 1,551,008 bytes, leaving about 149 KiB of application-slot headroom.

Three consecutive OTA updates were completed with populated iDotMatrix storage. Persistent Carousel and Schedule content remained available across the OTA cycles. Preset was also exercised during qualification, but it is intentionally cleared by the reboot that follows an OTA update and must be uploaded again for a new session. See Build Profiles and Testing and Qualification for the complete evidence.

Reset ownership

The iDotMatrix reset command clears Usermod-owned Carousel / Device Assets, Preset / Default active and pending content, alarms, programs/schedules and transient iDotMatrix state. It preserves WLED configuration, connectivity, time and unrelated filesystem content.