homefree-aoostar-lcd

HomeFree extension that drives the embedded front-panel LCD on the Aoostar WTR Max (and the compatible GEM12+ Pro) with live system vitals — CPU, memory, load, hwmon temperatures, BTRFS health, drive temperatures, and per-NIC network throughput.

The hardware is a 960×376 USB CDC-ACM serial display (VID:PID 0416:90a1). This flake packages asterctl (MIT/Apache-2.0) from the upstream zehnm/aoostar-rs Rust project, plus a lightweight Python sampler that feeds it metrics from psutil, /sys/class/hwmon, btrfs device stats, and the optional HomeFree drive-temperature sampler DB.

No reverse proxy, no web UI. The on-screen panel is the surface. Configuration is exposed in the HomeFree admin UI on the Services page like any other HomeFree app, via the standard options-metadata form.

Temperature thresholds (warn/err colour bands) are derived using the same cascade HomeFree's Hardware page does — NVMe (WCTEMP, CCTEMP) direct, else (crit-15, crit-5), else CPU bucket by /proc/cpuinfo family — so the LCD and the web UI agree on what counts as "hot."

Wiring it into a HomeFree box

1. Register this flake as a custom flake. Either through the admin UI (Developers → Custom Flakes → Add), or by appending to /etc/nixos/custom-flakes.nix:

   {
     inputs.homefree-aoostar-lcd.url = "path:/home/erahhal/homefree-aoostar-lcd";
   }
   

2. Rebuild — sudo nixos-rebuild switch.

3. Open admin./services, find Front Panel LCD, and toggle enable. Pick which panels to rotate through and the rotation interval.

Hardware presence

The systemd units are guarded by ConditionPathExists=/dev/aoostar-lcd, so enabling this service on a box that does not have the LCD attached is a no-op (the service stays inactive). A udev rule installs the stable /dev/aoostar-lcd symlink — necessary because the LCD shows up as /dev/ttyACM* and may race other CDC-ACM devices (e.g. a Z-Wave stick) for the same numeric slot.

What's not in scope

• Brightness control — asterctl v0.2.0 doesn't expose it.
• Custom user panels — this flake ships four built-ins (CPU & Memory, Temperatures, Storage, Network). Editing panelDefs in apps/homefree-aoostar-lcd/default.nix is the path to changes.
• Off-when-idle scheduling — not implemented in v0.1; if needed, wire it with a separate systemd timer that calls asterctl --off.

See also

• Upstream: https://github.com/zehnm/aoostar-rs
• Reverse-engineered LCD protocol: https://zehnm.github.io/aoostar-rs/lcd_protocol.html
• HomeFree flake plugin reference: ~/homefree-navidrome, ~/homefree-ai