[App][Pro] iDotMatrix — BLE pixel display

Apps
1

Hi everyone,

I’d like to share an early test release of an **iDotMatrix** integration for Homey Pro. iDotMatrix displays are cheap BLE pixel matrices (16×16, 32×32, 64×64) commonly sold on Amazon / AliExpress under names like “Divoom-style pixel display”. This app talks to them directly over Bluetooth Low Energy — no cloud, no vendor app, no account.

The protocol is ported from the excellent [python3-idotmatrix-library]( GitHub - derkalle4/python3-idotmatrix-library: This library talks to displays originally used with the iDotMatrix Android & iOS App. · GitHub ) by @derkalle4 and verified byte-for-byte against real hardware.

## Features

- **Capabilities**: On/Off, Brightness (5–100 %)

- **Flow actions**:

  • Show text (9 animation modes, color, speed)

  • Show clock (8 styles, color, date, 12/24h)

  • Countdown (start / pause / restart / disable)

  • Scoreboard (two 3-digit counters)

  • Chronograph (stopwatch)

  • Show image from URL (PNG / JPG / BMP / GIF — auto-detected)

  • Show image from a remote HTTP server on your LAN (nginx autoindex, Apache, Python `http.server`, or `index.json`)

  • Show image from the app’s built-in media store (POST endpoint for uploads)

  • Probe device capabilities (diagnostic dump to device settings)

- **Animated GIFs** are auto-resized to the display resolution frame-by-frame with nearest-neighbor scaling (preserves pixel-art crispness).

## Requirements

- **Homey Pro** (2023 or Early 2019) — Bluetooth Low Energy required

- Any iDotMatrix display advertising as `IDM-*`

Homey Bridge / Homey Cloud are **not supported** — they don’t have BLE.

## Install (test build)

:backhand_index_pointing_right: ** iDotMatrix | Homey**

Open that link on a phone or computer signed in to the same Homey, then *Install Test Version*.

## How to use

1. Add device → iDotMatrix Display → pick your `IDM-XXXXXX` from the list

2. On/Off and Brightness work straight from the device card

3. Build Flows around the actions listed above

4. For remote-server image hosting: open device settings → *Remote media server* → enter a URL like `http://192.168.1.50:8080/idotmatrix/\` (any directory listing works)

5. The first thing I recommend is running *Probe device capabilities* — it writes a full JSON diagnostic to your device settings so you (and I) can see exactly what your firmware supports

## Known limitations

- Built-in text font is intentionally minimal (5×7, uppercase + digits) — if you need a richer font, pass your own via `IDMProtocol.buildText(opts.font)`

- Notification ACKs are received but not yet gated against (writes are fire-and-forget); should be reliable in practice but image uploads can take a few seconds

- The secondary BLE service `0x00AE` advertised by the display is undocumented and currently unused — Probe lists it for future reverse engineering

- Image / GIF Flow cards take up to a few seconds — they run asynchronously so Homey doesn’t time-out, but the display updates after the upload finishes, not immediately

## Source & license

- **Source**: GitHub - fbnlrz/homeyidotmatrix · GitHub

- **License**: Unlicense (public domain — fork / modify / sell / do whatever)

- Built using [Claude Code]( Claude Code by Anthropic | AI Coding Agent, Terminal, IDE ) with the [dvflw/homey-app-skill]( GitHub - dvflw/homey-app-skill · GitHub ) Homey development skill by @mmcnees

## Feedback please

This is a v0.1.x — I’d love bug reports, especially:

- Pairing / discovery on firmware revisions I haven’t tested

- ACK byte sequences from *Probe device capabilities* for non-32×32 devices

- Anything you’d like as a Flow action that’s not there yet

Cheers!

2

Hi! I see you have the readme in multiple languages in a single file. Did you know that you can also create separate files for each language (README.txt for English (and all languages for which you don’t have separate files), README.de.txt for German and README.nl.txt for Dutch)? The Homey App Store automatically selects the correct version based on the user’s language

3

Hi! no i didnt knew that i will do that immediately! Thank you! :slight_smile:

4

Done :slight_smile:

5

Homey Cloud/Homey Bridge certainly have BLE, f.e. the MIPOW and Mi Flora apps are supported there. However, Homey Cloud does not support community apps, only official (= developed by brand, agencies or Athom) apps are allowed. There’s no technical limitations that block the use on Homey Cloud, only a software limitation that only allows official apps. In fact, I once built a service that allowed people to run community apps on Homey Cloud, which proves that it is possible to install community apps on Homey Cloud using some reverse engineered CLI communications. However, Athom didn’t like it and I had to take it down unfortunately.

6

Fix for repeated BLE connection failures on Homey Early 2019 — iDotMatrix v1.0.2

Hi! Thanks for developing this app. I encountered repeated connection failures on my Homey Early 2019 and found two small changes that allowed the app to connect.

My setup:

  • Homey Early 2019, firmware 13.5.1

  • iDotMatrix app v1.0.2

  • 32×32 display, MCU version 4.15

  • Display advertised as IDM-*

  • Bluetooth on my phone disabled during testing

The display repeatedly flashed its connection icon, while Homey reported it as unavailable. Sending scrolling text manually through Homey Developer Tools worked.

Both changes below are in lib/IDMClient.js.

1. Normalize short UUIDs with omitted leading zeros

The first error was:

iDotMatrix service 00fa not found. Discovered: 1800, fa, ae00

Homey reported the service as fa, while the app expected 00fa. The BLE connection succeeded, but the app then disconnected because it could not match the service.

Replace:

function _normalizeUuid(u) {
  return String(u || '').toLowerCase().replace(/-/g, '');
}

with:

function _normalizeUuid(u) {
  return String(u || '').toLowerCase().replace(/-/g, '').padStart(4, '0');
}

This is the minimal workaround tested on my setup: fa becomes 00fa, while longer UUIDs retain their length.

2. Retrieve characteristics directly through the Homey SDK

After the first change, the service was recognized, but the next error was:

Write characteristic fa02 not found on iDotMatrix service

Inside _doConnect(), replace:

const writeChar = _findChar(service, IDMProtocol.WRITE_SHORT_UUID);
const notifyChar = _findChar(service, IDMProtocol.NOTIFY_SHORT_UUID);

with:

const writeChar = await service.getCharacteristic(IDMProtocol.WRITE_SHORT_UUID);
const notifyChar = await service.getCharacteristic(IDMProtocol.NOTIFY_SHORT_UUID).catch(() => null);

The original lookup through service.characteristics did not find FA02 on my setup. Calling getCharacteristic() directly resolved it. I have not established why the original lookup failed.

Result

After saving both changes and running:

homey app run --remote

the log showed:

[ble] connected
Connected to iDotMatrix

For a persistent local installation:

homey app install

These changes restored the app’s BLE connection on my setup. I have not yet verified all Flow actions, image uploads, or long-term connection stability. The optional FA03 fallback also does not guarantee that features relying on notifications will work without it.

Hopefully this helps other users with the same errors, and gives the developer a reproducible case for an upstream fix. An App Store update may overwrite these local changes.