This project provides a WebSocket-based LED Matrix Application that can display content on RGB LED matrices. The application is designed to run on Raspberry Pi hardware or locally using a preview renderer for development purposes.

Features

WebSocket communication for real-time control
RGB LED matrix support via rpi-rgb-led-matrix library
Local development with preview support
Docker containerization for easy deployment
Poetry-based dependency management

Development Setup

Prerequisites

Docker and Docker Compose
Python 3.11+ (for local development)
Poetry (for dependency management)

Docker Compose Development Environment

The easiest way to develop is using Docker Compose, which provides a complete development environment:

Start the development container:
```
docker-compose up -d
```

Access the container shell:

docker-compose exec led-matrix-dev bash

Run the application inside the container:

poetry run python3 led_matrix_application/main.py

Stop the development environment:
```
docker-compose down
```

Local Development (without Docker)

Install Poetry (if not already installed):

curl -sSL https://install.python-poetry.org | python3 -

Install dependencies:
```
cd src
poetry install
```

Run the application:

poetry run python3 led_matrix_application/main.py

Production Deployment

Pulling the Docker Image

To pull the latest Docker image from the GitHub Container Registry (GHCR):

docker pull ghcr.io/starappeal/led-matrix-application-websocket:latest

Running on Raspberry Pi

When running on a Raspberry Pi, you must run the container as privileged to access hardware resources:

docker run \
    -d \
    --privileged \
    --network host \
    --env-file /home/pi/led-matrix.env \
    -v /run/dbus:/host/run/dbus:ro \
    --name led-matrix-app \
    --restart unless-stopped \
    ghcr.io/starappeal/led-matrix-application-websocket:latest

(You can also use podman instead of docker)

Running the Preview Server

Run the preview server locally to stream frames to the UI:

cd src
poetry run python -m led_matrix_application.preview.preview_server

Preview Rendering

The preview server now uses an isolated numpy-backed renderer per session. This avoids shared global state and allows multiple preview sessions in parallel.

Preview uses PreviewDisplay (no emulator required)
Hardware still uses HardwareDisplay
Frames are accessed via MatrixDisplay.get_frame() for WebSocket streaming

Configuration

Environment Variables

Create a .env file with your configuration. You can use the provided .env.example as a template:

cp .env.example .env

Then edit the .env file with your actual values:

WEBSOCKET_URL: The URL of the WebSocket server the application will connect to
JWT_TOKEN: The JWT token used for authentication

Example Configuration

See .env.example for a complete configuration template with all available options and documentation.

Project Structure

led-matrix-application-websocket/
├── src/
│   ├── led_matrix_application/
│   │   ├── main.py              # Application entry point
│   │   ├── controller/          # LED matrix controller logic
│   │   ├── ws/                  # WebSocket client implementation
│   │   ├── utils/               # Utility functions
│   │   └── fonts/               # Font files for text rendering
│   ├── pyproject.toml           # Poetry configuration
│   └── poetry.lock              # Locked dependencies
├── wheels/                      # Pre-built wheels (for Raspberry Pi)
├── Dockerfile                   # Production Docker image
├── Dockerfile.dev               # Development Docker image
├── docker-compose.yml           # Development environment
└── README.md                    # This file

Dependencies

Python 3.11+: Core runtime
websockets: WebSocket client communication
Pillow: Image processing for LED matrix
python-dotenv: Environment variable management
rpi-rgb-led-matrix: Hardware interface for RGB LED matrices

Troubleshooting

Common Issues

Permission errors on Raspberry Pi: Ensure the container runs with --privileged flag
WebSocket connection issues: Verify WEBSOCKET_URL and JWT_TOKEN are correct

Debugging

Check container logs: docker logs <container_id> or docker-compose logs
Access development container: docker-compose exec led-matrix-dev bash
Run with verbose logging by setting appropriate log levels in the application

Development Tips

Use the Docker Compose setup for consistent development environment
The development container includes volume mounts for live code reloading