trccd - a lightweight daemon for controlling Thermalright LCD displays

trccd is a lightweight solution for controlling Thermalright LCD displays found on AIO coolers such as the Frozen Warframe series. It uses libusb and ffmpeg to process and stream images or videos (or just a solid colour) directly to the screen.

Key Features

• Easy to use: Just point trccd at your media and it uses ffmpeg under the hood to automatically scale, crop and convert it to fit the display.
• Automatic caching: Processed media is cached to disk on the first run. Each subsequent run will begin playing the media instantly by loading from the cache.
• systemd integration: Designed to run in the background as a systemd service. The service unit is started automatically by systemd-udevd when the device is detected.
• Security: The service unit file makes extensive use of systemd sandboxing features (see systemd.exec(5)#SANDBOXING) to run the daemon as a dynamic user with stripped capabilities. A custom udev rule grants access to the USB device via the tr_display group.
• Lightweight: Written in pure C with performance and efficiency in mind. The Linux page cache is used to keep as much of the media in memory as possible without exhausting system RAM and the program will loop the media with as few USB transfers as it can manage. For static images and solid colours this uses very little CPU time.
• Pipe in your own data: Arbitrary data can be read from stdin so you can experiment with your own ffmpeg commands or use a different program to process your media.

Supported Devices

Vendor	Product	VID:PID
Winbond Electronics Corp.	USBDISPLAY	0416:5302

Only the device above is currently supported. If you own a Thermalright product that isn't supported and you're willing to help test, please create an issue and we can try to add support.

Tip

Run lsusb to find the name of your device.

Installation

From Source

Dependencies

• gcc >= 16 or clang >= 21
• make
• libusb
• pkg-config
• ffmpeg (not required if you only plan to pipe in pre-processed data)

Clone the repository and build with make:

git clone https://github.com/Jontos/trccd.git
cd trccd
make

Install to your system with:

sudo make install
sudo systemd-sysusers
sudo systemctl daemon-reload
sudo udevadm control --reload
sudo udevadm trigger

If the device is already plugged in udevadm trigger will automatically start the systemd service. See usage for instructions on adjusting this behaviour.

Note

Currently only tested on Arch Linux. If you run into problems on a different distro, please create an issue.

trccd can be uninstalled with:

sudo make uninstall

This won't remove the configuration file, which must be removed manually.

Usage

When running as a systemd service, trccd can be configured by editing the values in the trccd.conf file. Set the path to your media like so:

MEDIA=/etc/trccd/my_video.mkv

The OPTIONS= variable can be used to pass command line flags to trccd:

MEDIA=/path/to/my_media
OPTIONS=--mode video

Tip

The location of the trccd.conf file will differ depending on how you installed trccd. Use systemctl show -P EnvironmentFiles trccd to query its location.

Restarting the service will pick up new config changes:

sudo systemctl restart trccd

Important

The path used for MEDIA must be readable by the dynamic user created by systemd; this user cannot read files inside your home directory. Copy your media somewhere globally readable (e.g. in the same directory as the trccd.conf file) and specify that instead.

The service can be manually stopped or started with the below commands:

sudo systemctl stop trccd

sudo systemctl start trccd

Mask the systemd service if you want to prevent it from being automatically started by systemd-udevd:

sudo systemctl mask trccd

It can be unmasked with:

sudo systemctl unmask trccd

Command Line Usage

trccd can also be run manually:

trccd [OPTION]... {FILE|COLOUR}

Where FILE is either the path to the media you want to display or - for standard input, and COLOUR is either an X11 colour name (see colour_names.h for the full list) or an RGB565 colour value in hexadecimal format (e.g. 0xF800 for red).

Here's an example of how you can pipe data into trccd via standard input:

ffmpeg -nostdin \
    -loglevel fatal \
    -i /path/to/my_media.mkv \
    -an -sn \
    -vf "scale=320:240:force_original_aspect_ratio=increase,crop=320:240,transpose=1,fps=22" \
    -f rawvideo \
    -pix_fmt rgb565le - | trccd --mode video -

Note

The command above is what trccd runs internally for video mode.

Data can also be fed in from a file using shell redirection:

trccd --mode video - < rgb565_bytes.bin

Note

Data piped/redirected into trccd this way is not cached to disk.

Caching

The first time you play a media file, trccd runs ffmpeg to convert it and writes the processed frames to disk. Subsequent runs with the same media will map those cached frames into memory, avoiding redundant calls to ffmpeg and reducing start-up time.

Cache location

• Under systemd: /var/cache/private/trccd.
• When run manually: $XDG_CACHE_HOME/trccd or $HOME/.cache/trccd if $XDG_CACHE_HOME is empty or unset.

It's safe to delete these directories to wipe the cache. For the systemd service, the cache can be wiped by running this command when the service is stopped:

sudo systemctl clean trccd

Caveats

• Available disk space is not checked before caching the media to disk.
• Media is saved in an uncompressed format. One frame is 153.6 kilobytes, so one second of video at 22 FPS will be ~3.4MB; keep this in mind if you plan to watch any movies on your CPU cooler.

Licence

This project is licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the COPYING file for details.