Lighweight system daemon for running the Peerless Assassin digital display.
  • Rust 91.3%
  • Nix 8.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-16 22:19:45 -04:00
nix initial one-shot 2026-10-16 22:19:45 -04:00
src initial one-shot 2026-10-16 22:19:45 -04:00
tests initial one-shot 2026-10-16 22:19:45 -04:00
.envrc initial one-shot 2026-10-16 22:19:45 -04:00
.gitignore initial one-shot 2026-10-16 22:19:45 -04:00
Cargo.lock initial one-shot 2026-10-16 22:19:45 -04:00
Cargo.toml initial one-shot 2026-10-16 22:19:45 -04:00
flake.lock initial one-shot 2026-10-16 22:19:45 -04:00
flake.nix initial one-shot 2026-10-16 22:19:45 -04:00
README.md initial one-shot 2026-10-16 22:19:45 -04:00

peerlessd

A lightweight, Linux-only Rust library and foreground daemon for the Thermalright Peerless Assassin 120 Digital display. The upstream PA120 digit/indicator mapping and physical-wire remap have been confirmed on hardware. Live mode gathers total CPU usage, CPU temperature, GPU usage, and GPU temperature, then renders a complete frame once per second.

Uses the kernel's existing HID driver through hidraw. No custom kernel module, GUI, network service, or root daemon is required.

The CLI uses pico-args for a small argument parser. Run peerlessd --help for options. Argument errors exit with status 2; setup/display errors exit with status 1. Individual sensor failures do not terminate monitoring: the affected fields are blanked and retried on the next sample.

Attribution

Enormous thanks to Lexonight1 and the contributors to thermalright-trcc-linux. Their Python project's reverse-engineering work, protocol documentation, and PA120 digit/indicator mapping and physical-wire remap were invaluable in bringing this display to life. Using their existing layout saved us from having to map every LED by hand.

The display mapping used by peerlessd is based on that work. See Mapping provenance below for the specific source files and revision we consulted.

Development

nix develop
cargo build
cargo test
cargo clippy --all-targets -- -D warnings

The dev shell includes Rust tooling plus:

  • usbutils: lsusb, usb-devices
  • udev: udevadm
  • hid-tools: hid-decode, hid-recorder
  • lm_sensors: sensors
  • strace: inspect system calls

The HID backend is hidapi's native Linux implementation with basic-udev; it does not require linking libusb or libudev. Cargo may record dependencies such as windows-sys for upstream crates' other targets in Cargo.lock; those are not compiled on Linux.

NixOS service

The flake exports nixosModules.default (also nixosModules.peerlessd) and packages.<system>.peerlessd/default for x86_64-linux and aarch64-linux. For example, merge this into your host flake:

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  inputs.peerlessd.url = "git+file:///home/cameron/Projects/peerlessd";
  inputs.peerlessd.inputs.nixpkgs.follows = "nixpkgs";

  outputs = { nixpkgs, peerlessd, ... }: {
    nixosConfigurations.desktop = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        peerlessd.nixosModules.default
        {
          services.peerlessd = {
            enable = true;
            display = "pa120";
            color = "ff0000";
            brightness = 100;
          };
        }
      ];
    };
  };
}

The local Git URL is an example using this checkout; replace it with the repository location when publishing. Git-backed flakes include only tracked files: ensure the new nix/, Rust sources/tests, and updated flake/Cargo files are tracked before rebuilding. A commit is not required for local working-tree changes. Do not include target/ or .direnv/. With a non-flake NixOS configuration, the module can instead be imported directly from /home/cameron/Projects/peerlessd/nix/module.nix.

After rebuilding your NixOS configuration, inspect it with:

systemctl status peerlessd.service
journalctl -u peerlessd.service -b
ls -l /dev/peerlessd

The module creates a dedicated, non-login peerlessd system user/group. Its udev rule matches USB 0416:8001, HID interface 00, sets the node's group to peerlessd and mode to 0660, and creates /dev/peerlessd. No root daemon, sudo, interactive-session ACL, or world-writable HID rule is needed. The CLI resolves the symlink before validating the enumerated interface's USB ID. Other HID interfaces are not granted access.

The service starts at boot when the device exists, and udev requests it when the display appears later. It runs in the foreground with restart-on-failure, no capabilities, a read-only system/home sandbox, and a private network namespace. /proc/stat, sysfs, and device nodes remain visible for telemetry. After the rule is installed for an already-connected device, unplug/reconnect the cooler's USB connection or retrigger udev for that specific node if the symlink/permissions have not appeared. Stop a manually running peerlessd first so it releases its advisory lock. This module is not installed or activated merely by building this project.

Service options

Option under services.peerlessd Default Purpose
enable false Enable the systemd service and udev permissions.
display "pa120" Display enum; currently only Peerless Assassin 120 Digital.
package Package built from this source Override the daemon package.
device "/dev/peerlessd" Hidraw node or stable symlink.
usbPath null Restrict the udev rule to one ID_PATH USB port.
color "ff0000" Six hexadecimal RGB digits.
brightness 100 Integer percentage, 0–100.
cpuTemperaturePath null Override CPU temperature discovery with a millidegree input file.
gpu.vendor "auto" auto, amd, or nvidia; auto infers the configured driver(s).
gpu.device null Optional explicit DRM card directory; must match the effective vendor.

The module detects NVIDIA through hardware.nvidia.enabled (or NVIDIA videoDrivers on older NixOS). It detects AMD through amdgpu videoDrivers/kernel modules, hardware.amdgpu.initrd.enable, or an AMD NVIDIA PRIME bus ID. If exactly one vendor is configured, the daemon filters discovery to that vendor. If both or neither are detected, runtime primary-GPU selection remains enabled; generic modesetting configurations therefore still work. No fixed cardN index is generated. Set gpu.vendor explicitly if a hybrid/offload machine should monitor a different GPU.

When NVIDIA telemetry may be used, the service receives the configured hardware.nvidia.package binary output in PATH, plus the video supplementary group. This uses the driver-matched nvidia-smi, not an unrelated version from another nixpkgs package. Forcing AMD removes this NVIDIA dependency/group. The module does not enable, replace, or reconfigure GPU drivers; explicitly forcing NVIDIA requires NVIDIA support to be configured already.

The USB ID is shared by multiple Thermalright products, so the rule is not positive model detection. With multiple matching devices, set usbPath to the intended interface's ID_PATH from udevadm info --query=property --name=/dev/hidrawN. This narrows both the permission grant and /dev/peerlessd symlink to that USB port.

nix build builds the binary; nix flake check builds it with its Rust tests and runs module-evaluation checks covering permissions, GPU inference, hybrid overrides, argument escaping, and option validation.

Live monitoring

Build, then verify the selected sources and a live sample without touching the display:

cargo build
./target/debug/peerlessd run --model pa120 --dry-run --once

Write live readings to the explicitly selected PA120 (replace the path with one from peerlessd list):

sudo ./target/debug/peerlessd run --device /dev/hidrawN --model pa120

run stays in the foreground, suitable for a systemd Type=simple service. It opens and locks the display once, sends no handshake, establishes a CPU counter baseline, waits for the first one-second interval, then samples all fields and renders/writes one complete frame per tick. Scheduling accounts for time spent reading/writing; missed ticks are skipped instead of producing catch-up bursts. --once stops after the first update. --dry-run reads real sensors and renders frames, but prints just the readings without enumerating/opening HID devices. -- in these readings means unavailable, not zero.

Live temperatures are Celsius, rounded to the nearest integer. Styling defaults to red at 100%; --color RRGGBB and --brightness 0..100 override it. Selected sources are printed at startup; sensor warnings and recoveries go to stderr only when they change. Normal display updates do not log once per second. Display write failures exit so a service manager can restart the process. There is no custom signal handler: Ctrl-C/SIGTERM stop the process and leave the last displayed frame; use off to clear it.

Sensor sources and dependencies

No new Rust dependencies are needed for telemetry.

Reading Source Behavior
Total CPU usage Aggregate cpu counters in /proc/stat Interval busy/total time, 0–100% across all logical CPUs, not a per-core sum or load average. Idle and I/O wait are idle; guest counters are not double-counted.
CPU temperature CPU-only hwmon drivers: coretemp, k10temp, zenpower Intel package temperature; AMD Tdie preferred, Tctl fallback. Hottest package on multi-socket systems. Does not substitute NVMe, RAM, or motherboard temperatures.
AMD GPU usage Selected DRM device's gpu_busy_percent Driver-provided 0–100% busy value.
AMD GPU temperature Selected device's hwmon tempN_input Edge temperature preferred over junction; millidegrees converted to degrees.
NVIDIA GPU usage/temperature nvidia-smi from the installed proprietary driver One query pinned to the selected card's PCI identity, with a 750 ms timeout and bounded output. Requires nvidia-smi in PATH, including in a systemd service's environment. No NVML Rust binding or CUDA SDK dependency.

Automatic GPU selection prefers the boot_vga primary device, then the first supported card in numeric DRM order. --gpu-vendor auto|amd|nvidia optionally filters discovery before choosing a card; explicit --gpu paths must match that filter. It never combines one GPU's temperature with another's usage. Unsupported drivers (including Intel GPU telemetry and nouveau in this implementation) leave GPU fields blank instead of guessing or silently switching to a secondary GPU. NVIDIA does not provide the same simple sysfs busy ABI used here for AMD; its driver tool is the optional external dependency.

Override discovery when needed:

./target/debug/peerlessd run --model pa120 --dry-run --once --gpu /sys/class/drm/card2
sudo ./target/debug/peerlessd run --model pa120 --device /dev/hidrawN --cpu-temp-path /sys/class/hwmon/hwmon2/temp1_input

--gpu takes a DRM cardN directory, not a connector or render node. --cpu-temp-path takes an input file containing integer millidegrees Celsius. Inspect the source logs and hwmon name/tempN_label before overriding; class numbers can change after reboot. Discovery runs at startup. Missing automatic CPU/GPU sources and a selected AMD device's missing hwmon are retried about every five seconds to handle boot-time driver probing; source descriptions are logged again only when they change. Established CPU and AMD GPU paths are pinned to physical sysfs devices, so recycled class aliases do not redirect readings to another device. Existing sources are reread each tick, including after read failures. Restart after changing drivers or replacing established sensor sources. Invalid, faulted, disabled, negative, or unrepresentable readings are blank, never clamped to a plausible value.

Rust API

The library exports reusable DisplayValues, ProcessorReadings, Temperature, Percent, TemperatureUnit, DisplayOptions, DisplayFrame, and Pa120Display types. Temperature::new checks 0–999; Percent::new checks 0–100 for utilization or brightness. ProcessorReadings::new(temperature, utilization) checks both inputs and fills both fields. The numeric wrappers expose their values with get(); Percent::ZERO and Percent::FULL represent 0% and 100%.

Render without enumerating, opening, or writing hardware, including partially missing readings:

use peerlessd::{
    DisplayOptions, DisplayValues, Percent, ProcessorReadings, Temperature, TemperatureUnit,
};

fn main() -> anyhow::Result<()> {
    let values = DisplayValues {
        cpu: ProcessorReadings {
            temperature: Some(Temperature::new(42)?),
            utilization: None, // Unavailable: blank digits and percent indicator.
        },
        gpu: ProcessorReadings::default(), // No GPU readings: blank its labels too.
        unit: TemperatureUnit::Celsius,
    };
    let options = DisplayOptions {
        color: [255, 128, 0],
        brightness: Percent::new(25)?,
    };
    let frame = values.render(options);
    let reports: &peerlessd::protocol::LedReports = frame.reports();
    assert_eq!(reports.len(), 5);
    assert!(reports.iter().all(|report| report.len() == 64));
    Ok(())
}

Temperature and utilization are independently optional for each processor. None blanks that field and its unit/percent indicator; Some(0) displays zero. A processor's labels are lit when either field is present. DisplayValues::default() is entirely blank. Each render is a complete replacement frame, so missing readings clear previous digits rather than retaining stale values. TemperatureUnit::{Celsius, Fahrenheit} selects the indicator for both temperatures; it never converts the supplied values.

DisplayOptions::default() is red ([255, 0, 0]) at 100% brightness. All lit segments share the selected RGB color and brightness. Each output channel is floor(channel * brightness * 2 / 500), including the protocol's 0.4 scale (255 at 100% becomes 102). DisplayFrame owns fixed-size storage, and reports() borrows its five 64-byte reports: a 20-byte header, 252 RGB bytes, and 48 zero-padding bytes. These reports omit HIDAPI's extra zero report-ID byte.

Open an explicitly selected device once and reuse the handle for writes:

use peerlessd::{DisplayOptions, DisplayValues, Pa120Display, ProcessorReadings};

fn main() -> anyhow::Result<()> {
    // Replace this with the PA120's actual path from `peerlessd list`.
    let mut display = Pa120Display::open("/dev/hidraw9")?;
    let options = DisplayOptions::default();
    let mut values = DisplayValues {
        cpu: ProcessorReadings::new(42, 17)?,
        gpu: ProcessorReadings::new(65, 89)?,
        ..Default::default()
    };
    display.write(&values, options)?;

    // Later, retain CPU readings but clear all GPU fields and labels.
    values.gpu = ProcessorReadings::default();
    let frame = values.render(options);
    display.write_frame(&frame)?; // Send a previously rendered frame unchanged.

    display.clear()?; // Explicitly blank all LEDs when desired.
    Ok(())
}

Pa120Display::open requires read/write access and locks the selected device for repeated updates. The USB ID is shared by other models: opening does not detect the PA120 layout or send an automatic handshake. Writes observe the transport's frame cooldown; a failed write can leave an incomplete frame and is not automatically retried. Dropping the handle releases the lock but does not clear the display. clear() sends a blank frame, not a standby command. Stop other display controllers first; the lock only excludes cooperating programs. These display-only examples do not poll sensors. peerlessd::sensors::{SensorConfig, Sensors} exposes discovery, source descriptions, and sample() for callers needing telemetry. Each SensorSnapshot contains DisplayValues in Celsius plus warnings; the first CPU usage sample establishes the baseline and returns None. Wait one second before the next sample for interval utilization.

Start with passive discovery

cargo run -- list
cargo run -- list --all
lsusb -d 0416:8001

list reads HID enumeration metadata without opening hidraw nodes or sending a handshake. It prints paths, USB IDs, interface numbers, usage IDs, and product/manufacturer strings. The default filter is 0416:8001, shared by several Thermalright products—not a positive identification of the PA120.

In the examples below, replace /dev/hidrawN with an actual path from list. Device numbers can change after reboot or reconnection.

udevadm info --query=all --name=/dev/hidrawN

USB and HID descriptors can also be inspected with lsusb -v -d 0416:8001 and hid-decode. Some descriptor accesses require additional permissions. Don't run another HID controller or hid-recorder against the same interface during a probe or write.

Probe explicitly

cargo run -- probe --device /dev/hidrawN
cargo run -- probe --device /dev/hidrawN --timeout-ms 2000

Upstream reports that the firmware may answer the identification handshake only once per power cycle. Probe sends exactly one initialization report and performs one response read, with no automatic retry. Its default read timeout is 1000 ms, in addition to the 50 ms pre-send and 200 ms post-send delays. A timeout does not necessarily mean the device is absent or unusable.

The full raw response is printed before parsing. Save that output during hardware investigation: peerlessd does not yet persist identification results. The current upstream implementation reads SUB at raw byte 4 and PM at byte 5, while the dedicated protocol document says SUB at byte 5 and PM at byte 6. The CLI follows the implementation's offsets, validates the 64-byte response's magic and command, and does not infer a model or segment mapping from them.

Preview packets without hardware

cargo run -- layout-test --layout pa120 --dry-run
cargo run -- layout-test --layout pa120 --color ff8000 --brightness 25 --dry-run
cargo run -- off --model pa120 --dry-run

For layout-test and off, dry-run does not enumerate, open, or write any hardware. It prints the five raw protocol reports, including padding. Each report is 64 bytes; the extra zero report-ID byte required by the HIDAPI calling convention is not included in these dumps.

Clear the display

cargo build
sudo ./target/debug/peerlessd off --device /dev/hidrawN --model pa120

--model pa120 is required for run and off; layout-test instead requires --layout pa120. These are explicit choices, not hardware detection. Neither command sends a handshake. Writes require the selected interface to enumerate as 0416:8001, and an advisory lock prevents cooperating peerlessd processes from interleaving reports. Stop other display controllers first, since they can ignore the lock. Patterns persist until replaced; off sends black RGB values, not a hardware standby command.

Test the confirmed PA120 layout

The upstream PA120 renderer and its physical-wire remap have been confirmed on hardware. Use a fixed diagnostic pattern to check the display:

cargo build
./target/debug/peerlessd layouts
sudo ./target/debug/peerlessd layout-test --device /dev/hidrawN --layout pa120

The default pattern is red at 100% brightness, with these deliberately distinct, fixed diagnostic values:

Field Expected reading
CPU temperature 123°C
CPU utilization 45%
GPU temperature 67°C
GPU utilization 89%

These are not live sensor readings. Check that all numbers, CPU/GPU labels, and °C/% indicators appear in their intended places; GPU temperature should have a blank leading digit. The pattern remains until replaced or cleared with off.

Change the fixed values to check other digits, the partial hundreds digit for 100% utilization, or the unit indicator:

sudo ./target/debug/peerlessd layout-test --device /dev/hidrawN --layout pa120 --cpu-temp 42 --cpu-load 100 --gpu-temp 75 --gpu-load 0
sudo ./target/debug/peerlessd layout-test --device /dev/hidrawN --layout pa120 --unit f
./target/debug/peerlessd layout-test --layout pa120 --dry-run

Temperatures accept 0–999 and loads 0–100. --unit c|f selects only the indicator; it does not convert the literal temperature values. --color accepts six hexadecimal RGB digits (default ff0000); --brightness accepts 0–100 (default 100). No handshake or sensor polling is performed. Explicit --layout pa120 selects the PA120 model, so this command does not also require --model.

Mapping provenance

Inspected thermalright-trcc-linux at commit 6ef1fdef6f1227265fca8fed96b82c2bf8e2bcb7:

Upstream provides one PA120 layout/remap, shared by PMs 16–31 (including RK120 at PM 23), not a separate layout for each PM. Hardware confirmation here is for the PA120, not every model in that upstream group. Other display styles have different arrangements and LED counts and are not interchangeable PA120 mappings. If another device differs, investigate its model and layout rather than cycling arbitrary packet sizes.

The upstream project is licensed GPL-3.0-or-later. The Rust renderer is independently implemented using the referenced hardware mapping data and standard seven-segment encoding; no Python runtime or upstream application code is required at runtime. The CLI integration test checks the exact lit wire indices against a reference derived separately from the upstream tables. Public API integration tests cover checked inputs, missing readings, styling, packet framing, and complete replacement updates without hardware access. The PA120 mapping has been confirmed on the physical display.

Permissions

Read/write access to the selected hidraw node is required for live display writes, probe, layout-test, off, and Pa120Display::open. Sensor files and the selected GPU driver must also be readable. Sudo is sufficient for initial manual testing; do not make all HID devices world-writable, and prefer narrowly scoped device access for a deployed service.

For a local desktop session, an administrator can install a narrowly scoped udev rule in /etc/udev/rules.d/70-peerlessd.rules:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0416", ATTRS{idProduct}=="8001", TAG+="uaccess"

Reload the rules and reconnect the device. This grants active-session access on systems supporting uaccess; a headless service should instead receive access through a dedicated group and a 0660 rule. The USB ID is shared, so this rule also covers other attached devices with that exact ID.

Protocol basis

The LED data packet is a 20-byte header followed by 84 RGB triplets (252 bytes) in physical wire order, split into 64-byte HID reports with zero padding. A full frame is 272 bytes before its 48 padding bytes, or five reports. The transport leaves at least 30 ms between complete frame updates.

References and prior reverse-engineering work:

The overview's 0xA0 description conflicts with the dedicated LED document and implementation. This project uses their DA DB DC DD header, init command 1, and RGB-data command 2. The LED writes and PA120 mapping have been confirmed on hardware; these references are still not a complete specification for every device sharing the USB ID.