Omahub
← All plugins
S

Framework LED Matrix Helper

by Steve Godlewski

Control center for Framework 16 LED Matrix panels: preview patterns, text, animations, and effects on a live emulation of both panels before applying them, draw your own patterns in a pixel-art editor with a shareable PNG library, and manage per-panel power and firmware updates

GitHub

Security review

Review recommended · 3 findings

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
0bb5911
Scanned
1 month ago
  • low obfuscation bin/led-matrix-png:73

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n"
  • low obfuscation bin/led-matrix-png:131

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n":
  • low obfuscation bin/led-matrix-bounce:51

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n" + c(b"IHDR", struct.pack(">IIBBBBB", W, H, 8, 0, 0, 0, 0)) + c(b"IDAT", zlib.compress(raw)) + c(b"IEND", b"")

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
0bb5911
Reviewed
1 month ago

No malicious or hidden behavior was found. The deterministic scan's 'obfuscation' findings are false positives: the hex escapes are the standard PNG signature used to generate pattern images. The only elevated actions, installing an AUR dependency via yay and flashing firmware, are explicitly user-initiated, clearly documented, and the firmware path is validated against an allowlist of SHA-256 hashes before anything is written.

  • The flagged \x89PNG\r\n\x1a\n sequences in bin/led-matrix-png and bin/led-matrix-bounce are legitimate PNG file signatures, not obfuscated code.
  • The plugin can launch yay to install inputmodule-control from the AUR, but only after the user clicks an explicit install button and the command is shown in a terminal.
  • Firmware flashing can modify device firmware, but it requires a user-selected .uf2 file and the image is structurally validated and checked against published release hashes before flashing.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/godlewski/omarchy-framework-led-matrix-helper --enable
Hardware #bar

Framework LED Matrix Helper

A control center for the Framework 16 LED Matrix input modules, living in the Omarchy bar. Everything you set — patterns, text, animations, effects — shows on a live emulation of both panels first, so you see exactly what you'll get before applying it to the hardware. A built-in pixel-art editor lets you draw, save, and share your own patterns as plain PNGs. Rounded out with per-panel power and identity, full keyboard navigation, and in-place firmware updates.

Category: Hardware

Controls Editor Panels
Controls tab — live preview of both panels with a staged pattern Editor tab — pixel-art pattern editor Panels tab — identity, side assignment, firmware

Features

  • Live panel preview — an emulation of both LED matrices in the popup renders every choice before it touches hardware: patterns, text (including how it splits across panels), animations ticking live, effects pulsing, brightness and sleep state. Selections show on the preview first; Apply sends them to the panels, Revert (or x) discards.
  • Display picker — firmware patterns (logo, gradients, lotus, zigzag, all-on), free text, and streaming animations (clock, random EQ, mic EQ, bouncing Omarchy logo). One picker, because exactly one thing owns the grid at a time.
  • Effects — breathing/blinking brightness modulation that composes with any static display, and is automatically unavailable while a streaming animation owns the grid.
  • Per-panel targeting — control both panels or just the left/right one; text longer than 5 characters spans across both panels. Each panel has its own on/off switch under its preview (implemented as brightness-0 so running animations on the other panel are undisturbed).
  • Text positioning — nudge text pixel-by-pixel within the panel bounds (arrow buttons, or Enter on the Position row for an hjkl/arrow nudge mode); shifted text is sent as rendered frames using the firmware's own font.
  • Stable left/right identity — panels enumerate in random order per boot; assign each USB port a side once (with a brightness-pulse Identify helper) and the plugin keeps the order correct automatically.
  • Pattern editor — draw your own 9×34 patterns on an Editor tab: click to toggle, drag to paint, or a keyboard draw mode (hjkl/arrows + Space). Send to the panels directly, optionally live-painting as you draw. Save patterns by name — they appear in the Display picker as ★ name and are stored as plain 9×34 PNGs in ~/.local/share/godlewski.framework-led-matrix-helper/patterns/, directly usable with inputmodule-control --image-bw — exporting/sharing a pattern is just copying the file. Importing works too: the Import PNG… button opens the desktop file chooser and accepts any 9×34 PNG (grayscale, RGB, palette, or alpha — drawn in any editor); dropping files into the patterns folder or bin/led-matrix-ctl import-pattern <file> [name] work as well.
  • Firmware flashing — download a .uf2 from Framework's official releases (a button opens the page), pick the file, and the plugin flashes it in place (RP2040 UF2 flow) with streamed progress. The plugin never fetches or chooses firmware itself. Before anything touches the bootloader the image is read once from a regular file (bounded, no symlinks/FIFOs), structurally validated (UF2 block magics, RP2040 family ID), and its SHA-256 checked against Framework's published v0.2.0 ledmatrix images (standard, EVT, 10k) — a crafted RP2040 image with the right headers is still refused. Custom-built firmware is out of scope for the plugin; copy it to the RPI-RP2 drive yourself.
  • Stays lit — the firmware normally fades panels out 60 seconds after the last command, so static patterns would vanish; the widget keeps what you applied visible with a lightweight keepalive (sleeping panels via the power switch still saves power as before).
  • Bar conveniences — scroll the bar icon to change brightness, right-click to sleep/wake, full keyboard navigation (j/k/h/l, Enter, Esc, Tab) matching the first-party Omarchy panels.

Requirements

  • Framework 16 with one or two LED Matrix input modules
  • inputmodule-control (AUR), plus python3 (in the Omarchy base install)

Missing something? The widget guides you. When a dependency is absent the bar icon shows a setup state whose panel explains what's missing and offers an Install dependencies button (runs yay in an Omarchy floating terminal). Manual equivalent: yay -S inputmodule-control. If serial access is denied on your setup, also install inputmodule-udev from the AUR.

Install

omarchy plugin add https://github.com/godlewski/omarchy-framework-led-matrix-helper --enable

Or clone into ~/.config/omarchy/plugins/godlewski.framework-led-matrix-helper and run omarchy plugin enable godlewski.framework-led-matrix-helper.

Usage

Click the bar icon (or omarchy-shell shell toggle godlewski.framework-led-matrix-helper) to open the panel.

  • Controls tab — pick the target panel(s), set brightness, choose what to display, and add a breathing/blinking effect.
  • Panels tab — identify which physical panel is which, assign Left/Right to their USB ports, and update firmware.

IPC

omarchy-shell godlewski.framework-led-matrix-helper toggle|open|close|sleep|wake|refresh

Useful for keybindings, e.g. sleeping the panels before a presentation.

Settings

Stored in the widget's ~/.config/omarchy/shell.json entry (managed from the Panels tab; no manual editing needed): leftPort / rightPort (USB port paths for side identity) and swapped (derived automatically once ports are assigned).

Removal

omarchy plugin remove godlewski.framework-led-matrix-helper

State/caches you may also delete: ~/.local/state/godlewski.framework-led-matrix-helper/, ~/.cache/godlewski.framework-led-matrix-helper/.

Development

Agent/contributor docs live in CLAUDE.md, with deeper references in .claude/skills/ (shell UI kit, hardware/CLI semantics, dev loop).

Credits

The panel emulation embeds the 5×6 pixel font, lotus bitmap, and pattern algorithms from Framework's inputmodule-rs (MIT © Framework Computer Inc), which also provides the inputmodule-control CLI and firmware this plugin drives. The bouncing-logo animation and logo bitmap are ported from Omarchy (MIT).

License

MIT