Protocol Reference

This page summarizes the protocol subset implemented by iDotMatrix WLED Usermod 0.9.2. It distinguishes captured protocol facts from WLED integration choices; it does not claim that every command of every original device is known.

For field-level implementation details, PROTOCOL.md in the source package is the canonical release reference.

Device information

Request:

04 00 01 80

16x16 example response:

09 00 01 80 RELEASE_MAJOR RELEASE_MINOR 01 SCREEN_TYPE 00

SCREEN_TYPE: 01 = 16x16, 03 = 32x32, 04 = 64x64. The internal build identifier is not encoded in Device Info.

Time synchronization

0B 00 01 80 YEAR MONTH DAY DOW HOUR MINUTE SECOND

ACK: 05 00 01 80 01.

WLED local time/NTP remains the fallback when valid; the last valid app time synchronization is retained for compatibility/offline use.

Power and brightness

Power:

05 00 07 01 STATE

Brightness:

05 00 04 80 PERCENT

Both use standard command ACK status 01; brightness is clamped to 0..100 and mapped to WLED master brightness.

Full-screen RGB and standalone effects

Full RGB:

07 00 02 02 RED GREEN BLUE

Standalone light effects:

LENlo LENhi 03 02 EFFECT SPEED COUNT [R G B]...

Seven app-visible effects are rendered locally into the logical canvas and published through the single iDotMatrix WLED effect.

Graffiti / DIY session and pixels

Session:

05 00 04 01 STATE

Pixel update:

LENlo LENhi 05 01 UNKNOWN R G B X0 Y0 X1 Y1 ...

Coordinates are logical-profile coordinates. Pixel packets do not use the full-raster ACK flow below.

Graffiti full-raster multipart — 0.9.1

The official app has a dedicated type-0 RAW RGB path for publishing a full Graffiti canvas. It is not compact PNG and not generic Bulk RAW.

Each complete FA02 packet has a 9-byte header:

Offset	Size	Field
0	2	logical FA02 packet length, little-endian
2	1	type 0x00
3	1	fixed 0x00 in confirmed capture
4	1	marker: 0x00 first, 0x02 continuation
5	4	complete raster size, little-endian
9	remaining	current RAW RGB chunk

Expected complete RGB sizes:

Screen type	Resolution	Bytes
0x01	16x16	768
0x03	32x32	3072
0x04	64x64	12288

Captured and hardware-validated 64x64 flow:

packet 1: marker 0x00 + 4096 RGB bytes -> 05 00 00 00 02
packet 2: marker 0x02 + 4096 RGB bytes -> 05 00 00 00 02
packet 3: marker 0x02 + 4096 RGB bytes -> 05 00 00 00 01

4096 + 4096 + 4096 = 12288 = 64 * 64 * 3

For this command family 0x02 means accepted/incomplete and 0x01 means complete. There is no CRC field in the confirmed envelope; completion is exact accumulated byte count. The transfer is cancelled on timeout/disconnect/reset or incompatible replacement. The WLED implementation streams chunks into raw-image staging rather than allocating a second full-raster protocol buffer.

Compact inline PNG

A separate type-0 envelope carries a complete PNG in one FA02 logical packet:

LENlo LENhi 00 00 ... PNG_SIZE_LE32 PNG_BYTES...

The payload must begin with the PNG signature and the declared PNG size must equal the bytes present in that logical packet. Successful ACK is 05 00 00 00 03.

This path remains distinct from Graffiti full-raster multipart.

Clock

08 00 06 01 FLAGS RED GREEN BLUE

• FLAGS & 0x3F = style;
• FLAGS & 0x40 = 24-hour mode;
• FLAGS & 0x80 = date enabled.

ACK: 05 00 06 01 01.

On native logical/physical 64x64, styles 0 and 3 keep HH:MM on the upper row and DD/MM on the lower row simultaneously when date is enabled. Style 0 keeps the rainbow border; style 3 uses the selected solid background with black foreground. A 1-second grace window protects the date preference against transient app packets that clear showDate during entry/style changes.

Final 0.9.1 64x64 style 0/3 spacing: HH:MM is unchanged; the day is unchanged; only the date / separator and both month digits are moved two physical LEDs right.

Style 2 time-separator optical correction: 16x16 unchanged, 32x32 one LED left, 64x64 two LEDs left.

Smaller profiles retain the reconstructed 30 s time / 5 s date alternation when date display is enabled.

Clock presentation persistence — 0.9.2 development

The wire command remains unchanged. The Usermod now persists the last stable Clock style, 12/24-hour mode, date visibility and RGB colour in NVS. These values are loaded before standalone Clock fallback can run, so selecting the iDotMatrix WLED effect before reconnecting the phone preserves the previous Clock appearance.

The existing short protection against transient showDate=0 packets during Clock entry/style changes remains in place. Device reset 03 80 clears these stored presentation preferences.

Countdown

07 00 08 80 MODE MINUTES SECONDS

Modes: 0 reset/stop, 1 start/restart, 2 pause, 3 resume. Completion notification: 05 00 08 80 03.

Minutes are white; seconds are orange and red in the final ten seconds. The hourglass has ten frames and freezes at 00:00. Separator blink is 1 Hz; larger-canvas separator alignment is +1 native LED on 32x32 and +2 on 64x64.

Stopwatch

Command family 09 80, with start/reset/pause/resume behavior. White dial, gray/lilac shadow, orange top button, red hand, white minutes and orange seconds. The separator uses the same +1/+2 larger-canvas alignment as Countdown.

Scoreboard

Two three-digit rows with leading zeroes (000..999): A top in #7858F8, B bottom in #F82078.

Normal Bulk media

The normal Bulk header is 16 bytes. Major types:

• 0x01 GIF/image;
• 0x02 RAW RGB;
• 0x03 TEXT.

Generic Bulk status is 0x01 while incomplete and 0x03 at terminal completion. TEXT can reach 16654 bytes, sufficient for 64 complete 32x64 glyph records.

External buzzer service — 0.9.3 and later

The BLE wire protocol is unchanged. Alarm and Program/Schedule continue to use the same protocol buzzer/sound flags, but iDotMatrix no longer owns electrical buzzer configuration. When the standalone WLED Buzzer Usermod is compiled and ready, iDotMatrix translates sound events into requests through the optional weak-link Buzzer service bridge. GPIO, Active/Passive type, polarity, LEDC and timing belong exclusively to the external Usermod.

Alarm multipart media

Alarm uses a 24-byte feature header. mediaSize and mediaCRC describe the complete media object, not the current chunk. Observed marker: 0x00 first, 0x02 continuation. Completion requires exact total size plus full-object CRC32.

Program / Schedule multipart media

Schedule activity header: 23 bytes.

• byte 10 = one-byte contentType;
• byte 11 = chunk marker;
• bytes 12..15 = complete media size;
• bytes 16..19 = CRC32;
• byte 22 = media ID.

Validated ACK flow:

accepted, incomplete -> 05 00 05 80 01
complete + CRC-valid -> 05 00 05 80 03
rejected / failed    -> 05 00 05 80 02

The marker is transport framing and is not part of the media content type or identity.

Device reset

04 00 03 80

This is an iDotMatrix logical reset, not an ESP32/WLED reboot. It clears Usermod-owned Carousel / Device Assets, Preset / Default active and pending content, alarms, programs/schedules and transient iDotMatrix state while preserving WLED configuration, connectivity, time and unrelated LittleFS/PixelForge files.

ACK: 05 00 03 80 01.

Carousel / Device Assets

Persistent bank: 12 playable slots (0..11). GIF and TEXT can be mixed. Bulk metadata uses timeSign in bytes 13..14 and imageIndex in byte 15; indices 12/13 are transient paths rather than extra persistent Carousel slots.

Preset / Default

Preset is a volatile temporary playlist using protocol slots 14..19, maximum six entries. Uploads are staged without replacing the active display; activation is:

[lengthLE16] 06 02 <count> <slot1> ... <slotN>

Activation is transactional within the current session. Preset files are cleared at boot/reset and are not restored after reboot.

Audio / Rhythm

LEVEL and FFT packet formats are unchanged whether renderer values come from phone/BLE or the optional WLED AudioReactive bridge. AudioReactive exports 16 GEQ bands; adjacent pairs are averaged to the eight legacy iDotMatrix bands.

External buzzer service mapping

The BLE wire protocol did not change when the external buzzer service was introduced in 0.9.3 and remains unchanged in 0.9.4. Alarm buzzer fields and Program/Schedule sound flags retain their existing meanings. The implementation change is local: iDotMatrix translates those events to weak-link Buzzer service calls when the standalone WLED Buzzer Usermod is compiled and enabled. No GPIO, polarity or tone-generation fields are added to the BLE protocol.