LEDMatrix/docs/EMULATOR_SETUP_GUIDE.md

LEDMatrix Emulator Setup Guide

Overview

The LEDMatrix emulator allows you to run and test LEDMatrix displays on your computer without requiring physical LED matrix hardware. This is perfect for development, testing, and demonstration purposes.

Table of Contents

1. Prerequisites
2. Installation
3. Configuration
4. Running the Emulator
5. Display Adapters
6. Troubleshooting
7. Advanced Configuration

Prerequisites

System Requirements

• Python 3.10 or higher
• Windows, macOS, or Linux
• At least 2GB RAM (4GB recommended)
• Internet connection for plugin downloads

Required Software

• Python 3.10+
• pip (Python package manager)
• Git (for plugin management)

Installation

1. Clone the Repository

git clone --recurse-submodules https://github.com/ChuckBuilds/LEDMatrix.git
cd LEDMatrix

The emulator does not require building the rpi-rgb-led-matrix-master submodule (it uses RGBMatrixEmulator instead), so --recurse-submodules is optional here. Run it anyway if you also want to test the real-hardware code path.

2. Install Emulator Dependencies

Install the emulator-specific requirements:

pip install -r requirements-emulator.txt

This installs:

• RGBMatrixEmulator - the emulation library (and whatever it depends on)

3. Install Standard Dependencies

pip install -r requirements.txt

Configuration

1. Emulator Configuration File

The emulator uses emulator_config.json for configuration. It isn't in the repo (it's gitignored): RGBMatrixEmulator writes it on first run. A typical file looks like this:

{
    "pixel_outline": 0,
    "pixel_size": 16,
    "pixel_style": "square",
    "pixel_glow": 6,
    "display_adapter": "browser",
    "allow_adapter_fallback": true,
    "icon_path": null,
    "emulator_title": null,
    "suppress_font_warnings": false,
    "browser": {
        "_comment": "For use with the browser adapter only.",
        "port": 8888,
        "target_fps": 60,
        "fps_display": false,
        "quality": 70,
        "image_border": true,
        "debug_text": false,
        "image_format": "JPEG",
        "open_immediately": false
    },
    "log_level": "info"
}

2. Configuration Options

Option	Description	Default	Values
pixel_outline	Pixel border thickness	0	0-5
pixel_size	Size of each pixel	16	1-64 (8–16 is typical for testing)
pixel_style	Pixel shape	"square"	"square", "circle"
pixel_glow	Glow effect intensity	6	0-20
display_adapter	Display backend	"browser"	"browser", "pygame"
allow_adapter_fallback	Fall back to another adapter if the configured one fails to load	true	true/false
emulator_title	Window title	null	Any string
suppress_font_warnings	Hide font warnings	false	true/false

3. Browser Adapter Configuration

When using the browser adapter, additional options are available:

Option	Description	Default
port	Web server port	8888
target_fps	Target frames per second	60
fps_display	Show FPS counter	false
quality	Image compression quality	70
image_border	Show image border	true
debug_text	Show debug information	false
image_format	Image format	"JPEG"
open_immediately	Open the browser page automatically on start	false

Running the Emulator

1. Use the -e Flag (Recommended)

run.py accepts exactly two flags: -e/--emulator and -d/--debug.

python3 run.py -e

# With verbose logging
python3 run.py -e -d

2. Alternative: Set the Environment Variable

You can also enable emulator mode via the EMULATOR environment variable:

Windows (Command Prompt):

set EMULATOR=true
python run.py

Windows (PowerShell):

$env:EMULATOR="true"
python run.py

Linux/macOS:

EMULATOR=true python3 run.py

3. Verify Emulator Mode

When running in emulator mode, you should see:

• The emulated matrix — a web page at http://localhost:8888 with the default browser adapter, or a desktop window with the pygame adapter
• Console output indicating emulator mode
• No hardware initialization errors

Display Adapters

LEDMatrix supports two display adapters for the emulator:

1. Browser Adapter (Default)

The browser adapter runs a web server and displays the matrix as a web page at http://localhost:8888. This is the adapter the shipped emulator_config.json uses.

Features:

• Web-based interface
• Remote access capability
• Mobile-friendly
• Screenshot capture

Configuration:

{
    "display_adapter": "browser",
    "browser": {
        "port": 8888,
        "target_fps": 60,
        "quality": 70
    }
}

Usage:

1. Start the emulator (python3 run.py -e)
2. Open browser to http://localhost:8888
3. View the LED matrix display

2. Pygame Adapter (Alternative)

The pygame adapter provides a native desktop window with real-time display.

Features:

• Real-time rendering
• Keyboard controls
• Window resizing
• High performance

Configuration:

{
    "display_adapter": "pygame",
    "pixel_size": 16,
    "pixel_style": "square"
}

Keyboard Controls:

• ESC - Exit emulator
• F11 - Toggle fullscreen
• +/- - Zoom in/out
• R - Reset zoom

Troubleshooting

Common Issues

1. "ModuleNotFoundError: No module named 'RGBMatrixEmulator'"

Solution:

pip install RGBMatrixEmulator

2. Pygame Window Not Opening

Possible Causes:

• Missing pygame installation
• Display server issues (Linux)
• Graphics driver problems

Solutions:

# Install pygame
pip install pygame

# For Linux, ensure X11 is running
echo $DISPLAY

# For WSL, install X server
# Windows: Install VcXsrv or Xming

3. Browser Adapter Not Working

Check:

• Port 8888 is available
• Firewall allows connections
• Browser can access localhost

Solutions:

# Check if port is in use
netstat -an | grep 8888

# Try different port in config
"port": 8889

4. Performance Issues

Optimizations:

• Reduce pixel_size in config
• Lower target_fps for browser adapter
• Close other applications
• Use pygame adapter for better performance

Debug Mode

Enable debug logging:

{
    "log_level": "debug",
    "suppress_font_warnings": false
}

Advanced Configuration

1. Custom Display Dimensions

Modify the display dimensions in your main config:

{
    "display": {
        "hardware": {
            "rows": 32,
            "cols": 64,
            "chain_length": 2
        }
    }
}

2. Plugin Development

run.py always runs the full rotation — it has no single-plugin flag. To preview or check one plugin in isolation, use the dev tools:

# Run the full display in emulator mode (optionally with debug logging)
python3 run.py -e -d

# Live single-plugin preview in the browser (port 5001)
python3 scripts/dev_server.py

# Headless render/validation of one plugin
python3 scripts/check_plugin.py --plugin my-plugin

3. Performance Tuning

For High-Resolution Displays:

{
    "pixel_size": 8,
    "pixel_glow": 2,
    "browser": {
        "target_fps": 15,
        "quality": 50
    }
}

For Low-End Systems:

{
    "pixel_size": 12,
    "pixel_glow": 0,
    "browser": {
        "target_fps": 10,
        "quality": 30
    }
}

4. Integration with Web Interface

The emulator can work alongside the web interface:

# Terminal 1: Start emulator
python3 run.py -e

# Terminal 2: Start web interface (supported entry point)
python3 web_interface/start.py

Access the web interface at http://localhost:5000 while the emulator runs.

Best Practices

1. Development Workflow

1. Start with emulator for initial development
2. Test plugins using emulator mode
3. Validate configuration before hardware deployment
4. Use browser adapter for remote testing

2. Plugin Testing

# Test a specific plugin (headless check)
python3 scripts/check_plugin.py --plugin clock-simple

# Preview a single plugin live in the browser (port 5001)
python3 scripts/dev_server.py

# Test the full rotation in the emulator
python3 run.py -e

3. Configuration Management

• Keep emulator_config.json in version control
• Use different configs for different environments
• Document custom configurations

Examples

Basic Clock Display

# Start emulator with clock enabled in config.json
python3 run.py -e

Sports Scores

# Configure for sports display
# Edit config/config.json to enable sports plugins
python3 run.py -e

Custom Text Display

# Preview the text display plugin on its own
python3 scripts/check_plugin.py --plugin text-display
# or use the live dev preview server
python3 scripts/dev_server.py

Support

For additional help:

1. Check the logs - Enable debug mode for detailed output
2. Review configuration - Ensure all settings are correct
3. Test with minimal config - Start with default settings
4. Community support - Check GitHub issues and discussions

Conclusion

The LEDMatrix emulator provides a powerful way to develop, test, and demonstrate LED matrix displays without physical hardware. With support for multiple display adapters and comprehensive configuration options, it's an essential tool for LEDMatrix development and deployment.

For more information, see the main README.md and other documentation in the docs/ directory.