matrix_display

CLI tool to display terminal output on an LED wall

🎥 Demo video

---

Hardware

• Pixlite 16 Mk2
• LED strips
• Aluminium profile
• 3-wire cable
• 3-pin connectors
• Brackets (3d-printed)

Note: you could make this significantly cheaper by designing your own LED driver board (which is left as an exercise to the reader).

Installation

1. Clone the repo:

git clone git@github.com:maksimdrachov/matrix_display.git ~/matrix_display

2. Create a symlink that is on your PATH:

ln -s ~/matrix_display/matrix_display ~/.local/bin/matrix_display
ln -s ~/matrix_display/matrix_display_cyphal ~/.local/bin/matrix_display_cyphal

Make sure ~/.local/bin is on your PATH.

3. Create a ~/.matrix_display config file:

[[display]]
target_display = "maksim"
controller_ip = "192.168.1.201"

[[display]]
target_display = "meeting_room"
controller_ip = "192.168.1.202"

4. Send a message:

echo "Some message" | matrix_display --target maksim

To use the PyCyphal daemon, install the optional UDP dependencies:

python3 -m pip install -e 'pycyphal2[udp]'

Usage

matrix_display reads a message from standard input, renders it with a built-in bitmap font, and sends the corresponding Art-Net frames directly to the PixLite controller.

If the rendered message fits within 118 pixels, it is centered. If it is wider than 118 pixels, it scrolls once and then leaves the last visible slice on screen. The PixLite is expected to be configured to hold the last received frame.

If you prefer not to install anything, this also works:

PYTHONPATH=src python3 -m matrix_display

Use --target or -t to select which configured display to send to:

some_command | matrix_display --target maksim
some_command | matrix_display -t maksim

ANSI color sequences in stdin are supported. For example:

printf '\033[31mRED \033[32mGREEN\033[0m\n' | matrix_display -t maksim

PyCyphal Daemon

matrix_display_cyphal runs a background subscriber that listens for UTF-8 text messages and sends them to the same renderer/controller path used by the terminal CLI.

matrix_display_cyphal --target maksim

By default, this creates a PyCyphal/UDP node with home matrix_display_<target> and subscribes to ~/text. For --target maksim, the resolved topic is matrix_display_maksim/text, matching a daemon configured as:

node = Node.new(UDPTransport.new(), home="matrix_display_maksim", namespace="")
sub = node.subscribe("~/text")

You can override the Cyphal settings if needed:

matrix_display_cyphal --target maksim --home matrix_display_maksim --topic '~/text'

Example Usage

Display the current time in 24-hour format once a second:

#!/bin/sh

while true; do
  date '+%H:%M:%S' | matrix_display -t maksim
  sleep 1
done

Watch the latest GitHub Actions run and display a green or red result when it finishes:

#!/usr/bin/env bash

if gh run watch --exit-status; then
  printf '\033[32mPASSED\033[0m\n' | matrix_display -t maksim
else
  printf '\033[31mFAILED\033[0m\n' | matrix_display -t maksim
fi

Display a very long scrolling ZUBAX banner and refresh it every few minutes after the scroll has finished:

#!/bin/sh

text=$(printf 'ZUBAX %.0s' $(seq 1 100))

while true; do
  printf '\033[31m%s\033[0m\n' "$text" | matrix_display -t maksim
  sleep 2m
done

Development

LedController maps the matrix rows to 10 Art-Net universes, one per output:

• OUT1 -> row 0 -> universe 1
• OUT2 -> row 1 -> universe 2
• ...
• OUT10 -> row 9 -> universe 10

Each output carries 118 RGB pixels (354 DMX channels). Rows are mirrored during serialization so logical column 0 appears on the left edge of the physical display.

Testing

Run the unit tests:

PYTHONPATH=src python3 -m unittest discover -s tests -t .

Display the calibration frame on the controller at 192.168.1.201:

MATRIX_DISPLAY_RUN_HARDWARE_TESTS=1 PYTHONPATH=src python3 -m unittest tests.test_calibration

For the calibration test only, you can override the target universes with MATRIX_DISPLAY_UNIVERSES=1,2,3,4,5,6,7,8,9,10 and the controller IP with MATRIX_DISPLAY_TARGET_IP=192.168.1.201.