kraken-lcd

Live system stats on the LCD of NZXT Kraken liquid coolers — as a rotating carousel of tiles with animated backgrounds, or as a single always-on display. Linux only, no NZXT CAM, no Electron, no venv: one small Python daemon on top of liquidctl.

Features

• Eight tiles, individually selectable and ordered: liquid temperature, CPU load, GPU load, CPU+GPU temperatures, RAM usage, NVMe temperature, pump rpm, fan rpm. One tile in the list = a static live display.
• Animated GIF backgrounds with the live value burned in — bring your own GIFs or use the generated defaults.
• Safe uploads. The stock liquidctl driver streams multi-megabyte uploads into buckets the firmware has refused, which can wedge the device into its bootloader (see liquidctl #774 / #907 — reported from this project). kraken-lcd ships a patched upload path that verifies the bucket setup first, absorbs sporadic firmware refusals invisibly, manages the device's image memory proactively, enforces a size budget with adaptive frame thinning, and paces uploads. When the device stops answering status reads, uploads are held back until a reconnect succeeds — a sick device is never fed more data.
• Pump/fan curves (optional): a [liquid °C → duty %] curve written to the device firmware — it keeps regulating even with the daemon stopped.
• Robust as a service: systemd watchdog, dedicated unprivileged user, suspend/resume hook, bootloader detection with clear recovery instructions and restart suppression.
• Per-tile styling: labels, colors, positions, palette/frame tuning.

Supported devices

Device	USB ID	LCD
NZXT Kraken Z53 / Z63 / Z73	1e71:3008	320 × 320
NZXT Kraken 2023	1e71:300e	240 × 240
NZXT Kraken 2023 Elite	1e71:300c	640 × 640
NZXT Kraken 2024 Elite RGB	1e71:3012	640 × 640

The LCD resolution is auto-detected. Developed and continuously tested on a 2024 Elite RGB; the other models are driven by the same liquidctl driver class — feedback and test reports are very welcome.

Requirements

Python ≥ 3.11 with liquidctl (≥ 1.13), Pillow and psutil. On Debian/Ubuntu everything comes from the distribution — no virtualenv, so Python upgrades cannot break the installation:

sudo apt install liquidctl python3-pil python3-psutil

GPU tiles use nvidia-smi (NVIDIA) or the amdgpu driver (AMD) automatically. NZXT CAM or CoolerControl must not manage the same device at the same time.

Installation

git clone https://github.com/relative23/kraken-lcd.git
cd kraken-lcd
sudo ./install.sh

The installer is idempotent (re-run it to upgrade) and sets up: the application in /opt/kraken-lcd, your configuration in /etc/kraken-lcd/config.toml (never overwritten), a dedicated kraken-lcd system user with a udev rule for device access, the systemd service with watchdog, and a suspend/resume hook.

journalctl -u kraken-lcd -f          # watch it run
sudo systemctl stop kraken-lcd       # stop (hands the LCD back to firmware)
sudo ./install.sh --uninstall        # remove (keeps your /etc config)

Running from the checkout without installing works too:

python3 -m kraken_lcd status         # sensors + device
python3 -m kraken_lcd render --liquid 40   # render tiles to ./preview, no device
python3 -m kraken_lcd run            # foreground carousel (Ctrl-C resets the LCD)
python3 -m kraken_lcd reset          # back to the firmware liquid screen

Configuration

Everything lives in one commented file: /etc/kraken-lcd/config.toml (falls back to the checkout's config.toml; --config overrides). Restart the service after changes.

• Tiles: carousel.screens selects and orders the display.
• Backgrounds: drop GIFs into the assets directory (liquid.gif, cpu.gif, gpu.gif, temp.gif by default, or point any tile at any file via [screens.<name>] background = "..."). Changes are picked up automatically — the cache tracks file identity. The shipped backgrounds are generated by scripts/generate_backgrounds.py; tweak its color schemes and rebuild your own.
• Styling: [screens.<name>] overrides label, color = "#RRGGBB", vertical positions and per-tile colors/max_frames (file-size tuning for noisy backgrounds).
• Cooling: [cooling] sets a fixed duty or a curve for pump and fan. Note: this replaces the firmware's default curve persistently (NZXT CAM can restore it).

Troubleshooting

Black display / service failed → journalctl -u kraken-lcd -n 50.

"Kraken is stuck in bootloader mode (USB 1e71:3011)": the device wedged (typically caused by the stock driver's upload behavior this project exists to avoid). Recovery: shut down, cut standby power for ~30 s (PSU switch off or unplug — a reboot is not enough), boot. The service intentionally stays stopped while a bootloader is detected (exit code 78) and starts normally on the next boot.

No device found: lsusb | grep 1e71 must show one of the supported IDs. Stop NZXT CAM / CoolerControl (Conflicts=coolercontrold.service is declared by the unit).

"driver patch disabled itself" in the log: your liquidctl version changed the code the patch targets — everything keeps working on the stock driver, with occasional screen flashes during memory cleanup. If a liquidctl release fixes #774 upstream, this is expected and fine.

GPU tile missing: needs a working nvidia-smi or the amdgpu kernel driver; without either the tile is skipped silently.

Development

python3 -m pytest      # 160 tests, no hardware required

Firmware behavior notes (bucket protocol, bootloader wedge) are in docs/firmware-notes.md.

License

GPL-3.0-or-later — see LICENSE. The patched upload path in kraken_lcd/driver_patch.py is derived from liquidctl's GPLv3 KrakenZ3 driver.

This project is not affiliated with or endorsed by NZXT. "Kraken" is a product name of NZXT, used here to describe compatibility.