packaging: add a systemd user unit for the LCD stats ticker

packaging/systemd/README.md

@@ -1,8 +1,17 @@
-# trccd service files
+# TRCC service files
 
-Optional OS-level service registration for the TRCC daemon. The daemon
-auto-spawns when any UI calls it, so installing these is **not required**
-— they just make the daemon survive reboots / logout.
+Optional OS-level service registration. Two independent units live here:
+
+| Unit | What it does |
+|------|--------------|
+| `trccd.service` | the IPC daemon that owns USB and serves CLI/API/GUI clients |
+| `trcc-display.service` | the render-and-send ticker, so the panel shows live metrics after a reboot |
+
+**Install one or the other, not both.** Only one process may hold a panel's USB
+interface; running both makes them fight over it.
+
+The daemon auto-spawns when any UI calls it, so installing `trccd.service` is
+**not required** — it just makes the daemon survive reboots / logout.
 
 ## Linux (systemd user unit)
 
@@ -30,6 +39,57 @@ rm ~/.config/systemd/user/trccd.service
 systemctl --user daemon-reload
 ```
 
+## LCD stats ticker (systemd user unit)
+
+Drives the panel with the active theme on the configured refresh interval, from
+login. Without it the LCD only updates while the GUI or `trcc display play` is
+open, so it goes stale after a reboot.
+
+```bash
+# Install the unit + its helper (one-time)
+mkdir -p ~/.config/systemd/user
+cp trcc-display.service ~/.config/systemd/user/
+sudo install -Dm755 trcc-display-ticker /usr/bin/trcc-display-ticker
+
+systemctl --user daemon-reload
+systemctl --user enable --now trcc-display.service
+
+systemctl --user status trcc-display
+journalctl --user -u trcc-display -f
+```
+
+The helper runs `trcc detect` and drives the first panel it finds, so the unit
+carries no hardcoded VID:PID. To pin a specific panel, or to point at a
+pip/pipx install rather than `/usr/bin/trcc`:
+
+```bash
+mkdir -p ~/.config/trcc
+cat > ~/.config/trcc/ticker.env <<'EOF'
+TRCC_DEVICE=0416:5408
+TRCC_BIN=/home/you/.local/bin/trcc
+EOF
+systemctl --user restart trcc-display
+```
+
+To use the GUI while the ticker is running, stop it first — the ticker holds the
+USB interface, and the GUI blocks on its splash rather than reporting the device
+is busy:
+
+```bash
+systemctl --user stop trcc-display
+trcc qtgui
+systemctl --user restart trcc-display
+```
+
+To uninstall:
+
+```bash
+systemctl --user disable --now trcc-display.service
+rm ~/.config/systemd/user/trcc-display.service
+sudo rm /usr/bin/trcc-display-ticker
+systemctl --user daemon-reload
+```
+
 ## macOS (LaunchAgent)
 
 ```bash

packaging/systemd/trcc-display-ticker

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# trcc-display-ticker — device-detecting wrapper around `trcc display play`.
+#
+# Exists so trcc-display.service does not have to hardcode a VID:PID.  A
+# packaged unit naming one contributor's panel is useless to everybody else,
+# and `display play` requires an explicit device key.
+#
+# Override detection by setting TRCC_DEVICE=VVVV:PPPP in the environment —
+# trcc-display.service reads ~/.config/trcc/ticker.env for exactly this, which
+# is also how you pin one panel when several are attached.
+
+set -uo pipefail
+
+TRCC="${TRCC_BIN:-/usr/bin/trcc}"
+
+if [[ ! -x "$TRCC" ]]; then
+    # Fall back to PATH for pip/pipx installs, where trcc is under ~/.local/bin.
+    if command -v trcc >/dev/null 2>&1; then
+        TRCC="$(command -v trcc)"
+    else
+        echo "trcc-display-ticker: trcc not found (tried $TRCC and PATH)" >&2
+        exit 127
+    fi
+fi
+
+key="${TRCC_DEVICE:-}"
+
+if [[ -z "$key" ]]; then
+    # `trcc detect` prints rows like "  0416:5408  Winbond Trofeo Vision …".
+    key="$("$TRCC" detect 2>/dev/null \
+        | grep -oE '[0-9a-fA-F]{4}:[0-9a-fA-F]{4}' \
+        | head -1)"
+fi
+
+if [[ -z "$key" ]]; then
+    echo "trcc-display-ticker: no device detected — is it plugged in, and are" >&2
+    echo "                     the udev rules installed? (try: trcc doctor)"  >&2
+    # Non-zero so systemd's Restart= backs off and retries.  A missing device at
+    # login is normal: USB enumeration often lands after graphical-session.
+    exit 1
+fi
+
+echo "trcc-display-ticker: driving $key"
+exec "$TRCC" display play "$key"

packaging/systemd/trcc-display.service

@@ -0,0 +1,32 @@
+[Unit]
+# trcc-display — drives the LCD with the active theme on a timer.
+#
+# This is a USER unit. Install with:
+#     systemctl --user enable --now trcc-display.service
+#
+# Distinct from trccd.service: that one owns the IPC daemon, this one runs the
+# render-and-send ticker (`trcc display play`) so the panel shows live metrics
+# after a reboot without anyone opening the GUI.  Run one or the other — both
+# want exclusive USB access and will fight over the interface.
+Description=TRCC Linux LCD stats ticker
+Documentation=https://github.com/Lexonight1/thermalright-trcc-linux
+After=graphical-session.target
+PartOf=graphical-session.target
+
+[Service]
+Type=simple
+# Optional: TRCC_DEVICE=0416:5408 to pin one panel, TRCC_BIN=/path/to/trcc for
+# a pip/pipx install.  A missing file is not an error.
+EnvironmentFile=-%h/.config/trcc/ticker.env
+ExecStart=/usr/bin/trcc-display-ticker
+# Blank the panel on stop rather than leaving a stale frame lit.
+ExecStopPost=/bin/sh -c 'exec ${TRCC_BIN:-/usr/bin/trcc} display sleep "$(${TRCC_BIN:-/usr/bin/trcc} detect 2>/dev/null | grep -oE "[0-9a-fA-F]{4}:[0-9a-fA-F]{4}" | head -1)"'
+
+# The device is often not enumerated yet at login, and only one process may hold
+# the interface — so back off and retry rather than failing permanently.
+Restart=always
+RestartSec=5
+StartLimitBurst=0
+
+[Install]
+WantedBy=default.target