SmartMatrix Library

SmartMatrix Library supports the following hardware:

Teensy

• Teensy 4.x: Teensy 4.1 and Teensy 4.0 (Recommended for best performance).
• Teensy 3.x: Teensy 3.6, 3.5, 3.2/3.1, 3.0.

ESP32

• ESP32: Experimental support is available in version 4.0, though some features may not be as mature as the Teensy ports.

HUB75 RGB panels are cost-effective LED billboards that require an external controller (like a Teensy running SmartMatrix) to refresh them line by line.

• Compatibility: Panels from Adafruit and Sparkfun are known to be compatible, but most panels from sources like AliExpress are also compatible.
• Search Terms: When looking for panels, use terms like "pixel pitch" and "RGB" (e.g., "P6 RGB" for a 6mm pitch panel).

When chaining multiple panels to create a larger display, use kMatrixOptions to define how they are tiled. You can combine multiple options using the bitwise-OR operator (|).

Available Options

• SM_HUB75_OPTIONS_C_SHAPE_STACKING: Inverts the panel on each row to create a 'C' shape. This minimizes cable length between rows but is incompatible with panels requiring Multi Row Refresh Mapping (e.g., types containing column size like SM_PANELTYPE_HUB75_16ROW_32COL_MOD2SCAN).
• SM_HUB75_OPTIONS_BOTTOM_TO_TOP_STACKING: Stacks panels from the bottom up instead of the default top-down.

Example: C-shape stacking with Bottom-to-top direction

const uint8_t kMatrixOptions = (SM_HUB75_OPTIONS_C_SHAPE_STACKING | SM_HUB75_OPTIONS_BOTTOM_TO_TOP_STACKING);

Note: As of version 4.0.3, the stacking direction is reversed for the ESP32 platform.

Sketches written for version 3.x are generally compatible with 4.0 but require minor adjustments.

Key Migration Steps

• Review MIGRATION.md for specific code changes required.
• File Renaming: Many files were renamed using case-sensitive changes.
• Git Tip: If you encounter errors like The following untracked working tree files would be overwritten by checkout when switching versions, use the command line with the -f flag to force the checkout (note: this will discard local modifications).

New Features in 4.0

• Support for Teensy 4 and ESP32.
• Support for driving APA102 LEDs on Teensy platforms.
• Rewritten "GFX" layers for better efficiency, utilizing Adafruit_GFX for drawing and fonts.
• Support for non-standard mapping panels (e.g., 16x32/4 MOD4 panels).

The SmartMatrix Basic Spectrum Analyzer is a demo that visualizes audio on a 32x32 RGB LED matrix. It utilizes the SmartMatrix library for matrix control, FastLED for color management, and the Teensy Audio Library for signal processing.

Hardware Requirements

• LED Matrix: 32x32 RGB LED matrix.
• Controller: Teensy 3 or Teensy 4.
• Shield: A SmartMatrix shield is required to interface the controller with the matrix.
• Audio Input: Uses analog line-in on pin A2.

Analog Input Circuit

For optimal performance and to prevent damage, use a recommended analog input circuit. You can find the recommended schematic via the Teensy Audio GUI documentation: Teensy Audio Input Analog.

To run the Spectrum Analyzer example, you must install the following libraries in your Arduino/Teensy development environment:

1. Teensy Audio Library: https://github.com/PaulStoffregen/Audio
2. SerialFlash Library (dependency for Teensy Audio): https://github.com/PaulStoffregen/SerialFlash
3. SmartMatrix Library: https://github.com/pixelmatix/smartmatrix/releases
4. FastLED (v3.1 or higher): https://github.com/FastLED/FastLED/releases

You can install the SmartMatrix library using one of two methods:

1. Arduino Library Manager: Search for SmartMatrix. Note that during the transition to version 4.x, you might find it listed under SmartMatrix3.
2. Manual Download: Download the latest release from the GitHub Releases page and import it into your Arduino IDE.

Prerequisites:

• Arduino IDE: Version 1.6.5 or later recommended.
• Teensyduino: Install the latest version via the official download page.

SmartMatrix uses rgb24 for pixel data, which is not automatically compatible with FastLED's CRGB or CHSV types. Use the following casting patterns to resolve compiler errors:

• CHSV to rgb24: Wrap CHSV in CRGB(): buffer[XY(i,j)] = CRGB(CHSV(...));
• CRGB pointer casting: If a function expects CRGB*, cast the rgb24* buffer: (CRGB*)buffer.
• HTMLColorCode: Cast to CRGB: (CRGB)CRGB::Black.
• Function arguments (nblend, etc.): Cast the buffer element to CRGB&: nblend((CRGB&)buffer[pixelnumber], newcolor, 64);

In SmartMatrix 3.0, you must explicitly add your allocated layers to the matrix instance before initializing the hardware. If you skip this step, the screen may remain blank even if the code compiles.

// Add layers before matrix.begin()
matrix.addLayer(&backgroundLayer); 
matrix.addLayer(&scrollingLayer); 
matrix.addLayer(&indexedLayer); 

matrix.begin();

If you do not need a specific layer, omit the addLayer call and remove the corresponding SMARTMATRIX_ALLOCATE_* macro from your sketch.