PixelPush (codename)

Open-source frame server for HUB75 LED matrix displays. Renders Pixlet apps and serves raw pixels to microcontroller clients.

Architecture

┌─────────────────┐      HTTP       ┌──────────────────┐
│  Frame Server   │ ◄────────────── │  LED Matrix      │
│  (Python)       │   GET /frame    │  Client          │
│                 │ ───────────────►│  (MicroPython)   │
│  • Pixlet CLI   │   raw RGB       │                  │
│  • App rotation │   + headers     │  • Interstate 75W│
│  • Scheduling   │                 │  • Matrix Portal │
└─────────────────┘                 │  • ESP32, etc    │
                                    └──────────────────┘

Quick Start

Prerequisites

1. Install Pixlet CLI:

   # macOS
   brew install tidbyt/tidbyt/pixlet
   
   # Linux/other - see Pixlet docs

2. Install Python dependencies:

   cd server
   pip install -r requirements.txt

Run the Server

Option A: Docker (recommended for deployment)

docker compose up -d

Option B: Local Python

cd server
python server.py

Server starts at http://localhost:8080

• GET / - Health check / info
• GET /frame - Raw RGB pixels + metadata headers
• GET /frame/preview - PNG preview (8x scaled, for debugging)

Protocol

Clients fetch GET /frame and receive:

Headers:

• X-Frame-Width - Display width (e.g., 64)
• X-Frame-Height - Display height (e.g., 32)
• X-Frame-Count - Number of animation frames
• X-Frame-Delay-Ms - Milliseconds per frame
• X-Dwell-Secs - How long to show this app
• X-Brightness - 0-100
• X-App-Name - Current app name

Body: Raw RGB bytes (width × height × 3 × frame_count)

Configuration

Edit server/config.yaml:

display:
  width: 64
  height: 32
  brightness: 80

apps:
  - name: clock
    path: "../apps/clock.star"
    duration: 10

Adding Apps

1. Find or write a .star file (see Pixlet docs or community apps)
2. Put it in apps/
3. Add to config.yaml

Clients

• clients/interstate75w/ - Pimoroni Interstate 75W (MicroPython)
• More to come...

Docker Deployment

For running on a server (Proxmox, NAS, etc.):

# Clone and start
git clone https://github.com/johnfernkas/pixelpush.git
cd pixelpush
docker compose up -d

# View logs
docker compose logs -f

# Restart after config changes
docker compose restart

Volumes:

• apps/ — Add/edit .star files without rebuilding
• server/config.yaml — Edit config without rebuilding

Project Structure

pixelpush/
├── docker-compose.yml  # Docker orchestration
├── server/
│   ├── Dockerfile      # Container build
│   ├── server.py       # Flask HTTP server
│   ├── pixlet.py       # Pixlet CLI wrapper
│   ├── config.yaml     # App configuration
│   └── requirements.txt
├── clients/
│   └── interstate75w/  # MicroPython client
├── apps/               # Pixlet .star apps
│   ├── clock.star
│   └── hello.star
└── README.md

License

TBD