Getting started

led-ticker drives RGB LED matrix panels from a Raspberry Pi via a TOML config — RSS, weather, custom messages, animated transitions, and more. One toolchain (Docker) covers everything: try it on your laptop with no hardware, then deploy the same image to a Pi when your panels arrive.

Not sure led-ticker is the right fit? → Why led-ticker?

You want…	Go to
Try it on your laptop, no hardware (2 min)	Quickstart A below
Deploy to a Pi with panels (~20 min)	Quickstart B below
Build a complete sign config from scratch, ready to deploy (no hardware needed, ~1 h)	the Tutorial

What you’ll need:

• A laptop (macOS, Linux, or Windows) for the laptop quickstart
• A Raspberry Pi + HUB75 panels + Adafruit HAT/Bonnet for the Pi deploy (HUB75 is the standard connector on hobbyist RGB LED matrix panels — the Amazon/AliExpress “RGB LED matrix” panels are HUB75.)
• Docker — the single tool that covers both

Step 1 — Install Docker

Linux / Raspberry Pi:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in (or: newgrp docker) for the group change to take effect.

macOS / Windows: install Docker Desktop.

docker compose v2 ships with modern Docker — the old standalone docker-compose command is not required.

Quickstart A — Try it on your laptop (no hardware)

~2 minutes, Docker only. You’ll see a browser tab showing your sign rendering live in a simulated panel — no hardware needed.

Open a terminal (Terminal on macOS; WSL or a package manager like Chocolatey/Scoop provides make on Windows), then:

# Check Docker is installed first:
docker --version

# Clone (downloads the repo) + start:
git clone https://github.com/JamesAwesome/led-ticker.git
cd led-ticker
make try   # make is a standard task runner, pre-installed on macOS/Linux

make try builds the image and starts a headless display engine plus the web UI — no panel, no Pi. Open http://localhost:8080 and click the live preview tab to see the sign rendering in your browser. Already have a config/config.toml? make try previews it instead of the bundled example.

Both of those are plugins baked into the try image: the scrolling Hacker News headlines come from the rss.feed widget, and the Nyan Cat sweep between sections is an animated transition — no API keys or .env needed (the headlines just need an internet connection). Browse the plugin catalog for weather, sports scores, crypto, calendars, and more. To try a different plugin, add its package to config/requirements-plugins.try.txt, reference its widget or transition in config/config.try.example.toml, then re-run make try. (On a real deploy it’s simpler still — edit config/requirements-plugins.txt and docker compose restart, no rebuild.)

To stop: press Ctrl-C, then run:

make try-down

Quickstart B — Deploy to your Pi

~20 minutes, hardware required.

Before you start

Your Pi should be running Raspberry Pi OS (Bookworm, 64-bit) with SSH enabled and you logged in — flash it with Raspberry Pi Imager if you haven’t. All commands below run on the Pi.

make setup seeds the smallsign starter config and won’t overwrite an existing config/config.toml — if you’re building a bigsign (or your own layout), copy your config example first (step 2) so the stack boots with the right one.

1. Clone the repo:

git clone https://github.com/JamesAwesome/led-ticker.git
cd led-ticker

2. Copy the right example config:

# Smallsign: Pi 4 + 5× 16×32 panels = 160×16 logical canvas
cp config/config.example.toml config/config.toml

# Bigsign: Pi 5 + 8× P3 32×64 panels = 256×64 logical canvas
cp config/config.bigsign.example.toml config/config.toml

Not sure which fits? See Choosing a sign size.

3. Run setup:

make setup

make setup checks Docker, seeds .env, builds the image, and brings the stack up. Run it once.

Most config changes (sections, widgets, schedule) take effect automatically within one playlist cycle — no restart needed. Hardware-level fields (chain_length, gpio_slowdown, default_scale) need make restart. restart: unless-stopped in compose.yaml brings the ticker back up on its own after power loss.

Check it worked: you should see the starter messages scrolling on the panels within about a minute (the first boot builds the Docker image — typically 10–20 minutes on a Pi 4; later boots are seconds). Watch progress with make logs; docker compose ps should show the service running. Panels still dark after the image is built? Check gpio_slowdown and start with the Sharp edges section on the building-your-own page. Once the web UI is enabled (step 5), its Status tab gives you a richer first-boot view — a live panel preview plus per-source health at a glance.

4. Panel bring-up — after wiring, run make panel-test to rule out any wiring, driver, or RGB-order problems. Before running panel-test, make sure config.toml has the correct [display] values for chain_length, rows, and cols — panel-test reads them. If your panels are a single horizontal chain (like the smallsign), panel-test is all you need. For a multi-row layout (like the bigsign or a custom grid), also run the panel-map workflow to derive the pixel_mapper_config Remap string for your panel layout.

5. Optional: web UI — add a [web] block to config.toml:

[web]
# defaults are fine; see the web-status-ui docs for options

Then start with the webui profile:

COMPOSE_PROFILES=webui docker compose up -d

Both parts are needed — the [web] block makes the display process publish, the profile starts the sidecar. See Web status UI for the full options. Open http://<pi-hostname>.local:8080 for a live dashboard, config editor, and plugin Store.

Edit your config

A config is a list of sections, each containing widgets and a mode (ticker, slideshow, or one_at_a_time). Before editing, skim Sections and modes and the message widget page — the two most-used building blocks.

Validate any config before deploying. On a deployed sign, the easiest way is the web UI’s Config tab (step 5 above) — it validates before saving. On a dev machine:

make validate CONFIG=config/config.toml

(make validate needs the dev dependencies — install uv and run make dev once first; make dev checks for uv and prints the install command if it’s missing.)

Private media (GIFs, images, fonts) goes in config/local/ (gitignored) and is referenced as path = "local/<file>" in your TOML.

Run without a Pi

For a live browser preview, use Quickstart A above. The render-demo tool is for iterating on configs at the command line and generating GIFs — it runs the real ticker engine against a software stub and writes each config to a GIF:

make dev       # install Python dev deps (requires uv)
make render-demo CONFIG=config/config.example.toml OUT=preview.gif
open preview.gif   # macOS; xdg-open on Linux

Next steps

• Build a config: Sections and modes → Widgets → Transitions
• Add plugins: Available plugins — RSS, weather, sports scores, crypto, calendars, and more
• Buy / build hardware: Building your own → Smallsign or Bigsign
• Reference: [display] and section knobs · CLI

See also

• tutorial/01-setup
• concepts/sections-and-modes
• hardware/building-your-own