Framework LED Matrix Python Tool
Framework LED Matrix Python Tool is a Python command-line suite for the Framework Laptop 16 LED Matrix modules, developed by community member mariobx (with contributions from mariom6). It was created for programming novices to run "cool simulations" and visual experiments on the dual 9×34 LED matrix beyond the simple boot animations, after the author was surprised by the lack of available tooling at the time of purchase1. The project is licensed under GPL-3.01.
The core/ directory defines a simplified API for interacting with the LED functions — the path of the modules, sending both greyscale and regular payloads, and clearing the matrices — which the higher-level simulation and text commands build on1.
Capabilities
The suite runs a variety of visual experiments1:
| Category | Description |
|---|
| Anagrams & Text | Anagrams of random words gliding across the screen; custom text rendered vertically and horizontally |
| Cellular Automata | Conway's Game of Life, Biham-Middleton-Levine (BML) traffic model, Hardy-Pomeau-Pazzis (HPP) lattice gas collisions |
| Mathematical Visualizations | Plot functions like sin, cos, exp, tanh directly onto the matrix |
| Hybrid Simulations | Seed Game of Life or HPP simulations using math graphs or anagrammed text as the initial state |
| Noise & Hardware Effects | Hardware-level greyscale noise and control of internal hardware animations |
Command Reference
background (aliases: bg)
Run the background runner (screensaver mode)1.
led
| Subcommand | Description |
|---|
version | Get firmware version from modules |
clear | Clear both displays (all LEDs off) |
fill [--hold <s>] | Fill the display, holding for N seconds |
start-anim | Start hardware animation (e.g. fades) |
stop-anim | Stop hardware animation |
reset | Clear display and stop animation |
ports | Show available serial ports (debugging) |
text
| Subcommand | Description |
|---|
vertical <text> | Render text vertically (options: --font-size, --which left|right|both, --row-offset, --hold) |
horizontal <text> | Render text horizontally (options: --font-size, --which, --x-offset, --y-offset, --hold) |
anagram
| Subcommand | Description |
|---|
draw <word> | Find and draw anagrams for a word (--which, --no-animate) |
sim
| Subcommand | Description |
|---|
bml | Biham-Middleton-Levine traffic model (--density, --steps, --delay) |
bml-local | BML traffic model in a local Matplotlib window |
hpp | Hardy-Pomeau-Pazzis lattice gas (--density, --steps, --delay, --which) |
hpp-math | HPP simulation seeded with math function graphs |
outer | Generic Outer-Totalistic CA using Birth/Survival rules (--b-rule, --s-rule) |
gof | Conway's Game of Life (B3/S23) — --board random|glider|acorn |
inner | Inner-Totalistic CA, Wolfram NKS style (rule number argument) |
random-grey | Hardware-level greyscale noise (--duration, --no-animate) |
anagram-gof | Game of Life seeded with anagrammed text |
anagram-draw | Sequentially find and draw anagrams for random words |
math-gof | Game of Life seeded with math graphs |
math-graphs | Cycling sequence of random math graphs |
math
| Subcommand | Description |
|---|
plot <function> | Plot a function locally and on the matrix (sin, cos, tan, exp, log, tanh, etc.) |
A global -v, --verbose flag enables detailed logging for all commands, and frameworkled --test runs a built-in test suite cycling through various commands to verify hardware and software functionality1.
Technical Details
| Detail | Value |
|---|
| Language | Python1 |
| License | GPL-3.01 |
| Hardware | Framework 16 LED Matrix modules (RP2040 + IS31FL3741A) |
| Output | Grayscale PWM and black-and-white bitmaps |
| Dependencies | Matplotlib (local simulations) |
| Contributors | 2 (mariobx, mariom6)1 |
| Commits | 26+1 |
| Stars | 11 |
| Created | January 24, 20261 |