Adafruit_Protomatter is a C library (with Arduino and CircuitPython front-ends) for driving RGB LED matrices (colloquially called “HUB75” matrices but that’s a vague term and not entirely accurate). We already have one such library — RGBmatrixPanel for Arduino — it’s older code that works fine for AVR chips (and a couple others) but has some limitations.

This guide is mostly to assist with porting Adafruit_Protomatter to new hardware.

“Protomatter” was intended as a stand-in name until something better was decided upon, but we’d already moved in by that point.

In CircuitPython, it’s only seen by the sensible name rgbmatrix. But if working with the underlying C code or the Arduino library…sorry, you’re stuck with the awkward-to-type Protomatter name.

It originates in a quote from the character David Marcus in Star Trek III:I used protomatter in the Genesis matrix.” Hopefully the library doesn’t develop a similar reputation as “unstable” and “dangerously unpredictable.”

Protomatter was planned with newer hardware in mind and will not be back-ported to AVR — simply use the prior RGBmatrixPanel there if you need it. The new library takes a casual approach to some things and isn’t particularly RAM-efficient, a crucial concern on AVRs. What Protomatter does provide includes:

  • More flexibility in matrix chain width and height (RGBmatrixPanel only supports a few sizes).
  • More flexibility in pin selection (old code was specifically designed for an Arduino UNO shield).
  • Configurable bit depth, up to the maximum “565” color format used by Adafruit_GFX.
  • Doesn’t rely on esoteric peripherals — sticks with basic “PORT” GPIO and a timer interrupt.
  • No cycle-counting.

A likely candidate device for porting will have:

  • A reasonably fast 32-bit RISC core or similar (e.g. ARM, ESP32). Minimum we’ve used is a 48 MHz Cortex-M0+.
  • One or more timer peripherals, 16-bit or better, with configurable period and with interrupts.
  • GPIO with atomic bit-set and bit-clear registers, typically 32 bits wide…ideally tolerating writes to individual sub-bytes or words.
  • RAM usage depends on matrix size, bit depth and GPIO pin selection. Minimum device we’ve used has 32 KB RAM (total for device, not all consumed by the library).

As currently written, Protomatter eschews the use of DMA or special peripherals beyond what’s described above. Goal is simply to get this working on a variety of devices with a minimum of fuss. We can tweak and optimize later.

Things You’ll Need

  • A datasheet or reference manual for the device being ported to.
  • Hardware to test on. Having both a logic analyzer and a known-compatible-with-existing-devices RGB matrix is really helpful to verify that all signals are doing the right things at the right times.
This guide was first published on May 13, 2020. It was last updated on May 13, 2020. This page (Overview) was last updated on May 22, 2020.