CoolLEDUX Controller

The problem

The sign is a CoolLEDUX 16x96 full-color RGB LED matrix that talks Bluetooth Low Energy and normally runs from its stock Android app. I wanted it on my own terms: scriptable, reachable over HTTP, and wired into Home Assistant.

An existing community Python SDK was the obvious starting point, but its command codes were wrong for this firmware. So the decompiled stock app became the source of truth, and every command, checksum and frame format was checked against it (and against the real sign wherever possible) before it went into the Go code.

What the protocol turned out to be

• Packet framing - every packet to or from the sign uses the same stream frame: a start byte, a 2-byte big-endian length, the escaped payload, and an end byte. Any 0x01, 0x02 or 0x03 inside the length or payload is escaped as 0x02 followed by the byte XOR 0x04.
• CRC32 - program uploads carry a CRC32 (polynomial 0x4C11DB7, initial value 0xFFFFFFFF, no final XOR), computed bitwise the way the stock app does it.
• LZSS + stream framing - program data is LZSS-compressed and split into data chunks, with compression and stream framing that match the stock app.
• Images - pictures and GIF frames are encoded as RGB444, column-major.
• Color presets - uploading text as a content type 0x05 composite program unlocks the 28 auto-color text presets (rainbow, gradient, multi-color) that a plain text upload never reaches.

The frame, from the public BLE protocol spec:

[0x01] [length:2 BE] [escaped(payload)] [0x03]
  |         |               |              |
  |         |               |              +-- end byte (never escaped)
  |         +---------------+----------------- escaped together:
  |                                            0x01/0x02/0x03 -> [0x02, B ^ 0x04]
  +-------------------------------------------- start byte (never escaped)

payload = [command:1] [args...]   e.g. 0x04 brightness, 0x05 power

What the Go service does

• BLE scan, connect, MTU negotiation and reconnect
• A REST API for power, brightness, text, images, GIFs and program upload
• Countdown, stopwatch and scoreboard overlays
• Image and GIF sprite placement with letterbox, stretch and cover fit modes
• Three bitmap fonts: Plan 9 7x13, X11 Misc Fixed Bold 7x14b, and Spleen 8x16
• MQTT with Home Assistant auto-discovery (a light and a binary_sensor entity)
• An OpenAPI 3.1 spec with Swagger UI (Apr 2026)
• Runs in Docker on Linux/BlueZ

An honest gotcha

For a while the scoreboard looked broken: the sign ACKed every scoreboard command and showed nothing. The sign is very polite about ignoring you. The control commands only do something once the scoreboard's composite program (content type 0x0B) has been uploaded, so the fix was building that program the way the stock app does, after which it renders on the 16x96 panel.

Even then the clock is picky. A new time only latches while the clock is stopped, so changing it means stop, set, start. Scores update immediately either way.

Links

• coolledux-controller on GitHub
• BLE protocol spec
• REST API spec
• MQTT / Home Assistant spec