Luxafor Flag HID Reference

Device identity

On power-up the device runs a self-test and blinks white before settling. The self-test is a finite effect, so when it settles the device emits a 0x00 0x01 finished report (see Responses). If you read right after connecting, expect that report to arrive on its own.

Report format

Every command and response is an 8-byte report. Byte [0] is the opcode. The rest are arguments.

[0]      [1]    [2]   [3]   [4]    [5]     [6]     [7] 
opcode   arg1    R     G     B     opt1    opt2    opt3

The HID descriptor declares no Report ID (implicit 0 ). Some raw-HID libraries require you to prepend a 0x00 Report ID byte to the buffer, making it 9 bytes, while others add it for you. The tables below are report-relative ( [0] is the opcode). Prepend 0x00 if your library needs it.

• 6 LEDs. The LED selector byte is a single 1-based index ( 1..6 ), or 0xFF for all. It is not a bitmask, so it addresses one LED or all of them. To set several specific LEDs, send one report per LED. With 0x01 these apply instantly, so they read as simultaneous. Other values are out of range.
• Always send color as R, G, B in [ 2 ] [ 3 ] [ 4 ] .
• LEDs accept full 0..255 per channel on solid and fade. Strobe and wave run at half brightness (max effective value 127 per channel).
• Speed and period bytes are in units of about 251 us per animation step. 0 is fastest.

Commands (host to device)

0x01 — Set solid color

Sets color immediately with no animation. This is also the color a finite effect returns to when it finishes. Set it first if you want effects to fall back to it. It defaults to off if you never do.

0x02 — Fade to color

Fades each channel to the target. [5] is the step interval, where larger is slower. Emits a finished report when complete. Blends are linear in RGB space.

0x03 — Strobe / blink

Blinks all LEDs. [5] is the blink period. [7] is the repeat count, where 0 means infinite.

0x04 — Wave

Runs a wave animation across the LEDs. [6] is the repeat count, where 0 means infinite. [7] is the step speed. Use only wave types 1..4 .

0x06 — Built-in pattern

Plays a built-in animation. [2] is the repeat count, where 0 means infinite.

0x80 — Get firmware version and device ID

Request: 80 00 00 00 00 00 00 00 . The device replies with a 0x80 report (see Responses). This is the recommended liveness and identity probe, and the only command that returns a reliable reply.

Responses (device to host)

0x42 — Command acknowledged

Sent after every set, fade, strobe, wave, and pattern command. Means received, not finished. Safe to ignore, or use as per-command backpressure when streaming.

0x00 0x01 — Effect finished

Pushed once a fade or a finite (non-zero repeat) effect fully settles. Infinite effects ( repeat = 0 ) never emit this. Use it to know when a one-shot effect is done. The device also sends it once at boot, after the power-on self-test blink settles.

0x80 — Firmware version and device ID

Reply to a 0x80 request.