idotmatrix

TypeScript BLE client for iDotMatrix pixel displays (16x16, 32x32, 64x64).

Based on the protocol work from the Python iDotMatrix API client.

Installation

npm install idotmatrix

Prerequisites: This library uses @abandonware/noble for BLE communication. See noble's prerequisites for platform-specific setup (e.g. Xcode command-line tools on macOS, libbluetooth-dev on Linux).

Quick Start

import { IDotMatrix, ScreenSize, discover } from "idotmatrix";

// Find nearby devices
const devices = await discover(5_000);
console.log(devices); // [{ address, id, name: "IDM-XXXX" }]

// Send pixels to a 64x64 display
const matrix = new IDotMatrix({
  address: devices[0].id, // CoreBluetooth UUID on macOS, MAC on Linux
  screenSize: ScreenSize.S64,
});

// Create a red frame: 64*64*3 = 12288 bytes of raw RGB
const rgbData = new Uint8Array(matrix.rgbDataLength);
for (let i = 0; i < rgbData.length; i += 3) {
  rgbData[i] = 255; // R
}

const result = await matrix.sendPixelsOnce(rgbData);
console.log(result); // { success: true }

API

discover(timeoutMs?: number): Promise<DeviceInfo[]>

Scan for nearby iDotMatrix devices. Returns devices whose BLE advertisement name starts with IDM-.

interface DeviceInfo {
  address: string; // BLE address (empty on macOS)
  id: string;      // Platform-specific identifier (CoreBluetooth UUID on macOS)
  name: string;    // Advertisement name, e.g. "IDM-E621AD"
}

new IDotMatrix(options: ClientOptions)

interface ClientOptions {
  address: string;          // Device address (MAC on Linux, CoreBluetooth UUID on macOS)
  screenSize?: ScreenSize;  // Default: ScreenSize.S64
  scanTimeoutMs?: number;   // Default: 10000
}

enum ScreenSize {
  S16 = 16,
  S32 = 32,
  S64 = 64,
}

Instance Properties

Property	Type	Description
connected	boolean	Whether the device is currently connected
rgbDataLength	number	Expected byte count for one frame (screenSize * screenSize * 3)

Instance Methods

connect(): Promise<void>

Connect to the device and hold the connection open for reuse. Called automatically by sendPixels() if not already connected.

disconnect(): Promise<void>

Disconnect from the device.

sendPixels(rgbData: Uint8Array): Promise<SendResult>

Send raw RGB pixel data. Auto-connects if needed, stays connected after sending.

sendPixelsOnce(rgbData: Uint8Array): Promise<SendResult>

Send raw RGB pixel data then disconnect. Convenient for one-shot sends.

interface SendResult {
  success: boolean;
  error?: string;
}

Pixel Format

Pixels are raw RGB bytes in row-major order (top-left to bottom-right). Each pixel is 3 bytes: [R, G, B], values 0-255.

For a 64x64 display, the buffer is 12,288 bytes. To set pixel at (x, y):

const i = (y * screenSize + x) * 3;
buffer[i]     = r;
buffer[i + 1] = g;
buffer[i + 2] = b;

macOS Notes

• On macOS, peripheral.address is empty. Use peripheral.id (CoreBluetooth UUID) as the device address.
• Noble may return short UUIDs (e.g. fa02) during characteristic discovery. This library handles UUID normalization internally.

License

GPL-3.0 - See LICENSE for details.