Protocol Reference

This page summarizes the protocol subset implemented by iDotMatrix WLED Usermod 0.9.0. It documents confirmed behavior and WLED integration decisions; it is not intended to claim that every command of every original device is known.

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 development 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 remains authoritative when valid. The most recent app synchronization is retained as an offline fallback.

Power

05 00 07 01 STATE

• 00 = off
• non-zero = on

ACK:

05 00 07 01 01

Brightness

05 00 04 80 PERCENT

PERCENT is clamped to 0..100 and mapped to WLED master brightness.

ACK:

05 00 04 80 01

Full-screen RGB

07 00 02 02 RED GREEN BLUE

ACK:

05 00 02 02 01

The Usermod fills its logical RGB canvas and selects the iDotMatrix WLED effect.

Standalone light effects

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

Seven app-visible effect IDs (0..6) are rendered locally. App palette channels are expanded from the observed 0..127 scale to 0..255.

Graffiti / DIY

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.

Clock

08 00 06 01 FLAGS RED GREEN BLUE

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

ACK:

05 00 06 01 01

64x64 date layouts

On logical 64x64, styles 0 and 3 use native two-line composition when date display is enabled:

• HH:MM remains visible on the upper row;
• DD/MM remains visible on the lower row;
• the two rows are independently centered;
• style 0 retains its animated rainbow frame;
• style 3 retains its solid selected-color background with black digits;
• the clock colon blinks at 1 Hz (500 ms on / 500 ms off).

Smaller logical profiles retain the original time/date alternation behavior.

The official app can emit a short burst of Clock packets with showDate=0 while entering the page or paging between styles. For 64x64 styles 0 and 3, the adapter preserves the last valid date preference across a 1-second entry/style-change grace window. A later stable showDate=0 command is treated as an intentional request to disable the date.

Style 2 separator alignment

For style 2, the time separator is shifted left to sit optically between the hour and minute groups:

• 32x32: 1 native LED left;
• 64x64: 2 native LEDs left;
• 16x16: unchanged.

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

The 0.9 artwork uses a ten-frame animated hourglass. Minutes are white; seconds are orange and turn red during the final ten seconds. At 00:00 the last hourglass frame remains visible. The separator blinks at 1 Hz.

Separator alignment on larger canvases:

• 32x32: 1 native LED right;
• 64x64: 2 native LEDs right;
• 16x16: unchanged.

Stopwatch

The stopwatch uses the captured 09 80 family and preserves start/pause/resume state independently of WLED display ownership. The 0.9 artwork uses a white dial, gray/lilac case, orange top button, red hand, white minutes and orange seconds. The hand has eight positions derived from elapsed time, so pause naturally freezes the artwork.

The separator blinks at 1 Hz and uses the same larger-canvas alignment as Countdown: +1 native LED on 32x32 and +2 on 64x64.

Scoreboard

The scoreboard is rendered locally as two three-digit rows with leading zeroes (000..999):

• player A: top row, #7858F8;
• player B: bottom row, #F82078;
• two empty scanlines separate the rows on the 16x16 reference canvas before normal scaling.

Bulk media

The normal Bulk header is 16 bytes and carries media type, total size, CRC32 and optional feature metadata. Major types include:

• 0x01 GIF/image media
• 0x02 RAW RGB image
• 0x03 TEXT

TEXT may reach 16654 bytes, enough for 64 complete 32x64 glyph records. Large TEXT uses temporary dynamic memory and prefers PSRAM on ESP32-S3.

See Text and Fonts.

Audio / Rhythm

Audio/Rhythm frames select LEVEL or FFT visualization modes. The wire protocol remains the same whether renderer data comes from the phone/BLE stream or from WLED AudioReactive. See Audio Reactive.

Alarm multipart media

Alarm media uses a 24-byte feature header. mediaSize and mediaCRC describe the complete media object, not the current chunk.

Observed markers:

• 0x00 first chunk
• 0x02 continuation

Completion requires:

received == mediaSize
AND
CRC32(full media) == mediaCRC

The marker alone never means “final chunk”.

Program / Schedule multipart media

Schedule activity header: 23 bytes.

Important fields:

• byte 10 = uint8 contentType
• byte 11 = chunk marker
• bytes 12..15 = total media size
• bytes 16..19 = CRC32
• byte 22 = media ID

ACK semantics:

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

Device reset

04 00 03 80

This is an iDotMatrix logical reset, not an ESP32/WLED reboot. It clears Usermod-owned Carousel, alarms, programs and transient state while preserving WLED configuration, Wi-Fi/BLE operation and unrelated LittleFS content.

ACK:

05 00 03 80 01

Carousel / Device Assets

The persistent bank contains 12 playable slots (0..11).

Setup example:

11 00 02 01 0C 00 01 02 03 04 05 06 07 08 09 0A 0B

Bulk metadata includes:

• timeSign in bytes 13..14
• imageIndex in byte 15

imageIndex meanings:

• 0..11 persistent Carousel slots
• 12 transient/show-now
• 13 transient preview

Persistent GIF and TEXT slots are supported.

Preset / Default

Preset is a volatile temporary playlist, independent from Carousel.

Protocol slots:

14..19

Activation:

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

• count = 1..6
• uploads are staged without replacing the active display;
• 06/02 atomically activates the selected pending bank;
• playlist loops cyclically;
• Preset files are cleared at boot/reset and are not restored after reboot.

Large Preset objects use repeated-header Bulk continuation. 0x01 means accepted/incomplete; 0x03 means the complete CRC-valid transport object has reached its terminal stage.