PxMatrix Library Documentation

To install PxMatrix, download the library from the repository, rename the uncompressed folder to PxMatrix, and place it in your Arduino libraries directory: <arduinosketchfolder>/libraries/. If the libraries subfolder does not exist, create it. Restart the Arduino IDE after placement to complete the installation.

# Move the renamed folder to your Arduino libraries directory
# Example path structure:
# Documents/Arduino/libraries/PxMatrix/

To correctly drive an LED matrix panel, you must configure three main parameters: row scanning, scan pattern, and multiplex (mux) pattern.

1. Row Scanning: Defines the basic layout (e.g., 1/4, 1/8, 1/16, or 1/32). Set this using display.begin(n) where n is the scan factor.
2. Scan Pattern: If your image appears broken or fragmented, you may need to change the scanning pattern from the default LINE scanning. Use display.setScanPattern(x).
3. Mux Pattern: Defines how address lines (A, B, C, D, E) map to physical rows. Use display.setMuxPattern(x) to select the mapping method (e.g., BINARY, STRAIGHT, or SHIFTREG_ABC).

Example for a non-standard display configuration:

display.begin(4);
display.setScanPattern(ZAGGIZ);
display.setMuxPattern(STRAIGHT);

You can chain multiple panels horizontally to create a larger display. Connect the output connector (PO) of one panel to the input connector (PI) of the next.

To use a chain in your code:

1. Calculate the total width and height in the constructor (e.g., three 32x16 panels result in 96x16).
2. Call display.setPanelsWidth(n) where n is the number of panels in the chain.

Example for three 32x16 panels with 1/4 scan:

#include <PxMatrix.h>
// Total width = 3 * 32 = 96
PxMATRIX display(96, 16, ...);

void setup() {
  display.begin(4);
  display.setPanelsWidth(3);
}

If your panel has a slow multiplexer and only a partial image is displayed, you can add a delay to each of the A-E channels using display.setMuxDelay(). This adds a microsecond delay to the multiplexing process.

Example to add a 1us delay to each channel:

display.setMuxDelay(1, 1, 1, 1, 1);

The PxMatrix library supports various high-performance use cases on ESP8266 and ESP32, including animated clocks, picture frames, and MJPEG decoding.

Key examples include:

• Animated weather clock (ESP8266)
• Animated picture frame (ESP8266)
• 10 FPS MJPEG decoding on a 64x64 RGB LED matrix (ESP32)
• Particle physics simulations on a 64x64 RGB LED matrix (ESP32)

The display.begin(n) method initializes the display and sets the row scanning layout. The parameter n defines the scan factor, which determines how many rows are scanned in a single cycle.

Supported values for n are {4, 8, 16, 32}.

display.begin(4); // For 1/4 row scan

Use display.setScanPattern(x) to define how parts of your picture are mapped onto the matrix. This is useful if your image is broken up into pieces at incorrect locations.

Supported patterns include:

• LINE (default)
• ZIGZAG
• ZZAGG
• ZAGGIZ
• WZAGZIG
• VZAG
• ZAGZIG
• WZAGZIG2

Use display.setMuxPattern(x) to specify how the panel handles row multiplexing. Most panels use BINARY mapping, but others may require STRAIGHT or shift-register based patterns.

Supported patterns include:

• BINARY (default)
• STRAIGHT
• SHIFTREG_ABC (for panels with RT5957 chips)
• SHIFTREG_SPI_SE (experimental; uses SPI signal for row selection to save I/O pins)