Skip to content

iDotMatrix WLED Usermod v0.8.2

Choose a tag to compare

View all tags
@piggei piggei released this 13 Sep 03:16
· 23 commits to main since this release
v0.8.2
bd67792

Stable release of the iDotMatrix compatibility Usermod for WLED.

Version 0.8.2 brings the project to a mature and extensively tested state on the ESP32-C3 16×16 platform, with improved protocol handling, persistent media support, WLED integration, diagnostics, and long-running stability.

Highlights

  • Official iDotMatrix Android app compatibility
  • Native WLED iDotMatrix effect
  • Clock rendering with multiple styles and animated separators
  • TEXT rendering and motion effects
  • GIF and image playback
  • Persistent Carousel support
  • Persistent GIF frame caching to reduce LittleFS writes
  • Alarm support
  • Program / schedule support
  • Buzzer support
  • Audio effects with phone audio input
  • AudioReactive / external microphone integration
  • Persistent state recovery after reboot
  • iDotMatrix protocol reset support
  • Improved BLE FA02 reassembly and transport robustness
  • Improved filesystem transaction and recovery handling
  • Automatic WLED display ownership management
  • Active WLED playlists are stopped when iDotMatrix takes control of the display
  • Extended runtime and reset diagnostics

Major improvements in 0.8.2

Carousel and GIF playback

Persistent Carousel assets can now be replayed without rebuilding the GIF cache on every rotation.

The cache is generated on first use and then reused on subsequent Carousel cycles, substantially reducing LittleFS write amplification and improving playback startup time.

Invalid or failed Carousel entries are isolated without blocking later valid items.

GIF replacement and cache generation use transactional staging so a failed replacement does not destroy previously valid media.

BLE and protocol reliability

The FA02 receive path was redesigned around a single-owner model.

NimBLE callbacks now perform bounded receive/enqueue operations, while protocol assembly, timeout handling, buffer ownership and decoding are handled by the WLED loop.

Additional protection was added for:

  • fragmented transfers
  • interrupted transfers
  • queue pressure
  • bulk-transfer inactivity
  • reconnect scenarios
  • audio / normal-command routing

Display ownership

The interaction between WLED and iDotMatrix has been significantly improved.

When iDotMatrix takes control of the display:

  • background Clock/TEXT/light/audio renderers are stopped correctly
  • GIF decoding cannot be contaminated by a previous animated renderer
  • Carousel-to-Carousel transitions no longer briefly fall back to the Clock
  • active WLED playlists are terminated and pending playlist presets are cancelled

This prevents WLED presets from unexpectedly taking the display back while iDotMatrix content is active.

Clock improvements

Clock layouts were refined to better match the original device behaviour.

The time separator now blinks once per second, while date separators remain static.

Individual clock styles also received pixel-level positioning corrections.

Persistent reset

The iDotMatrix protocol reset now verifies deletion of:

  • Carousel assets
  • cached media
  • alarms
  • alarm media
  • programs
  • schedules
  • transient iDotMatrix state

Reset failures are reported diagnostically without rebooting WLED.

Diagnostics

/json/info now exposes additional iDotMatrix runtime information including:

  • active content
  • Carousel state
  • GIF cache build/reuse statistics
  • BLE transport errors
  • reset results
  • heap status
  • boot reset reason
  • AudioReactive source
  • display-effect ownership state

These diagnostics were extensively used during RC qualification and long-running hardware tests.

Validated hardware

Primary validation platform:

  • ESP32-C3
  • 16×16 RGB matrix
  • WLED 17.0.0-devV5
  • NimBLE 2.x
  • WLED IDF5 / shared-RMT environment

Both standard and AudioReactive builds have been exercised on real hardware.

External microphone / AudioReactive input, alarms, schedules, Carousel playback, GIF caching, reboot persistence and long-running animation playback have been tested successfully.

Compatibility

The release is designed to reproduce the behaviour expected by the official iDotMatrix application while keeping WLED functionality available.

Android compatibility has been validated extensively.

iOS compatibility is currently under investigation. The official iOS application appears to use some BLE behaviour differently from Android, and further protocol captures may be required before iOS support can be considered validated.

Security note

For compatibility with the original iDotMatrix application, the BLE profile remains unauthenticated.

Nearby BLE clients may therefore interact with the exposed iDotMatrix-compatible GATT service.

CRC fields used by the protocol provide integrity checking and must not be considered authentication.

Future work

The next major development line will focus on the new hardware platform and is intentionally kept outside the scope of 0.8.2.

Planned areas include:

  • ESP32-S3
  • PSRAM-aware media handling
  • larger matrices
  • 64×64 testing
  • HUB75 integration
  • additional memory and performance optimizations
  • further iOS compatibility investigation

These changes are expected to form the basis of the future 0.9 development series.

Release: 0.8.2
Build: 0.8.2

This release supersedes the 0.8.2 release candidates and is the recommended stable version for the currently validated ESP32-C3 / 16×16 hardware platform.

Assets 2
Loading