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](#prerequisites)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Running the Emulator](#running-the-emulator)
5. [Display Adapters](#display-adapters)
6. [Troubleshooting](#troubleshooting)
7. [Advanced Configuration](#advanced-configuration)

## Prerequisites

### System Requirements
- Python 3.7 or higher
- Windows, macOS, or Linux
- At least 2GB RAM (4GB recommended)
- Internet connection for plugin downloads

### Required Software
- Python 3.7+
- pip (Python package manager)
- Git (for plugin management)

## Installation

### 1. Clone the Repository

```bash
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:

```bash
pip install -r requirements-emulator.txt
```

This installs:
- `RGBMatrixEmulator` - The core emulation library
- Additional dependencies for display adapters

### 3. Install Standard Dependencies

```bash
pip install -r requirements.txt
```

## Configuration

### 1. Emulator Configuration File

The emulator uses `emulator_config.json` for configuration. Here's the
default configuration as it ships in the repo:

```json
{
    "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`.

```bash
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):**
```cmd
set EMULATOR=true
python run.py
```

**Windows (PowerShell):**
```powershell
$env:EMULATOR="true"
python run.py
```

**Linux/macOS:**
```bash
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:**
```json
{
    "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:**
```json
{
    "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:**
```bash
pip install RGBMatrixEmulator
```

#### 2. Pygame Window Not Opening

**Possible Causes:**
- Missing pygame installation
- Display server issues (Linux)
- Graphics driver problems

**Solutions:**
```bash
# 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:**
```bash
# 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:

```json
{
    "log_level": "debug",
    "suppress_font_warnings": false,
    "suppress_adapter_load_errors": false
}
```

## Advanced Configuration

### 1. Custom Display Dimensions

Modify the display dimensions in your main config:

```json
{
    "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:

```bash
# 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:**
```json
{
    "pixel_size": 8,
    "pixel_glow": 2,
    "browser": {
        "target_fps": 15,
        "quality": 50
    }
}
```

**For Low-End Systems:**
```json
{
    "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:

```bash
# 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

```bash
# 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

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

### Sports Scores

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

### Custom Text Display

```bash
# 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](../README.md) and other documentation in the `docs/` directory.