• REST API server for seamless remote control
• React Native mobile app for on-the-go management
• Plugin architecture for unlimited extensibility
• Preset management for quick scene switching
• Real-time configuration without restarts

Our extensive plugin system provides a diverse range of visual experiences:

• Starfield - Journey through a 3D cosmic environment
• Metablob - Organic fluid animations with flowing colors
• Clock - Elegant digital and analog timepieces
• Fire - Realistic flame simulations

• Spotify Integration - Display album art with beat-synchronized effects
• Audio Spectrum - Real-time frequency visualization
• Beat-synced animations with BPM detection

• Weather Display - Live weather with animated effects (rain, snow, etc.)
• GitHub Activity - Visualize your development activity

• Tetris - AI-powered automated gameplay
• Ping Pong - Classic Pong with AI opponents
• Maze Generator - Watch mazes being created and solved

• Julia Set - Animated fractal visualizations
• Wave Patterns - Hypnotic mathematical wave functions
• Plasma Effects - Smooth color gradients and patterns

• Particle Systems - Rain, sparks, and physics simulations
• Image Display - Remote image loading with artistic processing
• Custom Animations - Extensible through the plugin system

• Hardware abstraction supporting various matrix configurations
• Cross-compilation support for efficient Raspberry Pi deployment
• Emulator support with SDL2 for development
• Configurable logging with spdlog integration
• Persistent configuration with JSON-based settings

The heart of the system - a high-performance application that orchestrates everything:

• Scene rendering engine with smooth animations at 60+ FPS
• Plugin management with hot-loadable modules
• Hardware interface supporting multiple matrix configurations
• RESTful API server for external control and integration
• Configuration persistence and real-time updates

A sleek mobile companion for remote control:

• Intuitive scene selection with live previews
• Real-time matrix control from anywhere on your network
• Preset management for quick configuration switching
• Image upload functionality for custom displays
• Cross-platform support (iOS & Android)

Located in the react-native/ directory with modern TypeScript and native performance.

⚠️ Important: This project builds upon the excellent rpi-rgb-led-matrix library. For detailed hardware setup, wiring diagrams, troubleshooting, and matrix-specific configuration, please refer to the comprehensive documentation in that repository.

• Raspberry Pi 4 (3B+ minimum) for optimal performance
• RGB LED matrix panels with HUB75 interface (32x32, 64x32, 64x64, or custom sizes)
• Quality power supply (5V with sufficient amperage - matrices are power-hungry!)
• Adafruit RGB Matrix Bonnet or Electrodragon RGB Panel Driver for reliable performance

The application intelligently supports various setups:

• Single panels: 32x32, 64x32, 64x64, or custom dimensions
• Chained displays: Multiple panels connected horizontally
• Parallel chains: Up to 3 chains on Pi 3/4, 6 on Compute Module
• Mixed configurations: Different panel sizes and arrangements

Configure your setup using command-line flags or the configuration file - the system adapts automatically!

• CMake 3.5+ for build system management
• C++23 compatible compiler (GCC 12+ or Clang 15+)
• vcpkg package manager for dependency management
• Python 3 with jinja2 package (apt install python3-jinja2 -y)
• GraphicsMagick and development headers (apt install libgraphicsmagick1-dev)

• Node.js 18+ and npm/yarn
• React Native CLI and development environment
• Android Studio (for Android development)
• Xcode (for iOS development on macOS)

💡 Pro Tip: Building on Raspberry Pi can be slow. Consider cross-compilation for faster development cycles.

1. Install vcpkg following the official guide

2. Configure the build system:

   cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path_to_vcpkg]/scripts/buildsystems/vcpkg.cmake

3. Build the application:

   cmake --build build

4. Install (optional):

   cmake --install build

Test your scenes without physical hardware using our SDL2-based emulator:

# One-command setup and build
cmake --preset=emulator
cmake --build emulator_build

# Run with emulation
./emulator_build/main [options]

Perfect for development, testing, and demonstrations!

Get the mobile app running in minutes:

1. Navigate to the app directory:

   cd react-native

2. Install dependencies:

   npm install

3. Launch the app:

   npm run dev:android        # For Android
   npm run dev:ios            # For iOS

Start your LED matrix display with a simple command:

sudo ./led-matrix-controller [options]

🔑 Note: sudo is required for GPIO access on Raspberry Pi.

# Basic matrix setup
--led-rows=32              # Rows per panel
--led-cols=64              # Columns per panel
--led-chain=2              # Number of chained panels
--led-parallel=1           # Number of parallel chains

# Visual settings
--led-brightness=80        # Brightness (0-100)
--led-pwm-bits=11         # Color depth (1-11)
--led-limit-refresh=120   # Refresh rate limit

# Hardware-specific
--led-gpio-mapping=adafruit-hat    # For Adafruit HAT/Bonnet
--led-slowdown-gpio=1             # Timing adjustment for Pi models

📖 For comprehensive configuration options, including troubleshooting flickering displays, timing adjustments, and advanced setups, see the rpi-rgb-led-matrix documentation.

The application uses a smart configuration system:

• config.json - Automatically created in the application directory
• Persistent settings - Scene presets, API configurations, plugin settings
• Hot-reload support - Many settings update without restart
• Backup-friendly - JSON format for easy version control

Fine-tune logging for development and debugging:

# Set log level via environment variable
SPDLOG_LEVEL=debug ./led-matrix-controller

# Available levels: trace, debug, info, warn, error, critical, off

All logs output to console with timestamps and color coding for easy reading.

The REST API provides powerful remote control capabilities at http://<device-ip>:8080/.

🌟 Pro Tip: The API also serves static files from /web/ for custom web interfaces!

# Show refresh rate for performance monitoring
--led-show-refresh

# Detailed timing information
SPDLOG_LEVEL=debug ./led-matrix-controller

# Test basic functionality
./led-matrix-controller --led-rows=32 --led-cols=64 -D0

📚 For hardware-specific issues, timing problems, or panel compatibility, consult the comprehensive rpi-rgb-led-matrix troubleshooting guide.

Extend the matrix with your own custom scenes and effects!

1. Set up the plugin structure:

   plugins/
   └── MyAwesomePlugin/
       ├── CMakeLists.txt
       ├── MyAwesomePlugin.cpp
       ├── MyAwesomePlugin.h
       └── scenes/
           ├── MyScene.cpp
           └── MyScene.h
   

2. Implement the plugin interface:

   class MyAwesomePlugin : public BasicPlugin {
   public:
       MyAwesomePlugin();
       
       vector<std::unique_ptr<SceneWrapper, void (*)(SceneWrapper *)>> 
           create_scenes() override;
           
       vector<std::unique_ptr<ImageProviderWrapper, void(*)(ImageProviderWrapper*)>> 
           create_image_providers() override;
   };

Create engaging visual experiences with our scene framework:

class MyScene : public Scenes::Scene {
private:
    // Configurable properties - automatically exposed in API
    Property<float> speed{"speed", 1.0f};
    Property<int> color{"color", 0xFF0000};
    
public:
    bool render(RGBMatrixBase *matrix) override {
        // Your rendering logic here
        return true; // Continue rendering
    }
    
    void register_properties() override {
        add_property(speed);
        add_property(color);
    }
    
    string get_name() const override { return "my_scene"; }
};

• Property system - Automatic API exposure and persistence
• Image providers - Custom image sources and processing
• Hot-reloading - Test changes without restarting
• Inter-plugin communication - Share data between plugins
• Custom API endpoints - Extend the REST API

Study the included plugins for inspiration:

• ExampleScenes/ - Simple starting template
• FractalScenes/ - Mathematical visualizations
• SpotifyScenes/ - External API integration
• GameScenes/ - Interactive content
• WeatherOverview/ - Real-world data visualization

We welcome contributions! Whether it's a bug fix, new feature, or awesome plugin - join our community.

1. Fork the repository
2. Create your feature branch:

   git checkout -b feature/amazing-new-feature

3. Make your changes with clear, tested code
4. Commit with descriptive messages:

   git commit -m 'Add some amazing new feature'

5. Push to your branch:

   git push origin feature/amazing-new-feature

6. Open a Pull Request with detailed description

• New scene plugins - Weather, stocks, social media, games
• Performance optimizations - Faster rendering, lower memory usage
• Hardware support - New matrix types, different GPIO mappings
• Mobile app features - Better UI, offline mode, advanced controls
• Documentation - Tutorials, examples, troubleshooting guides

• C++23 features encouraged where appropriate
• Clear variable names and comprehensive comments
• Error handling with std::expected where possible
• Thread safety for multi-threaded operations
• Unit tests for critical functionality

See the LICENSE file for details.

• rpi-rgb-led-matrix by Henner Zeller - The foundation that makes this all possible
• RGBMatrixAnimations by Footleg - Particle system animations
• Open source community - For the countless libraries and tools that power this project