Skip to main content

LED Matrix Controllers

LED Matrix Controllers is a JavaScript/TypeScript library providing cross-firmware controllers for the Framework Laptop 16 LED Matrix Input Module, developed by Jacob Padgett (GitHub: jpadgett314)1. The library abstracts the differences between three LED matrix firmwares — the official Framework firmware, sparkle-fw16, and sigroot's firmware — behind a unified API using the WebHID and Web Serial APIs1.

The library is available on npm and via CDN (esm.sh), and is the same author's companion to the LED Matrix Vocab project12.

Supported Firmwares​

The library supports three LED matrix firmwares1:

FirmwareRepositoryInterface
Official (default)FrameworkComputer/inputmodule-rsWeb Serial1
sparkle-fw16vddCore/sparkle-fw16WebHID1
sigrootsigroot/FW_LED_Matrix_FirmwareWeb Serial1

API​

Firmware-Specific Controllers​

The library provides dedicated controller classes for each firmware1:

import { DefaultController, SigrootController, SparkleController } from 'led-matrix-controllers';

const controller = new DefaultController();
await controller.connect();
await controller.draw( /* 34x9 array of arrays of 0 to 1.0 */ );

Hardware Controller Factory​

A HardwareControllerFactory provides auto-detection for serial and HID devices, abstracting away the firmware selection1:

import { HardwareControllerFactory } from 'led-matrix-controllers';

const serialController = await HardwareControllerFactory.detectSerial();
const hidController = await HardwareControllerFactory.detectHID();

Web Worker Support​

As of December 2025, the library supports Web Workers, allowing LED matrix communication to continue running when the browser tab is inactive (avoiding throttling)3. The requestPortForWorker and requestDeviceForWorker functions establish permissions outside the Web Worker for use within it3.

Hardware Constants​

The library uses the following USB identifiers to detect Framework LED Matrix modules4:

ConstantValue
VID (Vendor ID)0x32AC4
PID (Product ID)0x00204
Display width9 LEDs4
Display height34 LEDs4

A gamma correction table is included for PWM dimming (not for analog dimming/constant-current reduction)4.

Installation​

Node.js​

npm install led-matrix-controllers

Requires Node.js v18 or later1.

CDN (esm.sh)​

<script type="importmap">
    {
        "imports": {
            "led-matrix-controllers": "https://esm.sh/led-matrix-controllers@latest"
        }
    }
</script>

Technical Specifications​

SpecificationDetails
LanguageJavaScript / TypeScript1
Packageled-matrix-controllers (npm)1
APIsWebHID, Web Serial1
Node.jsv18+1
FirmwaresOfficial, sparkle-fw16, sigroot1
Web WorkerSupported (since December 2025)3
LicenseNot specified1
GitHub Stars11
Sourcejpadgett314/led-matrix-controllers (GitHub)1
ProjectDescription
LED Matrix VocabJapanese vocabulary study tool by the same author (jpadgett314)
sparkle-fw16C-based alternative firmware supported by this library
sigroot FW LED Matrix FirmwareArduino-based alternative firmware supported by this library
led-matrix-managerQt GUI for LED matrix management
fw16-led-matrixdCross-platform Rust daemon for the LED matrix
LED Matrix MonitoringSystem metrics visualization for the LED matrix

Footnotes​

  1. jpadgett314/led-matrix-controllers — GitHub (README, API documentation, installation) ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13 ↩14 ↩15 ↩16 ↩17 ↩18

  2. jpadgett314/led-matrix-vocab — GitHub (companion project by the same author) ↩

  3. feat: web worker support — commit 5f856c0 — GitHub (jpadgett314, December 9, 2025) ↩ ↩2 ↩3

  4. led-matrix-vocab commit a35f4a2 — bundled source — GitHub (hardware-constants.js: VID, PID, gamma table) ↩ ↩2 ↩3 ↩4 ↩5 ↩6