MateLight Emulator

An open-source emulator for the Matelight CRAP protocol. This project allows you to develop and test Matelight applications locally without physical hardware, and also serves as a bridge to forward display content to real Matelight devices.

About Matelight

Matelight is a collaborative drawing installation consisting of multiple physical LED panels arranged in a grid. The official Matelight protocol (CRAP) defines how pixel data is transmitted over UDP to the physical devices.

Features

• Local Development: Run Matelight visualizations directly in your browser
• Hardware Bridge: Forward display content to physical Matelight hardware via UDP
• Multi-page UI: Editor, terminal view, games gallery, and more
• Python Visualizers: Multiple demo patterns and creative coding examples
• Real-time Sync: WebSocket server for client-server communication
• API Integrations: Built-in support for c-base APIs (ctatus, cbeam)

Quick Start

Prerequisites

• Node.js 14.x or higher
• npm (comes with Node.js)

Installation

git clone https://github.com/jaseg/matelightemu.git
cd matelightemu
npm install

Running the Emulator

node app.js

The server will start on http://localhost:8080 and listen for UDP traffic on port 1337.

Setting Up Secrets

Copy the example secrets file and configure your credentials:

cp secrets.example.json secrets.json
# Edit secrets.json with your credentials

Note

: secrets.json is already in .gitignore and should never be committed!

Project Structure

matelightemu/
├── app.js                    # Main Node.js server (UDP + WebSocket)
├── index.html                # Landing page / redirect
├── editor.html               # Pixel editor interface
├── play.html                 # Animation player
├── games.html                # Gallery of game demos
├── screensaver.html          # Screensaver mode
├── orbious.html              # Orb simulation
├── tamagotchi.html           # Tamagotchi game
├── weather.html              # Weather display
├── aquarium_auto.py          # Fish tank simulation (auto-run)
├── crawler.py                # Crawler animation
├── demo_patterns.py          # Various demo patterns
├── infinitovator.py          # Infinite loop game
├── sand_auto.py              # Sandbox simulation (auto-run)
├── sand-sandbox.py           # Interactive sandbox
├── sand_suto.py              # Sandbox (alternative)
├── tamagotchi.py             # Tamagotchi game logic
├── play_json_loop.py         # JSON animation looper
├── weather.py                # Weather API integrator (if exists)
├── screenshots/              # UI screenshots for documentation
├── node_modules/             # Node.js dependencies
├── package.json              # Project metadata
└── README.md                 # This file

Configuration

Server Settings

Edit the following variables in app.js:

var PORT = 1337;              // UDP port for CRAP protocol
var HOST = '0.0.0.0';         // Bind to all interfaces
var ROWS = 16;                // Display height
var COLS = 40;                // Display width
var targetUdpIp = '10.0.1.39'; // Physical display IP (if connected)
var targetUdpPort = 1337;     // Physical display UDP port

Hardware Sync

By default, hardware sync is enabled. You can toggle it from the editor UI or modify the default:

var targetUdpEnabled = true; // Set to false to disable hardware output

Usage

Using the Editor

1. Start the server: node app.js
2. Open http://localhost:8080 in your browser
3. Use the editor to create or load pixel patterns
4. Click "Send to Hardware" to broadcast to physical Matelight

Using Python Visualizers

python3 aquarium_auto.py    # Fish tank animation
python3 crawler.py          # Crawler demo
python3 tamagotchi.py       # Tamagotchi game
python3 sand-sandbox.py     # Interactive sandbox

Adding Visualizations

1. Create a Python script that outputs CRAP protocol data
2. Connect to localhost:1337 via UDP
3. Send RGB pixel data in the standard format

CRAP Protocol Format

The Matelight CRAP protocol transmits pixel data as a UDP packet:

• Format: 1280 bytes RGB data (40 cols × 16 rows × 3 colors)
• Checksum: 4 bytes of zeros appended
• Total: 1284 bytes

Data is sent column-major order:

[col 0 row 0][col 0 row 1]...[col 0 row 15][col 1 row 0]...

Each pixel is 3 bytes: R, G, B (0-255)

API Endpoints

The server also exposes these HTTP endpoints on port 8081:

Endpoint	Description
/api/ctatus	c-base/ctatus information
/api/cbeam	c-base/cbeam member count

Development

Project Setup

# Clone and install
git clone https://github.com/jaseg/matelightemu.git
cd matelightemu
npm install

# Start development server
node app.js

Adding New Pages

1. Create an HTML file (e.g., mynewgame.html)
2. Add WebSocket client code to receive pic events
3. Register in app.js router if needed

Running Python Scripts

Ensure Python 3.x is installed and send output to UDP port 1337:

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
# Send CRAP-formatted data
sock.sendto(data, ('localhost', 1337))

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT License - see LICENSE for details.

References

• Official Matelight Protocol
• c-base Matelight Project

Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

Acknowledgments

This emulator was originally created for the c-base community. Thanks to all contributors who have added visualizations and features over time.