led-matrix

KO | EN

gitlite — search

#react #ai #golang #go #android #rust #linux #docker #nodejs #cli #awesome-list #pytorch #mcp #openai

(★ 9)

System Monitor display for Framework 16 LED Matrix input module

led-matrix Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Framework 16 LED Matrix System Monitoring Application

This software is intended for use on a Framework 16 laptop with LED Matrix Panels installed. It's based on the [LED System Monitor](https://code.karsttech.com/jeremy/FW_LED_System_Monitor.git) project, with extensive modifications and extensions applied.

## Compatibility

**Hardware:** Framework 16 laptops with LED Matrix Panels  
**Operating Systems:** Linux distributions (Ubuntu, Fedora, NixOS, Debian, CentOS, RHEL, and others)  
**Dependencies:** Python 3.7+ with numerous PyPi depednenceies (see requirements.txt)

## Quick Start (install the app and run it as a service)

For most users, the fastest way to get started. This installs dependencies, builds the app, installs it as a service, and starts the service:

```bash
# Clone the repository
git clone <repository-url>
cd led-matrix

# Run with automatic dependency installation
chmod +x build_and_install.sh
./build_and_install.sh
./dist/led_mon/led_mon #optionally run manually
```

The `build_and_install.sh` script will automatically detect your Linux distribution, install the required dependencies, build an executable file of the python application, and install it as a user-level systemd service fwledmonitor.service.

## Capabilities
* Display system performance characteristics in real-time
  * CPU utilization
  * Battery charge level and plug status + memory utilization
  * Disk Input/Output rates 
  * Network Upload/Download rates
  * Temperature sensor readings
  * Fan speeds
* Other apps
  * Current weather or weather forecast
  * Time
  * Display patterns saved in snapshot json files
  * Equalizer visualization of current audio source
* Display any system monitoring app on any quadrant
  * Top or bottom of left or right panel
  * Assign multiple apps to any quadrant and cycle throiugh them at specified time intervals
  * Turn on animation and define command arguments for apps
  * Specified via a yaml config file
* Keyboard shortcut `ALT` + `I` identifies apps running in each quadrant by displaying abbreviated name
* Keyboard shortcut `ALT` + `N` forces the display of the next widget, without waiting for the time slice to complete
* Keyboard shortcut `ALT` + `F` freezes app switching, cuasing the current widget to be displayed indefinitely
* Keyboard shortcut `ALT` + `U` unfreezes app switching
* Plugin framework supports simplified development of addiitonal LED Panel applications
* Automatic detection of left and right LED panels
* Automatic detection of keyboard device (for keyboard shortcut use)

## Important note about Python environments
[Pep 668](https://peps.python.org/pep-0668/) provides a mechanism for a Python installation to communicate to tools such as Pip that the installation is externally managed. For Python installations that implement this notification, an attempt to install a package in the global context will be denied, with a message that the installation is externally managed. There are ways to override the PEP 668 constraint (such as using pipx or the --break-system-packages flag). The standard solution, however, is to use a Python Virtual Environment.

The build and installation instructions and scripts for this project assume that every Python installation action is done in a virtual environment. If you want to perform a global installation, it's up to you to make whatever changes are needed to make that work. Also, please note that a misconfigured virtual environment will result in either build-time or run-time failures. See installation notes below for instructions. In general, you should 1) Install package dependencies for the selected virtual environment tool 2) Install the tool 3) Configure the tool per instructions provided by the tool provider 3) Create a virtual environment and activate it 4) Ensure that the virtual environment is currently activated in any shell from which you perform a Python installation, whether launching python directly or invoking a build or installation script. The error message `python: command not found` is a likely indicator of a missing or misconfigured virtual environment.

## Plugins
Application capabilities can be extended by including plugins. See `plugins/plugins-README.md` for more info. See the plugin configuration near the bottom of this page for plugin-specific configuration instructions.

## Manual Installation (run the app from the command line in the foreground)

Install [PyEnv](https://github.com/pyenv/pyenv) or any other python virtual environment package (Commands below work with PyEnv)
### For Ubuntu/Debian users:
```bash
sudo apt update
sudo apt install -y python3-numpy python3-psutil python3-serial python3-evdev python3-pynput python3-yaml python3-pip
cd led-matrix-monitoring
pyenv install 3.11 # or higher (tested up to 3.14)
pyenv virtualenv 3.11 led-matrix-env
pyenv activate led-matrix-env
python -m pip install -r requirements.txt
python -m led_mon.led_system_monitor
```

### For Fedora users:
```bash
sudo dnf install -y python3-numpy python3-psutil python3-pyserial python3-evdev python3-pynput python3-pyyaml python3-pip
cd led-matrix-monitoring\
pyenv install 3.11 # or higher (tested up to 3.14)
pyenv virtualenv 3.11 led-matrix-env
pyenv activate led-matrix-env
python -m pip install -r requirements.txt
python -m led_mon.led_system_monitor
```

### For NixOS users:
```bash
# Using the Nix flake (recommended)
nix run github:timoteuszelle/led-matrix/main

# Or build locally
nix build
./result/bin/led-matrix-monitor
```

### NixOS System Integration
For NixOS users who want to run LED matrix monitoring as a system service, use the standalone module from this repository.

**1. Add flake input:**
```nix
{
  inputs = {
    # ... other inputs
    led-matrix-monitoring.url = "github:timoteuszelle/led-matrix/main";
  };
}
```

**2. Import module:**
```nix
{
  imports = [
    inputs.led-matrix-monitoring.nixosModules.led-matrix-monitoring
    # or: inputs.led-matrix-monitoring.nixosModules.ledmatrixmonitoring
  ];
}
```

**3. Configure service (recommended Nix-native schema):**
```nix
services.led-matrix-monitoring = {
  enable = true;
  configurationMode = "nix-module"; # linuxOS | nix-flake | nix-module

layout = {
    duration = 10;
    quadrants = {
      topLeft = [{ name = "cpu"; }];
      bottomLeft = [{ name = "mem-bat"; }];
      topRight = [{ name = "disk"; }];
      bottomRight = [{ name = "net"; }];
    };
  };

# Optional for graphical sessions:
  # environment.DISPLAY = ":0";
};
```

**4. Rebuild your system:**
```bash
sudo nixos-rebuild switch
```

**Troubleshooting NixOS Service Issues:**
```bash
systemctl status led-matrix-monitoring
journalctl -u led-matrix-monitoring -f
```

For a full module option reference (including `configurationMode`, config-source compatibility, runtime/service options, and layout app fields), see `README-NIXOS.md`.

**Alternative: Systemd Service (Advanced)**

For automated continuous execution, you can run as a systemd service instead:

```bash
# The service runs as a user-level systemd service under the logged in user's account
./build_and_install.sh
# manage the service
systemctl --user start|stop|status fwledmonitor.service
# The service config file is at ~/.config/systemd/user/fwledmonitor.service.
# The service executable is at /opt/led_mon/led_mon (sym-linked to /usr/local/bin/led_mon)
```

## Required Permissions

### LED Matrix Device Access

By default, LED Matrix devices appear as serial devices (e.g., `/dev/ttyACM0`, `/dev/ttyACM1`) that are typically owned by root with restricted permissions. To allow your user to access these devices, you have several options:

#### Option 1: Add User to dialout Group
```bash
# Add your user to the dialout group
sudo usermod -a -G dialout $USER

# Log out and log back in, or use:
newgrp dialout

# Verify group membership
groups $USER
```

#### Option 2: Create Custom udev Rules
Create a udev rule file to automatically set proper permissions:

```bash
# Create the udev rule file
sudo tee /etc/udev/rules.d/99-framework-led-matrix.rules <<EOF
# Framework 16 LED Matrix Input Modules
SUBSYSTEM=="tty", ATTRS{idVendor}=="32ac", ATTRS{idProduct}=="0020", MODE="0666", GROUP="dialout"
SUBSYSTEM=="usb", ATTRS{idVendor}=="32ac", ATTRS{idProduct}=="0020", MODE="0666", GROUP="dialout"
EOF

# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger
```

#### Option 3: Run as Root (Not Recommended)
Since running as root will bypass permission issues, this is not recommended for security reasons. You also may have to work around PEP 668 restrictions on an externally managed Python environment, as discussed above.
```bash
sudo python3 -m led_mon.led_system_monitor
```

## Keyboard Input Access (Optional)

For the keyboard shortcut features to work, the application needs read access to keyboard input devices:

```bash
# Add user to input group (be aware of security implications)
sudo usermod -a -G input $USER

# Log out and log back in, then verify
groups $USER
```

**Security Note:** Adding your user to the `input` group allows any program running as your user to potentially capture keystrokes. Consider the security implications before doing this, or do not add your user to the group, and use `--no-key-listener` to disable this feature.

## Modifying the Apps Configuration
* The app is configured *out of the box* to cycle through most of the available widgets, switching to the next widget every 30 seconds.
* To customize the coonfiguration:
  * The file `led_mon/config.yaml` contains the default configuration, along with comments explaining the format and meaning of config settings.
  * Make a copy of `config.yaml`, named `config-local.yaml`, in the `led_mon` directory, and make any desired changes. This file is git-ignored, so it will not be shared or overwritten.
  * If `config-local.yaml` is present, it will be the active config, and `config.yaml` will be ignored.
  * When running as a service, both config files will be copied to `/opt/led_mon/_internal/`. Files in this directory will be completely overwritten for every installation, so you should maintain your local configuration in the project repo, not the application installation directory.
  * The `config.yaml` file may be updated when you run `git pull` in the repo. Check Pull Request comments for an explanation of what changed. Every effort will be made to avoid breaking changes, but they cannot be ruled out at this stage of dvelopment. When new widgets are added to the app, you'll need to manually copy the new widget config settings into your local config file if you have one.

## Verifying Device Access

To check if your LED Matrix devices are properly accessible:

```bash
# List LED Matrix devices
ls -la /dev/ttyACM*

# Check if they're accessible by your user
python3 -c "from serial.tools import list_ports; [print(f'{p.device}: {p.description}') for p in list_ports.comports() if 'LED Matrix' in str(p)]"
```

## Run from the command line
```
cd led-matrix
python -m led_mon.led_system_monitor [--help] [--no-key-listener] [--disable-plugins] [--list-apps]
python -m led_mon.led_system_monitor --help #For more verbose help info
```

## Run as a Linux service
Enter the top-level project directory, and ensure that a virtual environment is configured and activated.
```
./build_and_install.sh
systemctl --user start|stop|restart|status fwledmonitor
```

## Keyboard Shortcut
* Alt+I: displays app names in each quadrant while keys are pressed
* Alt+N: displays the next widget without waiting for the time slice to complete
* Alt+F: freezes app switching, causing the current widget to be displayed indefinitely
* Alt+U: unfreezes app switching
* Disable key listener with `--no-key-listener` program arg
* To use the key listener, the app must have read permission on the keyboard device (e.g `/dev/input/event<n>`). T use the key listener, you need to add your user account to the `input` group and ensure there is a group read permission on the keyboard device. **NB:** Consider the implications of this. Any program running as a user in the `input` group will be able to capture your keystrokes.

## Plugin Development
* See `plugins/plugin-README.md` for instructions

## Plugin Configuration and Dependencies
See `config-README.md` for general configuration instructions. Here we provide plugin-specific configuration, dependency, and other information. Plugins that have no special configuration or depenency requirements are not adderssed here.

### Time (provided by `time_weather_plugin.py`):
Configure the following arguments in the config file (`app->args`)

`fmt_24_hour: true|false`

### Weather (provided by `time_weather_plugin.py`):
Specify app arguments in the config file as described below.
Set arguments (`app -> ags`) for the `weather` app in the desired quadrant
  - Weather provider behavior:
    - Primary provider: OpenWeather (used when `OPENWEATHER_API_KEY` is set)
    - Automatic fallback provider: Open-Meteo (no API key required)

- Environment variables:
    - `OPENWEATHER_API_KEY` (optional): enables OpenWeather as primary provider.
    - `IP_LOCATE_API_KEY` (optional): enables IPLocate-based IP geolocation when you do not set `lat_lon` or `zip_info`.
      If this is not set, the app will fall back to keyless IP geolocation providers.
  - To enable online lookup of local weather information, the app must know your location. Choose one or more of the options.

1) Specify country-specific zip and [ISO 3166 digraph code](https://www.iban.com/country-codes)
    
         `zip_info: ["your zip", "country code"]`

2) Specify latitude and longitude direclty

`lat_lon: [<lat>, <lon>]`

3) Set env var IP_LOCATE_API_KEY in `.env`. Get a free API key from https://iplocate.io
       
  - Display temperature in Celsius, Farenheit, or Kelinv. Default is metric

`units: imperial|metric|standard`
  - If weather is configured with `scope: panel`, it owns the full panel while active and the sibling quadrant on that side is suppressed by the scheduler.
    For predictable rotation, configure one panel-scope app per side and set the sibling app to `display: false`.
  - Show current or forecast weather. Default is current

`forecast: true|false`
  - Set day offset (GMT time) for forecast (max 5, default 1)

`forecast_day: n`
  - Set Hour offset (GMT time) for forecast on selected day. One of 0, 3, 6, 9, 12, 15, 18, 21. default is 12
    If selected time is more than 5 * 24 hours from present time, the latest available forecast will be shown

`forecast_hour: n`
  - Override the key used to display the app ID. This means if forecast is true, use weather_forecast, otherwise use weather_current

- Specify measures to show. If more than one is provided, the app will cycle through them indefinitely
    
    `measures: [temp_condition, wind_chill, wind]`
  - Specify the number of seconds to display each measure.
    
    `measures-duration: 20`

`id_key_override: [forecast, weather_forecast, weather_current]`

If `forecast` is true, the `Forecast Days` and `Forecast Hours` settings will be shown at the bottom left and right edges of the LED device. The `Forecast Days` value will be indicated by 1 to 5 pixels stacked from the bottom on the left edge. The `Forecast Hours` will be indicated by one to 8 pixels stacked from the bottom on the right edge, each representing the three-hour periods from 0 to 21. A hash mark will be drawn in the adjacent column at the fourth pixel, if lit, for ease of reading.

### Snapshot (built-in app, not a plugin):
Configure the following arguments in the config file (`app -> args`)
- Name of the JSON file with a pattern to display

`file: <file name>`
- The file path relative to the module dir (`led_mon`)

`path: <path>`
- The sudbir of the file, relative to `path`

`panel: left|right|<xxx>`

### Equalizer (provided by `equalizer_plugin.py`)
The equalizer is effectively panel-wide per side (`left` or `right`) because it writes directly to the LED device for that side.
If configured as `scope: panel`, the scheduler enforces panel ownership and suppresses the sibling quadrant while it is active.
Set the following app settings. These are direct properties of the equalizer app, not args
- Set to true if the app will handle drawing to the grid the entire time it is active. If false, the app draws a static snapshot on every invocation. Default is false

`persistent-draw: true|false`
- Since the equalizer draws continuously to the LED panel, this function (specified in `app_funcs`), is invoked to pause the equalizer when its duration peroiod expires

`dispose-fn: equalizer_dispose`

Configure the following arguments in the config file (`app -> args`)
- Use the internal python 9-band filter or use an extenal filter. [EasyEffects](https://github.com/wwmm/easyeffects) is the recommended external filter to use. You can tune the equalizer dynamically as it runs, using the EasyEffects GUI.

`external-filter: false|true`
- Select the equalizer input source mode.
  - `playback` (default): follows the current sink monitor.
  - `microphone`: captures microphone input (recommended to dedicate a panel/quadrant for this mode).

`input-mode: playback|microphone`
- Optional input device override used primarily with `input-mode: microphone` (matches an input device name).

`input-device: <device-name-or-index>`
- Per-band gain multiplier applied after band energy detection.
  - Default `1.35` for `playback` (improves low-volume responsiveness).
  - Default `0.75` for `microphone` (reduces ambient mic sensitivity).

`level-gain: <float>`
- Per-band minimum level threshold after gain. Bands below this value are forced to zero.
  - Default `1` for `playback`.
  - Default `18` for `microphone` (reduces ambient mic noise spikes).

`noise-gate-level: <int>`
- Total level sum threshold used to treat frames as silent (for pulse idle transitions).
  - Default `2` for `playback`.
  - Default `48` for `microphone`.

`silence-level-sum-threshold: <int>`
- Identify which physical panel side this equalizer instance controls. Used for instance identity/dispose handling.
  Run playback and microphone equalizers as separate app instances and assign each to its own panel/quadrant time slice.

`side: left|right`
- Delay (seconds) before entering pulse-only silent visuals when levels drop to zero.

`zero-frame-delay-sec: <seconds>`
- Pulse start delay (legacy alias retained for compatibility). The lower of this and `zero-frame-delay-sec` is used.

`silent-pulse-after-sec: <seconds>`
- Pulse period for long-silence mode (center-origin star-like ripple pulse).

`silent-pulse-period-sec: <seconds>`
- Time for gradually revealing the inverted `EQ0` mask during long silence while pulsing.

`silent-pulse-reveal-sec: <seconds>`

The equalizer relies on PulseAudio and Pipewire packages to receive and process the audio output of your computer. The following packages must be installed:
- Debian/Ubuntu: `sudo apt install pipewire pipewire-pulse wireplumber pulseaudio-utils`
- Fedora: `sudo dnf install pipewire pipewire-pulseaudio wireplumber`

You must add your user to the audio group
- `sudo usermod -Ag audio $USER`
- Then logout and login, run `newgrp audio`, or reboot. Verify with `sudo groups`

The Equalizer requires the Framework-provided Input Module Control binary to be intatlled somewhee on your executable path. If it's on the path, the app will find it. Otherwise, the equalizer will not run, and an error will be logged.
- [Project Info](https://github.com/FrameworkComputer/inputmodule-rs/tree/main) (with instructions to build from source)
- [Binary Downloads](https://github.com/FrameworkComputer/inputmodule-rs/releases)

If there are problems with the audio stream, try restarting the audio streaming services

`systemctl --user restart wireplumber pipewire pipewire-pulse`

If you use the EasyEffects external filter, add an input effects preset with 9 bands whose center frequencies are equal to the `BAND_CENTERS` list in `visualize.py`. Set q between 1 and 2 initially, and adjust it if you want narrower or wider bands. Set all the gains to 0, then adjust them with the sliders in the GUI whle audio is playing. Save the preset and set it to auto-load on startup.

## Notes
* See https://github.com/FrameworkComputer/inputmodule-rs for info about the LED matrix device. Be sure to run the code that installs the udev rules for accessing the devices.
* To list your input devices, use the following python code after installing [Python-evdev](https://python-evdev.readthedocs.io/en/latest/index.html)
```
>>> import evdev

>>> devices = [evdev.InputDevice(path) for path in evdev.list_devices()]
>>> for device in devices:
>>>     print(device.path, device.name, device.phys)
/dev/input/event1    Dell Dell USB Keyboard   usb-0000:00:12.1-2/input0
/dev/input/event0    Dell USB Optical Mouse   usb-0000:00:12.0-2/input0
```
* The baseline reference for calculating the ratio used to display temperature and fan speed readings were arbitarily defined. See `TEMP_REF` and `MAX_FAN_SPEED` in `temp_fan_plugin.py`.  
* To examine system performance measures manually and in detail, run `python ps-util-sensors.py`
* To use a different key combination for identifying the running apps, see `KEY_I` and `MODIFIER_KEYS` in `led_system_monitor.py`

led-matrix

led-matrix Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

led-matrix

led-matrix Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README