English | Deutsch
A modular display system for HUB75 LED panels on the Raspberry Pi.
Build your own modules – clocks, countdowns, crypto tickers, animations – and let them run seamlessly one after another.
Real panels, real time: the Christmas countdown and two clock styles playing one after another.
Get your matrix into the holiday mood: a twinkling garland, a tree with a glowing star, gently falling snow – and a big countdown to Christmas Eve. On Christmas Eve it switches to a colorful greeting, and after the holidays it starts counting towards the next Christmas by itself.
It speaks your language – English, German, French and Spanish are built in:
Add it to your config/config.yaml:
language: de # en, de, fr, es
modules:
- type: christmas
duration: 15
hour: 18 # Christmas Eve at 18:00, 0 = midnight
snow: 40 # number of snowflakes, 0 = no snowYour own words? Every text can be replaced right in the config – see Languages.
Counting down to your next trip? A ship appears on the horizon, comes closer and crashes right into the countdown – the time bursts into hundreds of pixels. The ship drags them along in its wake and drops them into place: your trip details. Sky, clouds and waves move all the time.
- type: voyage
date: "2027-06-01 00:00" # departure: "YYYY-MM-DD" or "YYYY-MM-DD HH:MM"
lines: # shown after the ship, 1-4 lines
- "My Cruise"
- "Caribbean"
- "Miami - Miami"
ship_speed: 1.0 # 2.0 = twice as fast, 0.5 = half as fast
hold: 6 # seconds the lines stay once they are complete
palette: blue # red, orange, gold, green, cyan, blue, purple, pink
# ship: private/my_ship.png # optional, your own ship picture (transparent PNG)
finale: # optional: GIFs or pictures after the lines
- file: examples/star.gif # a GIF without hold runs once
- file: examples/cruise_ship.png
hold: 3 # a picture stays this many seconds
transition: fade # fade or fade_black
transition_time: 1.5 # seconds, comes on top of the holds| Option | Meaning |
|---|---|
date |
departure – the countdown runs until then |
lines |
your trip details after the ship, 1–4 lines |
ship_speed |
speed of the ship – the whole scene gets shorter or longer with it |
hold |
seconds the trip details stay on screen |
palette |
color set for all texts: red, orange, gold, green, cyan, blue, purple, pink |
title_color, days_color, time_color, line_colors |
single colors, they win over the palette |
ship |
your own ship as a transparent PNG – default is the included examples/cruise_ship.png |
finale |
list of GIFs or pictures shown after the trip details – each entry has file, optional hold (seconds) and fit (contain, cover, stretch) |
transition |
how the parts of the finale blend into each other: fade or fade_black |
transition_time |
seconds for each transition – they come on top, every part stays fully visible for its time |
Turn any video you are allowed to use into a GIF that fits the matrix – with ffmpeg:
sudo apt install -y ffmpeg
ffmpeg -ss 69 -to 84 -i private/my_video.mp4 \
-vf "fps=20,crop=iw*0.75:iw*0.375,eq=contrast=1.35:saturation=1.7:gamma=1.4,scale=128:64:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" \
private/clip.gif| Part | What it does |
|---|---|
-ss 69 -to 84 |
cut from second 69 to 84 |
fps=20 |
20 frames per second are plenty for the panels and keep the file small |
crop=iw*0.75:iw*0.375 |
cut out the middle in the matrix ratio 2:1, 75 % of the video width – smaller values zoom in more |
eq=… |
more contrast and color, lighter dark tones – they disappear on LEDs otherwise |
scale=128:64 |
your display size (cols × chain_length by rows × parallel) |
palettegen / paletteuse |
picks the best 256 colors for this clip – no color stripes |
Then add - file: private/clip.gif to the finale.
Tip
Need a different ship? Use your own picture with ship: (keep pictures you are not allowed
to share in private/) – or open an issue
and describe the ship you would like to see.
Not a single script, but a small platform: the system takes care of hardware, timing and playback. You only write modules that define what is shown. Everything that depends on your hardware lives in one config file – so the same code runs on any panel size, chain length or wiring.
flowchart LR
A[Modules<br/>Clock · Countdown · Crypto · GIF …] --> B[Scheduler<br/>order & duration]
E[config.yaml] --> A
E --> B
B --> C{Frame hub}
C --> D[LED panels<br/>via rpi-rgb-led-matrix]
C --> F[Web interface<br/>live picture · status · no hardware needed]
Watch your matrix from any browser in your home network – PC, tablet or phone. It runs next to the panels, or completely without any hardware.
- Live – the picture on the panels as glowing LEDs: LED size, glow, round or square LEDs, screenshot, fullscreen and the pixel coordinate under the mouse
- On screen now – which module is running, how long it still takes, real frames per second
- Modules – every module of your config, on or off, with its options (colors as swatches)
- Hardware – the matrix (display size, panels, chains, brightness, wiring) and the host it runs on: model, CPU, temperature, memory, storage, uptime and IP address – bars turn orange and red when it gets tight
- Design – system, light or dark; the texts follow
language(en, de, fr, es) - API – JSON at
/api/status,/api/config,/api/modules,/api/host– for other devices and scripts. The running program describes it itself: openhttp://<IP of your Pi>:8080/api/docs(an interactive page made by FastAPI, not a file in the repository)
The web interface is optional: install it with pip install -e ".[web]" (FastAPI, uvicorn and psutil),
switch it off with web: {enabled: false} in the config.
Important
The web interface has no password and is meant for your home network. From outside, use a VPN (for example the one of your router) – never open a port for it in your router.
No Pi, no panels? Everything runs on your PC (Windows, macOS, Linux) – modules, timing and the web interface, exactly like on the Pi. Only no panels are driven. Perfect for building your own modules before you buy anything. You need Python 3.11 or newer.
git clone https://github.com/gerry-git-ops/Waveshare-P2.5-LED-Matrix.git
cd Waveshare-P2.5-LED-Matrix
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[web]"
cp config/config.example.yaml config/config.yaml # Windows: copy config\config.example.yaml config\config.yaml
ledmatrix-previewThen open http://localhost:8080.
Tested on a Raspberry Pi 4 with Raspberry Pi OS Lite (64-bit), Python 3.13.
sudo apt update
sudo apt install -y git build-essential python3-dev python3-venv cython3The built-in sound of the Pi uses the same hardware as the LED library and causes trouble.
echo "blacklist snd_bcm2835" | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
sudo rebootcd ~
git clone https://github.com/hzeller/rpi-rgb-led-matrix.git
git clone https://github.com/gerry-git-ops/Waveshare-P2.5-LED-Matrix.git
cd Waveshare-P2.5-LED-Matrixpython3 -m venv --system-site-packages .venv
source .venv/bin/activate
pip install ~/rpi-rgb-led-matrix # Python bindings of the LED library (takes a few minutes)
pip install -e ".[web]" # this project with web interface
# or: pip install -e . # without web interfacecp config/config.example.yaml config/config.yamlAdjust config/config.yaml to your panels – see Configuration.
sudo .venv/bin/python -m ledmatrix # panels + web interface (needs root for GPIO)Open the web interface at http://<IP of your Pi>:8080 – the IP is shown by hostname -I.
Stop with Ctrl+C.
Tip
Working on the Pi over VS Code Remote-SSH? VS Code forwards port 8080 automatically –
just click Open in Browser. With plain SSH: ssh -L 8080:localhost:8080 user@your-pi
No Pi yet? See Try it without hardware.
All settings live in config/config.yaml. Your own file is ignored by Git,
the template config.example.yaml is part of the repository.
hardware:
rows: 32 # pixel rows per panel
cols: 64 # pixel columns per panel
chain_length: 2 # panels per chain
parallel: 2 # parallel chains (1-3)
hardware_mapping: regular # GPIO mapping, see rpi-rgb-led-matrix
gpio_slowdown: 4 # higher = slower, needed on faster Pis
rgb_sequence: RBG # color order of your panels
brightness: 50 # 0-100
fps: 30 # frames per second
language: en # en, de, fr, es – missing texts fall back to English
web: # optional, these are the defaults
enabled: true # web interface (needs: pip install -e ".[web]")
port: 8080
modules: # played in this order, then from the start
- type: clock
duration: 5 # seconds
color: [0, 150, 255]
fmt: "%H:%M:%S"
- type: christmas
duration: 15
hour: 18The display size is calculated from the hardware section:
width = cols × chain_length, height = rows × parallel (here 128 × 64).
Important
The hardware section must match the panels that are actually connected. If it doesn't, panels show copies of the image or flicker.
Every module entry needs a type. Optional for every module:
| Key | Meaning |
|---|---|
enabled |
false switches the module off without deleting it (default: true) |
duration |
seconds on screen – if left out, the module decides itself (e.g. scrolltext by its loops) |
All other keys are handed to the module as options.
language sets the language for all modules. Built in: English (en), German (de),
French (fr) and Spanish (es). If a text is missing in your language, English is used –
nothing breaks.
Change single texts directly in the config, no code needed. Just use the text key of the module:
- type: christmas
title: "Only" # instead of "Christmas in"
done: "Ho ho ho!" # instead of "Merry Christmas!"| Module | Text keys |
|---|---|
christmas |
title, days, day, done |
countdown |
title, days, day, done |
voyage |
title, days, day, trip (end line if no lines are set) |
scrolltext |
text |
Your language is missing? Add it to the texts of the module (see
Build your own module) and open a pull request – contributions are very welcome.
| Module | Description | Options | Status |
|---|---|---|---|
clock |
Digital clock, scales itself to the display | color, fmt (strftime) |
✅ |
christmas |
🎄 Countdown to Christmas Eve with garland, tree and snow | hour, snow, texts |
✅ |
scrolltext |
Scrolling text in one color or rainbow, runs a set number of times | loops, speed, size, color, rainbow, text |
✅ |
countdown |
Days and time left until any date, with a message once it is reached | date, title_color, days_color, time_color, texts |
✅ |
gif |
Plays an animated GIF a set number of times | file, fit, speed, loops |
✅ |
voyage |
🚢 A ship crashes into the countdown and drags your trip details into place | see above | ✅ |
| Crypto ticker | Prices via web API, with history | idea |
scrolltext with rainbow: true – it runs through completely loops times, then the next module follows.
- type: scrolltext
loops: 2 # how often the text runs through completely
speed: 40 # pixels per second
size: 0.6 # text height, share of the display height
rainbow: true # or: color: [255, 255, 255]
# text: "Your own text" # optional, replaces the translated default textNote
Leave out duration for scrolltext – otherwise it overrides the loops.
- type: countdown
duration: 10
date: "2027-01-01 00:00" # "YYYY-MM-DD" or "YYYY-MM-DD HH:MM"
title: "Holiday in" # optional, replaces the translated title
done: "Have fun!" # optional, shown once the date is reached - type: gif
file: examples/star.gif # path from the project folder
fit: contain # contain, cover or stretch
speed: 1.0 # 2.0 = twice as fast
loops: 3 # how often the animation plays completelyNote
Only use GIFs you are allowed to use. Your own GIFs are best kept in the private/ folder –
it is ignored by Git.
Modules don't have to start from scratch: widgets are small building blocks that each draw one thing into an area you give them. A module just puts them together – back to front.
| Widget | Draws | Options |
|---|---|---|
ScrollingText |
text moving from right to left | text, color, rainbow, speed, size |
Gif |
an animated GIF or a still image | path, fit, speed |
Snow |
falling snowflakes | count, color |
Countdown |
days and time left until a moment | target, day, days, days_color, time_color |
Sky |
sky with a color gradient and drifting clouds | clouds, top, bottom |
Water |
water with moving waves | back, front |
Particles |
bursts an image into pixels and gathers them into another one | gravity, drag |
The built-in modules are made of them, too: scrolltext is one ScrollingText,
gif is one Gif, countdown is one Countdown, christmas uses Snow and Countdown,
and voyage puts Sky, Water, Countdown and Particles together.
Example – a star with falling snow and a rainbow text in the bottom row:
from PIL import Image
from ledmatrix.modules.base import Module
from ledmatrix.widgets.media.gif import Gif
from ledmatrix.widgets.text.scrolling_text import ScrollingText
from ledmatrix.widgets.effects.snow import Snow
class StarNight(Module):
"""A star with falling snow, and a scrolling text below."""
texts = {
"en": {"text": "Good night!"},
"de": {"text": "Gute Nacht!"},
}
def __init__(self, width: int, height: int, **kwargs) -> None:
super().__init__(width, height, **kwargs)
text_h = height // 4 # bottom quarter for the text
self.snow = Snow(width, height - text_h, count=30)
self.star = Gif(width, height - text_h, "examples/star.gif")
self.scroller = ScrollingText(width, text_h, self.text("text"), rainbow=True, size=0.8)
self.duration = 2 * self.scroller.pass_time() # two runs of the text
def start(self) -> None:
self.snow.start()
def render(self, t: float) -> Image.Image:
img = Image.new("RGB", (self.width, self.height))
text_y = self.height - self.scroller.height
self.star.draw(img, 0, 0, t) # back
self.snow.draw(img, 0, 0, t) # middle
self.scroller.draw(img, 0, text_y, t) # bottom row
return imgdraw(img, x, y, t) paints the widget at position x, y, every widget only within its own size.
What is drawn first lies in the back.
A module is a small Python class: it gets the display size and returns one image per frame.
t is the time in seconds since the module became active – perfect for animations.
1. Create src/ledmatrix/modules/bounce.py:
"""A dot moving from left to right."""
from PIL import Image, ImageDraw
from ledmatrix.modules.base import Module
class Bounce(Module):
def __init__(self, width: int, height: int, color=(255, 0, 80), **kwargs) -> None:
super().__init__(width, height, **kwargs)
self.color = tuple(color)
def render(self, t: float) -> Image.Image:
img = Image.new("RGB", (self.width, self.height))
x = int(t * 40) % self.width
y = self.height // 2
ImageDraw.Draw(img).ellipse((x - 3, y - 3, x + 3, y + 3), fill=self.color)
return img2. Register it in src/ledmatrix/modules/__init__.py:
from ledmatrix.modules.bounce import Bounce
REGISTRY = {
"clock": Clock,
"bounce": Bounce,
}3. Add it to your config/config.yaml:
- type: bounce
duration: 8
color: [255, 0, 80]Check it with python -m ledmatrix --preview – done.
Tip
Always calculate with self.width and self.height, never with fixed numbers –
then your module works on every panel setup.
Pass **kwargs on to super().__init__() – that's how your module gets the language.
Put your texts into texts and read them with self.text(...):
from PIL import Image, ImageDraw
from ledmatrix.fonts import fit_font
from ledmatrix.modules.base import Module
class Greeting(Module):
texts = {
"en": {"hello": "Hello!"},
"de": {"hello": "Hallo!"},
}
def render(self, t: float) -> Image.Image:
img = Image.new("RGB", (self.width, self.height))
font = fit_font(self.text("hello"), self.width - 4, self.height - 4)
ImageDraw.Draw(img).text((self.width / 2, self.height / 2), self.text("hello"),
font=font, fill=(255, 255, 255), anchor="mm")
return imgfit_font (from ledmatrix.fonts) finds the largest font size that fits – using the bundled
Inter font with full support for umlauts and accents.
Waveshare-P2.5-LED-Matrix/
├── config/
│ └── config.example.yaml template for your config.yaml
├── docs/ translations, roadmap, images
├── examples/ example files: star.gif, cruise_ship.png
├── src/ledmatrix/
│ ├── __main__.py entry point (python -m ledmatrix)
│ ├── colors.py color palettes
│ ├── config.py load and validate the config
│ ├── fonts.py font helpers (bundled Inter font)
│ ├── renderer.py output to the LED panels
│ ├── scheduler.py plays the modules one after another
│ ├── transitions.py blend one frame into another (fade, fade_black)
│ ├── modules/
│ │ ├── base.py base class for all modules (incl. translations)
│ │ ├── clock.py clock module
│ │ ├── christmas.py Christmas countdown
│ │ ├── countdown.py countdown to any date
│ │ ├── gif.py GIF player
│ │ ├── scrolltext.py scrolling text
│ │ └── voyage.py voyage countdown with ship
│ ├── widgets/ building blocks for modules
│ │ ├── base.py base class for all widgets
│ │ ├── effects/ moving effects
│ │ │ ├── particles.py burst an image into pixels and gather them again
│ │ │ └── snow.py falling snow
│ │ ├── media/ images and animations
│ │ │ └── gif.py animated GIF or still image
│ │ ├── scenery/ backgrounds
│ │ │ ├── sky.py sky with clouds
│ │ │ └── water.py water with waves
│ │ └── text/ text
│ │ ├── countdown.py days and time left
│ │ └── scrolling_text.py scrolling text
│ ├── web/ web interface (optional extra)
│ │ ├── hub.py passes every frame to the panels and the browser
│ │ ├── api.py JSON API and live stream (FastAPI)
│ │ ├── host.py details of the host: model, CPU, temperature, memory …
│ │ ├── server.py starts the web server next to the display
│ │ └── static/ the page
│ │ ├── index.html layout of the page
│ │ ├── style.css look: light and dark design
│ │ ├── led.js live picture as glowing LEDs
│ │ └── app.js menu, texts and data from the API
│ └── assets/fonts/ Inter font and its license
└── pyproject.toml project metadata and dependencies
- Raspberry Pi 4 (headless, via SSH)
- 4× Waveshare RGB-Matrix P2.5, 64×32 in a 2×2 grid → 128×64 pixels
- Driven by rpi-rgb-led-matrix, GPIO mapping
regular - Custom wiring via the GPIO header, two parallel chains of two panels each
- Separate 5 V power supply for the panels (Waveshare: up to 2.5 A per panel)
Wiring diagram and terminal plan will follow.
snd_bcm2835: found that the Pi sound module is loaded
The on-board sound is still active. Do step 2 and reboot.
make: No rule to make target 'build-python'
The Python bindings of rpi-rgb-led-matrix are built with pip since February 2026.
Use pip install ~/rpi-rgb-led-matrix inside the activated virtual environment.
ModuleNotFoundError: No module named 'ledmatrix' or 'rgbmatrix'
The virtual environment is not active – run source .venv/bin/activate.
With sudo, always use the Python of the venv: sudo .venv/bin/python -m ledmatrix.
The web interface needs the web extra or the page does not open
Install the extra: pip install -e ".[web]". Your PC or phone must be in the same network as the Pi –
use the IP from hostname -I and the port from the config (default 8080).
Image appears twice, flickers or panels stay dark
Check that chain_length and parallel match the panels that are really connected.
Wrong colors
Try another rgb_sequence (e.g. RBG, GRB). A red text must appear red, a green one green.
One chain only shows some rows (stripes)
An address line (A, B, C or D) is missing on that chain – check the wiring.
This project lives from ideas – yours are very welcome!
- 💡 An idea or a wish? Open an issue and describe it.
- 🧩 Need a special module? Describe what it should show – I'm happy to build modules on request.
- 🐞 Found a bug? Open an issue with what you did, what you expected and, if possible, a photo of the panels.
- 🔧 Built something yourself? A new module, widget or language – pull requests are welcome.
This project is licensed under the GNU General Public License v3.0.
It builds on rpi-rgb-led-matrix by Henner Zeller (GPL). The bundled font Inter is licensed under the SIL Open Font License 1.1.
What is planned and what is already running: ROADMAP













