rpi-led-matrix

You can develop locally on your machine and automatically sync changes to your Raspberry Pi.

1. Prerequisites: Ensure you have passwordless SSH access to your Pi.
2. Clone: Clone the repository with submodules onto both your local machine and the Pi.
3. Install: Run npm install in both locations.
4. Configure Sync: Create a sync.config.json file on your local machine with the following structure:

   {
     "username": "<username>",
     "hostname": "<hostname or IP address of your Pi>",
     "directory": "<parent directory on Pi into which the repo was cloned>",
     "quiet": false
   }

5. Workflow:
   • On Local Machine: Run npm run sync-changes. Any changes to /src or /examples will be automatically uploaded to the Pi.
   • On Raspberry Pi: Run npm run build-changes. This will automatically rebuild the changes pushed from your local machine.

Troubleshooting: If npm install fails with TypeError: cannot use a string pattern on a bytes-like object, try switching your environment to Python 2.7.

The MatrixOptions interface defines the physical and electrical configuration of your LED hardware. You should extend the defaults provided by LedMatrix.defaultMatrixOptions().

Key configuration concepts:

• Hardware Mapping: Use the GpioMapping enum to specify your connection type (e.g., GpioMapping.AdafruitHatPwm).
• Pixel Mapping: For complex physical configurations, use LedMatrixUtils.encodeMappers() to generate the required pixelMapperConfig string.
• Enums: Use provided enums for discrete values like ScanMode, MuxType, and RowAddressType to ensure type safety.

import {
  LedMatrix,
  GpioMapping,
  LedMatrixUtils,
  PixelMapperType,
} from 'rpi-led-matrix';

const matrix = new LedMatrix(
  {
    ...LedMatrix.defaultMatrixOptions(),
    rows: 32,
    cols: 64,
    chainLength: 2,
    hardwareMapping: GpioMapping.AdafruitHatPwm,
    pixelMapperConfig: LedMatrixUtils.encodeMappers({
      type: PixelMapperType.U,
    }),
  },
  {
    ...LedMatrix.defaultRuntimeOptions(),
    gpioSlowdown: 1,
  }
);

To create animations that depend on time (like pulsing or moving elements), use the afterSync method on an LedMatrixInstance. This method accepts a SyncHook callback that is automatically executed after every matrix sync.

Callback Signature: type SyncHook = (matrix: LedMatrixInstance, dt: number, t: number) => void;

• matrix: The current LedMatrixInstance.
• dt: Time elapsed since the previous sync (in milliseconds).
• t: Monotonically-increasing system clock time (in milliseconds).

CRITICAL: When calling matrix.sync() inside the afterSync callback to create a continuous animation loop, you must wrap it in a setTimeout(() => matrix.sync(), 0). Failing to do this will cause a stack overflow error because the calls will occur synchronously on the same stack.

This pattern is similar to requestAnimationFrame in web development.

// Example: Creating a continuous animation loop
matrix.afterSync((mat, dt, t) => {
  // 1. Perform your drawing logic here
  mat.fgColor(0xff0000).setPixel(0, 0);

  // 2. Schedule the next sync using setTimeout to avoid stack overflow
  setTimeout(() => mat.sync(), 0);
});

// Start the initial sync
matrix.sync();

The LedMatrixInstance provides a drawing API. Most methods follow a getter/setter pattern: calling a method without arguments returns the current value, while calling it with an argument sets the value and returns the instance itself. This allows for method chaining.

Important Note: Changes are not immediately visible on the hardware. You must call .sync() to commit your drawing operations to the display.

matrix
  .clear() // clear the display
  .brightness(100) // set the panel brightness to 100%
  .fgColor(0x0000ff) // set the active color to blue
  .fill() // color the entire display blue
  .fgColor(0xffff00) // set the active color to yellow
  .drawCircle(matrix.width() / 2, matrix.height() / 2, matrix.width() / 2 - 1)
  .drawRect(
    matrix.width() / 4,
    matrix.height() / 4,
    matrix.width() / 2,
    matrix.height() / 2
  )
  .fgColor({ r: 255, g: 0, b: 0 }) // sets the active color to red
  .drawLine(0, 0, matrix.width(), matrix.height())
  .drawLine(matrix.width() - 1, 0, 0, matrix.height() - 1)
  .sync(); // commit changes to the display

The MatrixOptions interface defines the physical and electrical configuration of your LED matrix. Use this to specify panel dimensions, multiplexing types, and hardware-specific settings like GPIO mapping and PWM precision.

Key configuration properties include:

• brightness: Initial brightness percentage (default: 100).
• chainLength: Number of daisy-chained panels (default: 1).
• cols & rows: Dimensions of a single panel (e.g., 32 cols, 32 rows).
• multiplexing: The MuxType required by your panel.
• hardwareMapping: The GpioMapping used (e.g., GpioMapping.Regular or GpioMapping.AdafruitHat).
• pixelMapperConfig: A string representing the pixel mapper arrangement. Use LedMatrixUtils.encodeMappers() to generate this.
• pwmBits: Precision of PWM (1-11, default: 11).
• scanMode: ScanMode.Progressive or ScanMode.Interlaced.

const matrixOptions: MatrixOptions = {
  brightness: 100,
  chainLength: 1,
  cols: 64,
  rows: 32,
  multiplexing: MuxType.Direct,
  hardwareMapping: GpioMapping.Regular,
  scanMode: ScanMode.Progressive,
  // ... other options
};