TRMNL Display is a lightweight, Linux command line application designed to display dynamic images directly on both framebuffer (LCD/HDMI) and SPI e-paper displays like the one in the TRMNL OG. It fetches images from the TRMNL API (or your own self-hosted server) and renders them directly to either a framebuffer or e-paper, providing a seamless display experience without requiring a traditional desktop environment.

• Direct framebuffer or e-paper image rendering.
• Supports JPEG, PNG, and BMP image formats.
• 1-bit images support optional dark mode inversion.
• Configurable refresh rates.
• Easy configuration through environment variables or interactive prompts.

• Linux SBC (Raspberry Pi, Orange Pi, etc)
• Go 1.24 or higher (minimum version required)
• framebuffer-enabled display
• or e-paper display with SPI connection
• Internet connection for fetching images

Clone the repository:

git clone https://github.com/usetrmnl/trmnl-display.git
cd trmnl-display

Run the provided build.sh script:

./build.sh

You'll see a message:

Select your display device:
  1) framebuffer (HDMI/LCD)
  2) Waveshare e-paper HAT
  3) Pimoroni Inky Impression Spectra 7.3"

Input "1" or "2" or "3", then press enter. The script will complete with the following:

Compiling TRMNL go program...
Build complete. Run trmnl-display to start.

Navigate to wherever you cloned the trmnl-display repository.

Run the application:

./trmnl-display

On the first run you'll be asked to provide your Device API Key. If you're using TRMNL's native application at usetrmnl.com, go to https://usetrmnl.com/devices/current/edit and find the key under the Developer Perks section.

If you're using a BYOS solution, find your API key from that implementation's settings screen. You will also need to change the base_url to point to your server. See Configuration for more details.

To skip to the next item in your playlist, press the enter key.

Keypress...skipping to next update
Displayed: /tmp/trmnl-display3898330261/plugin-b67875-1763221411
EPD update completed

Optional flags:

• Enable dark mode (inverts all pixels):

./trmnl-display -d

Navigate to wherever you cloned the trmnl-display repository.

Run the application:

nohup ./trmnl-display &

This lets you escape the command (ctrl+c) and close your session without terminating the script.

Background + Automatic Reboot

To restart trmnl-display whenever your device is turned on, access your crontab editor with crontab -e. You may be required to set an editor (1, 2, 3), then press enter.

crontab -e
no crontab for trmnl - using an empty one
Select an editor.  To change later, run select-editor again.
  1. /bin/nano        <---- easiest
  2. /usr/bin/vim.tiny
  3. /bin/ed

Choose 1-3 [1]:

Inside your crontab, paste the following command. Change the path (if applicable) to point to your trmnl-display Installation location:

@reboot sleep 15 && nohup /home/$(whoami)/Desktop/trmnl-display/./trmnl-display > /home/$(whoami)/.config/trmnl/logfile.log 2>&1 &

The sleep 15 intends to ensure your network configuration is ready before trmnl-display makes an HTTP request to your playlist.

Confirm this works by running sudo reboot, which should momentarily trigger an automatic screen refresh.

TRMNL Display by default stores the following two configuration files in:

~/.config/trmnl/config.json
~/.config/trmnl/show_img.json

config.json stores your Device API Key and other preferences. You may also need to provide your MAC address with key device_id for BYOS clients that require it to be paired with an API Key in the request headers.

show_img.json stores the configuration for your e-paper or framebuffer display device. It will be created during Installation (one of the final steps in build.sh).

TRMNL Display is licensed under the MIT License. See LICENSE for details.

Contributions are welcome! Please open an issue or pull request on GitHub.