Skip to content

README.md

Latest commit

 

History

History
237 lines (173 loc) · 8.23 KB

README.md

File metadata and controls

237 lines (173 loc) · 8.23 KB

LEDCube Example Applications

This repository contains example applications for the LEDCube matrixserver framework, demonstrating various 3D volumetric graphics, 2D matrix effects, and interactive games.

About This Fork

This is a fork of the original squarewavedot/exampleApplications repository with the following enhancements:

  • Claude-generated documentation: Comprehensive documentation generated with Claude AI assistance
  • macOS compatibility: CMake build system tweaks to compile on macOS
  • Enhanced project structure: Improved organization and build configuration, matrixserver as a git submodule

Documentation

📖 Complete Documentation

The full project documentation is hosted on GitHub Pages and includes API references, tutorials, and examples.

Overview

This collection showcases the capabilities of the LEDCube matrixserver framework through various application types:

3D Volumetric Applications

  • CubeTestApp - Basic 3D functionality demonstration and testing
  • Snake - Multi-player 3D Snake game with joystick input and AI opponents
  • Genetic - Genetic algorithm color evolution visualization in 3D space
  • Blackout3D - Minimal interactive 3D application template
  • Breakout3D - Full-featured 3D Breakout game with physics and multiplayer support

2D Matrix Applications

  • Rainbow - Particle system with IMU integration (Raspberry Pi only)
  • Picture - Image display with animation support and file watching
  • Genetic - Genetic algorithm visualization on 2D matrix displays

Animation & Effects

  • PixelFlow/PixelFlow2/PixelFlow3 - Fluid dynamics particle simulations

Architecture

All applications inherit from either:

  • CubeApplication for 3D volumetric rendering
  • MatrixApplication for 2D matrix effects

The framework provides:

  • 3D Volumetric Rendering: Set voxels, draw 3D lines, render text on cube faces
  • Multi-Screen Support: Six screens (front, right, back, left, top, bottom)
  • Input Integration: Joystick, IMU (MPU6050), and ADC (ADS1000) sensor support
  • Multiple Connection Types: TCP, IPC, and Unix socket communication with matrixserver

Quick Start

Prerequisites

Matrixserver Framework Installation

The matrixserver framework must be compiled and installed before building these example applications. The linker requires access to the libmatrixapplication library and related components.

Installation Steps:

  1. Clone the matrixserver framework:

    git clone https://github.com/squarewavedot/matrixserver.git
cd matrixserver

  2. Build and install the framework locally (recommended):

    mkdir -p build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=../install
make
make install

    This installs the framework into matrixserver/install/, which the example applications pick up automatically without any extra configuration.

    Alternative - System-wide installation:

    mkdir -p build && cd build
cmake ..
make
sudo make install
# Installs libraries to /usr/local/lib and headers to /usr/local/include
sudo ldconfig

  3. Verify installation:

    # Local install (recommended)
ls matrixserver/install/

# System-wide install
ls /usr/local/lib/libmatrixapplication*

Required matrixserver components:

  • libmatrixapplication - Core application framework (version >= 0.3)
  • Header files for CubeApplication and MatrixApplication base classes
  • Server executable: matrix_server (one binary; backend selected at runtime via --backend=<simulator|fpga-ftdi|fpga-rpispi|rgb-matrix>)

Troubleshooting:

  • The build system checks ./matrixserver/install/ first, then falls back to system paths
  • If using a custom install location, pass -DCMAKE_PREFIX_PATH=/your/path to CMake
  • Ensure all matrixserver dependencies are installed (Boost, OpenGL, etc.)

LC_RPATH gotcha when iterating on matrixserver alongside the example apps:

The example apps' CMake bakes only LC_RPATH = /usr/local/lib into each binary. So when you make install matrixserver into a local matrixserver/install/ prefix, the example app build picks up the new library at link time (the API is verified), but at runtime the dynamic loader still falls back to /usr/local/lib/libmatrixapplication.* — the previously installed system copy. The binary will silently run against the old library.

To actually run an app against the freshly built matrixserver, point the loader at the install tree:

# macOS
export DYLD_LIBRARY_PATH=/path/to/matrixserver/install/lib

# Linux
export LD_LIBRARY_PATH=/path/to/matrixserver/install/lib

./build/bin/Snake

Or alternatively: sudo make install matrixserver to /usr/local so the existing rpath matches (replaces the system copy), or on macOS patch the binary in place with install_name_tool -add_rpath /path/to/matrixserver/install/lib build/bin/<App>.

Additional prerequisites

  • CMake
  • Boost libraries (thread, log, system)
  • Imlib2 (image processing)
  • Google's Abseil library

Building

# Clone the repository
git clone https://github.com/your-username/exampleApplications.git
cd exampleApplications

# Build all applications
mkdir -p build && cd build
cmake ..
make

# Or build specific applications
make cubetestapp     # Basic 3D test
make snake           # 3D Snake game
make breakout3d      # 3D Breakout game
make picture         # Image display

Running Applications

  1. Start a matrixserver instance:

    # From matrixserver directory
./build/server/matrix_server                       # default: --backend=simulator
./build/server/matrix_server --backend=fpga-ftdi   # for FPGA hardware (must be compiled in)

  2. Run an example application:

    ./cubetestapp            # Basic 3D demo
./snake                  # 3D Snake game
./picture image.png      # Display image

Configuration

IMU Orientation (Raspberry Pi)

Applications using the MPU6050 IMU sensor (like Rainbow) support configurable orientation corrections via matrixServerConfig.json:

{
  "imuOrientation": {
    "xyRotationDeg": 0.0,
    "xzRotationDeg": 45.0,
    "yzRotationDeg": 0.0
  }
}

The three rotation angles allow you to correct for how the sensor is physically mounted:

  • xyRotationDeg: Rotation around the Z axis
  • xzRotationDeg: Rotation around the Y axis
  • yzRotationDeg: Rotation around the X axis

All values default to 0° when absent, maintaining backwards compatibility.

Platform Support

  • All Platforms: CubeTestApp, PixelFlow3, basic applications
  • Raspberry Pi: Additional IMU-based applications (Rainbow, PixelFlow, PixelFlow2)
  • macOS: Enhanced compatibility with updated CMake configuration

Hardware Compatibility

Applications work with the unified matrix_server binary, which selects a renderer backend at runtime via --backend=<name>:

  • simulator — Software development and testing (always available)
  • fpga-ftdi — FTDI USB interface for FPGA boards
  • fpga-rpispi — Raspberry Pi SPI interface
  • rgb-matrix — Raspberry Pi GPIO matrix panels

Hardware backends are only selectable if they were compiled into the binary via -DHARDWARE_BACKEND=… at build time. matrix_server --help lists which backends the current binary supports.

Package Creation

Generate Debian packages for easy deployment:

make package

Creates .deb files with automatic matrixserver dependency resolution.

Contributing

This project welcomes contributions! Please see the upstream repository squarewavedot/exampleApplications for the original codebase and contribution guidelines.

License

This project follows the same license as the upstream repository. License of upstream matrixserver

Links