iDotMatrix WLED UserMod v0.9.3

Version 0.9.3 is a maintenance and integration release focused on simplifying buzzer support by moving audio playback to the standalone WLED Buzzer Usermod.

Highlights

• Removed the internal iDotMatrix buzzer backend.
• Added optional integration with the external WLED Buzzer Usermod.
• Removed iDotMatrix-specific buzzer GPIO, Active/Passive type, polarity, LEDC and timing configuration.
• Added a single Buzzer → Enable option to the iDotMatrix settings.
  • The option is available when the external Buzzer Usermod is installed.
  • Without the Buzzer Usermod, iDotMatrix continues to compile and run normally with buzzer support disabled.
• Added external buzzer feedback for:
  • BLE connection
  • BLE disconnection
  • Countdown completion
  • Alarm
  • Program / Schedule
• Silent Alarm and Program / Schedule configurations remain silent when requested by the protocol.

External Buzzer integration

Buzzer support now requires the standalone WLED Buzzer Usermod.

The integration is optional and does not create a hard build dependency:

• Buzzer Usermod installed: buzzer integration is available.
• Buzzer Usermod not installed: iDotMatrix works normally and the Buzzer option remains disabled.

iDotMatrix WLED Usermod v0.9.2

Version 0.9.2 improves the iDotMatrix compatibility layer with configurable active/passive buzzer support, persistent Clock preferences, and related configuration and runtime improvements.

Highlights

• Added support for both active and passive buzzers.
• Added configurable passive buzzer trigger polarity:
  • High
  • Low
• Added hardware LEDC tone generation for passive buzzers at 2 kHz.
• Added safe idle-level handling for low-level-trigger passive buzzer modules.
• Added buzzer feedback for:
  • BLE connection
  • Countdown completion
  • Alarm
  • Program / Schedule
• Improved buzzer timing using the ESP32 high-resolution timer to keep sound patterns stable under WLED, BLE, filesystem and media workloads.
• Added Clock preference persistence across reboot.
• Improved the Usermod configuration interface for buzzer settings.

Buzzer support

v0.9.2 contains the buzzer implementation directly inside the iDotMatrix Usermod.

The configuration supports:

• Buzzer GPIO
• Active or Passive buzzer type
• Active-buzzer polarity
• Passive-buzzer trigger polarity
• Test buzzer

Passive buzzer operation uses hardware LEDC at approximately 2 kHz.

Special handling is included for low-level-trigger modules so the GPIO returns to the electrically safe idle state after playback.

Clock persistence

Clock preferences are now persisted and restored during startup before a boot/fallback Clock is rendered.

Persisted settings include:

• Clock style
• 12/24-hour mode
• Show-date option
• Clock color settings

The iDotMatrix reset command also clears the persisted Clock preferences.

Buzzer timing improvements

Alarm and Program / Schedule playback was hardened to avoid timing irregularities caused by media loading and normal WLED loop activity.

On ESP32, buzzer timing uses esp_timer, decoupling sound sequencing from the normal WLED loop and providing stable playback even while other iDotMatrix features are active.

iDotMatrix WLED UserMod v0.9.1

iDotMatrix WLED UserMod 0.9.1 is a maintenance and compatibility release focused on protocol completeness, hardware qualification, and improved build organization.

This release adds hardware-validated support for the original iDotMatrix Graffiti full-raster multipart transfer used by the official app for large 64x64 images. The implementation now correctly reassembles multi-packet RAW RGB transfers and follows the original continuation/final ACK flow observed in real Bluetooth captures.

It also introduces and validates an OTA-capable ESP32-C3 profile for 4 MB devices, using dual application slots while retaining 640 KiB of LittleFS space. The new layout was tested through multiple consecutive OTA updates together with Carousel, Preset, Schedule, BLE, GIF playback, AudioReactive, and normal WLED effects.

Highlights

• Hardware-validated Graffiti 64x64 multipart RAW RGB transfers
• Correct handling of first/continuation Graffiti packets and ACK flow
• ESP32-C3 4 MB OTA profile with dual firmware slots
• 640 KiB LittleFS retained on the OTA C3 layout
• C3 OTA qualification with repeated OTA cycles and media stress testing
• Build-support files reorganized into dedicated overrides/ and partitions/ directories
• Protocol documentation expanded and aligned with the current implementation
• Reset behavior clarified: iDotMatrix-owned Carousel, Preset, Alarm, Program/Schedule and transient state are cleared, while unrelated WLED filesystem content is preserved

Qualified targets

• Adafruit MatrixPortal S3 + 64x64 HUB75 RGB panel
• ESP32-C3 SuperMini + WS2812B 16x16 matrix
• Classic ESP32 profiles inherited from the qualified 0.8.2 baseline, including:
  • 16x16 native operation
  • 32x32 → 16x16 rescaled operation
  • 64x64 → 16x16 64x64-lite operation

WLED baselines

• MatrixPortal S3:

  • WLED 17.0.0-devV5
  • Commit 06ae26db67107cb3f6a3d107a92340035991a063

• ESP32-C3:

  • WLED 17.0.0-devV5
  • Commit d55037f7510541eddc390c8f3d01afc5787aa44a

See the project Wiki for detailed information.

iDotMatrix WLED UserMod 0.9.0

Major release adding native ESP32-S3 / HUB75 64x64 support while preserving compatibility with the existing iDotMatrix application and legacy WLED targets.

Highlights include native 16x16/32x32/64x64 rendering, PSRAM-assisted media handling, large TEXT and 64px fonts, GIF playback, Carousel, Presets, Alarm and Program/Schedule multipart transfers, redesigned Clock/Timer/Scoreboard graphics, improved AudioReactive effects, transactional filesystem handling, and extensive host/hardware validation.

The primary qualified 0.9 target is the Adafruit MatrixPortal S3 with a 64x64 HUB75 RGB panel.

See the project Wiki for installation, supported hardware, architecture, protocol documentation, media formats, build profiles and qualification information.

iDotMatrix WLED Usermod v0.8.2

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.

iDotMatrix WLED UserMod v0.8.1 – ESP32-C3 Support & Stability Improvements

iDotMatrix WLED UserMod v0.8.1

Release 0.8.1 adds officially validated ESP32-C3 support and includes a focused set of stability, recovery, documentation, and test improvements.

Highlights

• Added official ESP32-C3 4 MB / 16×16 matrix support
• Migrated the ESP32-C3 profile to the WLED ESP-IDF 5 / shared-RMT backend
• Added compatibility with NimBLE-Arduino 2.x on the ESP32-C3
• Eliminated the LED flicker/spikes observed with the legacy ESP32-C3 RMT backend while BLE was active
• Preserved the existing stable classic ESP32 + WLED 16.0.1 configuration
• Improved GIF promotion failure handling and recovery
• Made automation/program replacement transactional to prevent filesystem/NVS inconsistencies
• Added comprehensive host-side regression tests for automation persistence and failure paths
• Added GIF filesystem failure-injection tests
• Added ASan/UBSan regression testing
• Corrected and expanded architecture, protocol, build-profile, and testing documentation
• Clarified FA02 packet handling:
  • 4112-byte permanent inline buffer
  • up to 8192-byte logical packets using temporary dynamic storage
• Improved release/build identification and diagnostics

ESP32-C3 validated configuration

The ESP32-C3 build is based on the pinned WLED revision:

d55037f7510541eddc390c8f3d01afc5787aa44a

and uses:

• WLED 17.0.0-devV5
• ESP-IDF 5.5.4
• shared-RMT LED backend
• NimBLE-Arduino 2.5.1
• AnimatedGIF 1.4.7
• compact12/LZW12 GIF decoder

Hardware validation included BLE advertising and connection, iDotMatrix image/GIF playback, WLED effects, repeated WLED ↔ iDotMatrix switching, automation/program execution, WebSocket activity, and approximately 150 combined content/effect changes.

No LED flicker, random pixels, watchdog resets, or stability regressions were observed during the final ESP32-C3 validation.

Supported targets

Classic ESP32

• WLED 16.0.1
• 16×16 matrix
• NimBLE-Arduino 1.4.3
• Existing v0.8.x behaviour preserved

ESP32-C3

• 4 MB flash
• 16×16 matrix
• WLED IDF5/shared-RMT build described above
• NimBLE-Arduino 2.5.1
• Hardware validated

Release identification

• Release: 0.8.1
• Validated build: 0.8.1-audit-fix1

The build identifier is intentionally retained because it identifies the exact source revision that completed the final hardware validation.

Notes

The ESP32-C3 WLED base is intentionally pinned to the revision listed above. Using an arbitrary newer WLED development build is not considered equivalent to the configuration validated for this release.

ESP32-S3 support and further iDotMatrix functionality changes are planned for the next development cycle.

v0.8.0 - Stable ESP32 16x16 Release

WLED iDotMatrix Usermod v0.8.0

First stable release focused on the classic ESP32 / esp32dev target and 16×16 iDotMatrix devices.

Highlights

• Stable ESP32 / esp32dev support
• 16×16 iDotMatrix BLE emulation
• Animated GIF support with compact12/cache
• Improved GIF memory handling and admission checks
• Automatic default BLE name in IDM-xxxxxx format derived from the ESP32 hardware ID
• WLED effects, 2D matrix support, presets and playlists preserved
• Reduced-memory build profile with unused WLED features disabled
• OTA disabled in the supplied profiles to maximize application space
• Clean external usermod integration for WLED 16.0.1
• Updated build and profile documentation

Recommended baseline

• WLED 16.0.1
• Classic ESP32
• 16×16 matrix
• IDOT_GIF_LZW12
• IDOT_SCREEN_MAX_DIM=16

ESP32-C3

ESP32-C3 support is currently under investigation and is not considered supported in v0.8.0.

Initial tests confirmed working BLE communication, but RMT LED output showed occasional flicker and spurious pixels when using the BLE-compatible framework. C3 support will be addressed separately.

This release provides the stable baseline for future hardware targets and larger display profiles.

v0.7.1 – 64x64 media support, low-memory GIF pipeline and stability improvements

iDotMatrix Usermod v0.7.1

This release significantly expands media support and memory efficiency, especially on classic ESP32 boards without PSRAM.

Highlights

• Added 32x32 and 64x64 logical media profiles
• Added low-memory rescaling from 64x64 logical content to smaller physical WLED matrices
• Added a safe compact LZW12 decoder with the full 4096-code dictionary
• Added LittleFS frame caching for 64x64 GIF playback on ESP32 without PSRAM
• Improved GIF-to-GIF transitions and media lifecycle cleanup
• Added RAM-aware predecode scheduling to keep Wi-Fi and the Web UI responsive
• Added black staging during GIF preparation to avoid visible Solid-effect flashes
• Improved WLED ownership handling when switching between iDotMatrix media and normal WLED effects
• Added build/runtime diagnostics in /json/info
• Expanded host tests, regression tests and memory-safety checks

Memory architecture

64x64 GIF decoding on classic ESP32 required a dedicated low-memory path.

The final 0.7.1 architecture keeps the full 12-bit GIF code space while reducing decoder memory usage and moving playback frames to LittleFS cache storage. This allows large and complex GIFs to run while preserving enough internal RAM for WLED, BLE, Wi-Fi and the Web UI.

Boards with PSRAM can use the direct decoder path instead.

Validated configurations

• 16x16 native media
• 32x32 logical media rescaled to 16x16
• 64x64 logical media rescaled to 16x16 on classic ESP32 without PSRAM
• Repeated GIF switching
• Clock → GIF
• WLED effect → GIF
• GIF → GIF
• GIF → WLED effect

Notes

Native 64x64 output, PSRAM-backed direct playback and HUB75 integration remain areas for further validation and development.

See ARCHITECTURE.md, HISTORY.md and RELEASE_NOTES_0.7.1.md for the full technical details.

v0.6.0 – First Stable iDotMatrix Command Foundation

First stable command-capable release

This release establishes the stable foundation of the iDotMatrix Usermod for WLED.

An ESP running WLED can now emulate an iDotMatrix BLE peripheral, be discovered and connected by the official iDotMatrix app, and execute the primary display commands.

Verified functionality

• BLE discovery and connection from the official iDotMatrix app

• Device profiles:

  • 0x01 – 16×16
  • 0x03 – 32×32
  • 0x04 – 64×64

• Correct app power-switch initialization after connection

• Screen ON/OFF mapped to WLED power

• iDotMatrix brightness mapped to WLED master brightness

• Full-screen RGB mapped to WLED static color

• BLE advertising restarted after disconnection

• Wi-Fi and BLE operating together

Architecture

The implementation is divided into independent components:

• IDotMatrixBLEServer – BLE transport, GATT services and bounded receive queue
• IDotMatrixProtocol – packet validation, decoding and responses
• IDotMatrixWLEDAdapter – mapping between protocol events and WLED
• usermod_idotmatrix.cpp – Usermod lifecycle, configuration and diagnostics

BLE callbacks remain short and non-blocking. WLED state changes are processed from the normal Usermod loop.

Important limitations

• Brightness synchronization currently works only from the iDotMatrix app to WLED.
• Brightness changes made directly in WLED cannot update the app slider because no verified device-to-app brightness-state message is known.
• Full-screen RGB affects the active and selected WLED segments.
• Graffiti/pixel drawing and the resolution-independent framebuffer are not implemented yet.
• Text, clock, GIF/media, countdown, stopwatch, alarms and schedules are not included in this release.
• Fragmented commands and payloads larger than the current 64-byte command slot are not yet supported.
• The WLED I2S LED backend is required; RMT is not compatible with BLE on the tested classic ESP32 configuration.
• The supplied 4 MB partition layout disables OTA updates. Upload through USB/serial is required.

Verified build environment

• WLED 0.16.0.1
• Classic ESP32 / esp32dev
• PlatformIO espressif32@~6.13.0
• Arduino-ESP32 2.0.17
• ESP-IDF 4.4.7
• NimBLE-Arduino 1.4.3
• WLED digital LED driver set to I2S

This stable release contains the same runtime source code validated as 0.6.0-dev.7, with consolidated documentation and version metadata.

See README.md, PROTOCOL.md, ARCHITECTURE.md, TESTING.md, HISTORY.md and TODO.md for installation details, protocol coverage, known limitations and the development roadmap.