README-NIXOS.md

Framework 16 LED Matrix Monitoring - NixOS Integration

This repository provides a NixOS package and a standalone NixOS module (ledmatrixmonitoring.nix) for the Framework 16 LED Matrix monitor service.

What is new in the module design

• Standalone module file: ledmatrixmonitoring.nix (no large inline module block in flake.nix)
• Nix-native configuration schema: services.led-matrix-monitoring.layout (typed options for quadrants/apps)
• Configuration mode switch: configurationMode = "linuxOS" | "nix-flake" | "nix-module"
• Backward compatibility: legacy quadrant shorthand (topLeft, bottomLeft, etc.) and settings/configFile remain available
• Non-Nix Linux flow unchanged: scripts like build_and_install.sh and install_service.sh are untouched

Quick start (flake-based NixOS)

1) Add input

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    led-matrix-monitoring = {
      url = "github:timoteuszelle/led-matrix/main";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

2) Import the module

{
  imports = [
    inputs.led-matrix-monitoring.nixosModules.led-matrix-monitoring
    # or: inputs.led-matrix-monitoring.nixosModules.ledmatrixmonitoring
  ];
}

3) Configure the service (recommended style)

{
  services.led-matrix-monitoring = {
    enable = true;
    configurationMode = "nix-module";

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

    # Optional examples:
    # disableKeyListener = true;
    # disablePlugins = true;
    # user = "tim";
    # environment.DISPLAY = ":0";
  };
}

4) Rebuild

sudo nixos-rebuild switch --flake .#your-hostname

Configuration modes

• linuxOS
  • Service behaves like normal Linux packaging lookup (no Nix-managed config file injected)
  • Do not combine with layout, settings, config, configFile, or legacy quadrant shorthand
• nix-flake
  • Nix-managed config source required (layout, settings, configFile, or legacy shorthand)
• nix-module
  • Same runtime behavior as nix-flake, named for direct module-centric workflows

Configuration sources (priority and compatibility)

Recommended:

• layout (typed, future-friendly Nix schema)

Also supported:

• settings (raw attrset rendered to YAML)
• config (deprecated alias of settings)
• configFile (path to YAML file)
• Legacy shorthand: topLeft, bottomLeft, topRight, bottomRight (+ legacyDuration)

Module option reference

Top-level options under services.led-matrix-monitoring:

• enable
  • Enables the systemd service and installs the package to environment.systemPackages.
• configurationMode
  • linuxOS: service runs without Nix-managed config injection and uses the app's Linux config lookup behavior.
  • nix-flake / nix-module: require one Nix-managed config source (layout, settings, config, configFile, or full legacy quadrant shorthand).
• package
  • Package that provides led-matrix-monitor.
• layout
  • Recommended typed schema for quadrant/app configuration.
• settings / config
  • Raw YAML-like attrset (config is deprecated alias of settings).
• configFile
  • Existing YAML file path passed through --config-file.
• Legacy shorthand options
  • topLeft, bottomLeft, topRight, bottomRight, legacyDuration.
• Runtime/service options
  • disableKeyListener, disablePlugins, user, group, environment, extraArguments.

layout app item options:

• name (required)
• duration (optional; falls back to layout duration)
• animate (default false)
• scope (optional; supports panel behavior)
• persistentDraw (default false)
• disposeFn (optional)
• display (default true)
• args (attrset of app-specific arguments)

Validation rules enforced by module assertions:

• settings and config cannot both be set.
• layout is mutually exclusive with settings, config, configFile, and legacy shorthand.
• configFile is mutually exclusive with layout, settings, config, and legacy shorthand.
• Legacy shorthand requires all four quadrants to be set.
• In layout, each quadrant list must contain at least one app.
• In linuxOS mode, managed config sources are rejected.
• In nix-flake/nix-module mode, one managed config source is required.

Panel-scope scheduling behavior

• If an active app has scope = "panel", it owns the full panel for that side while active.
• The sibling quadrant on that side is suppressed for both rendering and app rotation during that active slice.
• If both active top and bottom apps on the same panel request scope = "panel", top quadrant app wins and a warning is logged.
• For predictable behavior, configure one panel-scope app per side and set the sibling app to display = false.

Notes for future development

The new schema aligns with long-term roadmap goals:

• clean mode boundaries
• easier extension for additional app fields/options
• stronger validation in module assertions
• easier API-oriented evolution without forcing users to hand-maintain YAML-shaped config in Nix

Troubleshooting

Check service status:

systemctl status led-matrix-monitoring

Follow logs:

journalctl -u led-matrix-monitoring -f

Test binary:

led-matrix-monitor --help