fw16-led-matrixd
fw16-led-matrixd is an open-source, cross-platform daemon and CLI for controlling the Framework Laptop 16 LED Matrix Input Modules, developed by community member Sabrina Andersen (GitHub: NukingDragons). Written in Rust, it fully implements Framework's LED Matrix serial API and provides both a background daemon (fw16-led-matrixd) and a command-line client (ledcli) for scripting and automation1.
The project is notable for its pair mode, which treats two 9x34 LED matrix modules as a single unified 18x34 display, and its built-in keep-alive mechanism that prevents the modules from entering sleep1.
Background
The Framework Laptop 16 supports hot-swappable LED Matrix Input Modules — 9x34 (306 LED) monochrome displays driven by an RP2040 microcontroller communicating over USB ACM Serial at 115200 baud2. Framework provides official tools including a Rust CLI (inputmodule-control), a Python library, and a web-based drawing app, but none of these offer a persistent daemon with image rendering and animated GIF/APNG/WebP support3.
fw16-led-matrixd was created to fill this gap, providing a daemon that stays running in the background, a CLI that can render images and animations, and pair mode for unified dual-matrix display1.
Architecture
The project is organized as a Rust workspace with three crates1:
| Crate | Binary | Purpose |
|---|---|---|
daemon | fw16-led-matrixd | Background daemon that owns the serial connections |
client | ledcli | CLI tool that sends commands to the daemon over IPC |
shared | (library) | Shared types, IPC protocol, serial commands |
Communication between ledcli and the daemon uses Unix domain sockets (on Linux) with a newline-delimited JSON protocol via the interprocess crate1.
Features
Image & Animation Rendering
The ledcli render command supports static and animated images, automatically resizing and converting to grayscale for the LED matrix1:
| Format | Static | Animated |
|---|---|---|
| PNG | Yes | — |
| APNG | Yes | Yes |
| GIF | Yes | Yes |
| WebP | Yes | Yes |
| JPEG, BMP, TIFF, etc. | Yes | — |
Pair Mode
When two LED matrix modules are installed, pair mode combines them into a single 18x34 display. Images rendered in pair mode are resized to 18x34 pixels, with the left 9 columns sent to the left module and the right 9 columns to the right module1.
Patterns & Presets
Built-in patterns available through ledcli pattern1:
| Pattern | Flag |
|---|---|
| Percentage fill (0–255) | --percentage |
| Gradient | --gradient |
| Double gradient | --double-gradient |
| "LOTUS" horizontal | --lotus-horizontal |
| "LOTUS" vertical | --lotus-vertical |
| Zigzag | --zigzag |
| All LEDs on (full bright) | --fullbright |
| "PANIC" text | --panic |
Keep-Alive
A background thread polls each non-sleeping matrix every 45 seconds by reading the firmware version, preventing the modules from entering their idle sleep timeout1.
CLI Reference
The ledcli client exposes the following subcommands1:
| Command | Description |
|---|---|
list | List all connected LED matrices |
render | Render an image, GIF, APNG, or raw bytes |
brightness | Get or set brightness (0–255) |
pattern | Display a built-in pattern |
sleep | Get or set sleep state |
animate | Get or set vertical scroll animation |
stage-col | Stage a single column of pixel values |
flush-cols | Flush staged columns and render |
draw-bw | Draw a 1-bit black-and-white bitmap (39 bytes) |
version | Query the module's firmware version |
bootloader | Enter bootloader mode |
crash | Force a panic on the module (debug) |
Most commands accept --matrix with values left, right, or both. The render and stage-col commands additionally support pair1.
Installation
Arch Linux (AUR)
Two packages are available in the AUR4:
yay -S fw16-led-matrixd # release version
yay -S fw16-led-matrixd-git # git HEAD
The Arch package includes a systemd service unit (fw16-led-matrixd.service)14.
Debian / Ubuntu
An apt repository is provided with a one-line installer1:
curl -fsSL https://nukingdragons.github.io/fw16-led-matrixd/deb.sh | bash
Windows
A PowerShell installer creates a Windows service and adds ledcli to the system PATH1:
irm https://nukingdragons.github.io/fw16-led-matrixd/win.ps1 | iex
Configuration
The daemon reads a TOML config file defining the serial port for each matrix1:
Linux (/etc/fw16-led-matrixd/config.toml):
[left_matrix]
port = "/dev/ttyACM1"
baudrate = 115200
sleeping = false
[right_matrix]
port = "/dev/ttyACM0"
baudrate = 115200
sleeping = false
Windows (C:\Program Files\fw16-led-matrixd\config.toml): same format with COM3/COM4 ports.
Technical Details
| Detail | Value |
|---|---|
| Language | Rust (2021 edition) |
| License | MIT |
| IPC | Unix domain sockets (newline-delimited JSON) |
| Serial protocol | Magic bytes 0x32 0xAC + command byte + parameters |
| USB VID | 0x32AC |
| USB PID | 0x20, 0x1F |
| Matrix resolution | 9x34 (306 LEDs) per module |
| Pair resolution | 18x34 (612 LEDs) |
| Baud rate | 115200 (configurable) |
| Log rotation | 10 MB max, 10 files retained (log4rs) |
| Linux daemon | Double-fork SysV-style with PID file at /run/fw16-led-matrixd.pid |
| Windows daemon | Windows Service via windows-service crate |
Related Projects
| Project | Description |
|---|---|
| inputmodule-rs | Official Framework firmware + CLI + Python tools3 |
| led-matrix-manager | Qt GUI for LED matrix management |
| led_matrix_daemon | Alternative Rust daemon with HTTP API5 |
| fw16-ledvu | PipeWire/CAVA audio visualizer for the LED matrix |
| FW_LED_Matrix_Firmware | Alternative Arduino firmware with full 256 brightness levels |