Installation

This guide covers the complete installation process for the LED Matrix Cube example applications, including dependencies, compilation, and deployment across different platforms.

Prerequisites

Framework Dependency

The example applications require the matrixserver framework to be installed first. The matrixserver provides the core libraries and runtime components needed by all applications.

Required: matrixserver framework with matrixapplication library

System Dependencies

The following system libraries are required for compilation:

Essential Libraries

  • Boost (version 1.58.0 or later)

    • boost-thread - Multi-threading support

    • boost-log - Logging framework

    • boost-system - System utilities

  • Imlib2 - Image processing library for picture display functionality

  • absl - Google’s Abseil C++ library for utility functions

Platform-Specific Dependencies

On macOS with Homebrew:

brew install boost imlib2 abseil

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libboost-all-dev libimlib2-dev libabsl-dev

On Raspberry Pi:

sudo apt-get update
sudo apt-get install libboost-all-dev libimlib2-dev libabsl-dev
# Additional Raspberry Pi specific packages may be needed

Build System Requirements

CMake (version 3.07 or later) C++ Compiler with C++17 support (GCC 7+, Clang 5+, MSVC 2017+) Make or equivalent build system

Platform Detection

The build system automatically detects the target platform and enables appropriate applications:

Raspberry Pi Detection

The CMake configuration automatically detects Raspberry Pi systems by checking for the existence of /boot/LICENCE.broadcom. When detected:

  • Additional Raspberry Pi-specific applications are enabled

  • Hardware-specific optimizations are applied

  • Platform-specific dependencies are configured

if (EXISTS "/boot/LICENCE.broadcom")
    set(BUILD_RASPBERRYPI true)
    message("Build on Raspberry Pi is enabled")
endif()

Enabled Applications by Platform

All Platforms:

  • CubeTestApp - Basic 3D functionality demonstration

  • PixelFlow3 - Fluid dynamics simulation

Raspberry Pi Only:

  • ImuTest - IMU sensor integration

  • PixelFlow - Original fluid dynamics (with hardware optimizations)

  • PixelFlow2 - Enhanced fluid dynamics

  • Rainbow - Particle system with IMU integration

Building from Source

Basic Build Process

  1. Clone or extract the source code

  2. Create build directory:

    mkdir -p build
cd build

  3. Configure with CMake:

    cmake ..

  4. Compile all applications:

    make

  5. Build specific application:

    make <application_name>
# Example: make cubetestapp

Build Configuration Options

Build Type Configuration

The build system defaults to Release mode for optimized performance:

# Explicit Release build
cmake -DCMAKE_BUILD_TYPE=Release ..

# Debug build with symbols
cmake -DCMAKE_BUILD_TYPE=Debug ..

Custom Installation Prefix

cmake -DCMAKE_INSTALL_PREFIX=/custom/path ..

Platform-Specific Options

For macOS systems, the build system automatically configures library paths:

# Automatic configuration for Homebrew paths
cmake -DIMLIB2_ROOT=/opt/homebrew/Cellar/imlib2/1.12.2 ..

Dependency Resolution

CMake Package Discovery

The build system uses CMake’s find_package mechanism to locate dependencies:

find_package(Boost 1.58.0 REQUIRED COMPONENTS thread log system)
find_package(absl REQUIRED)
find_package(matrixapplication REQUIRED)

Library Linking Configuration

Each application links against the required libraries:

target_link_libraries(cubetestapp
    matrixapplication::matrixapplication
    absl::log_internal_message
)

Troubleshooting Build Issues

Common Problems and Solutions

Missing matrixapplication Library

Error: Could not find package configuration file provided by "matrixapplication"

Solution: Install the matrixserver framework first. Ensure it’s properly installed and CMake can find it.

Imlib2 Not Found

Error: IMLIB2 Not Found

Solution: Install Imlib2 development packages or specify custom path:

cmake -DIMLIB2_ROOT=/path/to/imlib2 ..

Boost Version Conflicts

Error: Boost version too old

Solution: Update Boost to version 1.58.0 or later, or specify custom Boost installation:

cmake -DBOOST_ROOT=/path/to/boost ..

C++17 Compiler Issues

Error: C++17 features not available

Solution: Use a modern compiler that supports C++17:

cmake -DCMAKE_CXX_COMPILER=g++-7 ..

Deployment

Package Generation

The project includes Debian package generation for easy deployment:

# Generate .deb package
make package

This creates a .deb file with:

  • Dependency declaration on matrixserver package

  • Proper installation paths (/home/pi/APPS on Raspberry Pi)

  • Package metadata and installation scripts

Manual Installation

For manual deployment:

  1. Copy executables to target system

  2. Ensure matrixserver framework is installed

  3. Install runtime dependencies (Boost, Imlib2, absl)

  4. Set executable permissions if needed

Running Applications

Server Requirement

All applications require a running matrixserver instance. Start the appropriate server for your hardware:

Development/Testing:

# Software simulator
/path/to/matrixserver/build/server_simulator

Hardware Deployment:

# FPGA with USB interface
/path/to/matrixserver/build/server_FPGA

# Raspberry Pi SPI interface
/path/to/matrixserver/build/server_FPGA_RPISPI

# Direct GPIO control
/path/to/matrixserver/build/server_RGBMatrix

Application Execution

Once a server is running, launch any example application:

# From build directory
./cubetestapp
./snake
./pixelflow3
# etc.

The applications will automatically:

  • Detect and connect to running matrixserver instances

  • Configure appropriate frame rates and display settings

  • Begin rendering to the connected display hardware

Connection Priority

Applications attempt connections in this order:

  1. TCP localhost:2017 (default)

  2. IPC message queue (local fallback)

  3. Unix domain sockets (alternative local)

This ensures robust connectivity across different deployment scenarios.