Desktop app for two Framework Laptop 16 LED Matrix input modules — the 9×34 greyscale wells beside the keyboard.
Pick an animation for each side or play games. Built so someone who just bought the laptop can have a normal app in the menu.
Not an official Framework Computer product. MIT licensed.
- Framework Laptop 16
- at least 1 LED Matrix input module plugged in next to the keyboard
- Linux with Python 3.11+ (Omarchy, Arch, Fedora, Debian, Ubuntu all work)
- No pip packages. No
pyserial. The USB driver is the Python standard library.
This is my first app, so I hope you like it ;) Just got my first laptop that I own, and I'm so happy that it's the Framework 16!! I was encouraged by my wonderful uncle Stephon Lawrence to use Omarchy as my frist Linux OS. 100% don't regret listening to him!
Omarchy is a beautiful OS that is filled to the brim with features that my Mac and Windows brian could only dream of. And when paired with the Framework 16 its a AI work-horse!!
I am also going to admit that this App was vibe-coded along-side Cursor and Opencode.
Though Cursor did most of the heavy lifting, and Opencode did a lot of the terminal management, I am still proud of how close I programmed, edited, and promted the idea I had.
There is a time and place for AI, and I can confidently say, that this is where it belongs.(At least for me)
So you can definitely count on me using these tools to speed up my usual process in more of my projects in the future!
git clone https://github.com/Neotech3000/led-matrix.git
cd led-matrix
chmod +x install.sh uninstall.sh run
./install.shThe script:
- Puts
led-matrixon yourPATH(~/.local/bin) - Adds an LED Matrix entry to the app menu
- Asks for your password once to install a udev rule so the modules work without root
Then press Super (the logo key) and type LED Matrix. Or run:
led-matrixTo remove the menu entry and launcher (your clone stays on disk):
./uninstall.shgit clonecopies the project.cdmoves into that folder../install.shruns the installer.- If the app is “command not found”, open a new terminal so
~/.local/binis on yourPATH, or log out and back in. - If both wells stay dark and the pills say
permission denied, unplug the two LED modules and reseat them after the udev rule is installed.
- Click a well to send keyboard input there.
- Left-column cards run on the left well; right-column cards run on the right well.
- L / R badges on a card send that animation to either well.
- Brightness and speed sit in the top bar. Speed scales every animation (0.25×–2.5×).
- The Search box sits just left of Brightness. Type a name and both libraries filter to the best fuzzy matches (typos welcome —
clokfinds Clock); Tab or → accepts the ghost completion, Enter assigns the top hit to the focused well, Esc clears. Left column still feeds the left well and right column the right well. - Random shuffles both wells through the catalog. Each loop stays up for 10–30 seconds. Click a card to stop.
- The live preview stays in the middle; the first hundred loops are on the left, the rest on the right.
| Module | How to play |
|---|---|
| Flappy Bird | Click the well, press Space / W / ↑ to flap. Autopilot until you take over. Default: left. |
| Fish tank | Ambient loop. Default: right. |
| Snake | Tap a side of the well (left/right/up/down), or WASD / arrows. Auto-plays until you steer. |
| Pong | You are the bright bottom paddle. Drag anywhere on the well or use ← →. |
| Game of Life | Drag to paint live cells, Shift-drag to erase. R reseeds, P pauses. |
| Sketch | Drag on the well — one LED per pixel. Shift-drag erases. C clears. |
| Falling sand | Drag to pour sand. Shift-drag erases. C clears. |
| Breakout / Dodge | Drag or ← →. |
| Tetris | WASD or arrows. |
| Invaders | ← → to move, Space to shoot. |
| Dino run / Flappy | Click or Space. |
| Marquee | Type in the field under the well. Default text is FRAMEWORK. Letters enter at the top and loop down. |
| Clock | Local time: hours, minutes, then seconds, with a progress bar through the minute. |
| ECG | A scrolling EKG trace (no heart icon). |
| Hearts | Lots of falling hearts. |
There are 201 animations (Clock and Search arrived in v1.7.0). Click a well, then use the keyboard for games.
The app guesses sides from USB path order. Close it and run:
led-matrix --swapIf a module is mounted upside down:
led-matrix --flip-left
# or
led-matrix --flip-rightList what the computer can see:
led-matrix --listpython3 -m matrix_deck --simulate --host 127.0.0.1 --port 43173--simulate is for hacking on animations when the modules are not plugged in. On the laptop, omit it so the wells update for real.
./run --guiThe GUI binds to 127.0.0.1 so only your user can control the panels. Do not pass --host 0.0.0.0 on a shared network.
python3 -m unittest discover -s tests -vCI runs that on Python 3.11–3.13. See CONTRIBUTING.md to add an animation. Hardware protocol lives in matrix_deck/protocol.py; the serial driver is matrix_deck/hardware.py.
MIT.
0 comments
log in to comment.