# Adafruit Protomatter RGB Matrix Library ## Overview https://www.youtube.com/watch?v=x8MAx_PMnN4 **Adafruit\_Protomatter** is a C library (with Arduino and [CircuitPython](https://learn.adafruit.com/rgb-led-matrices-matrix-panels-with-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](https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/library) for Arduino — it’s older code that works fine for AVR chips (and a couple others) but has some limitations. This guide was mostly to assist with **porting**  Adafruit\_Protomatter to new hardware, but has since been expanded with installation and basic use. “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.” ![led_matrices_trek3.jpg](https://cdn-learn.adafruit.com/assets/assets/000/091/089/medium640/led_matrices_trek3.jpg?1589248388) 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. - Mostly doesn’t rely on esoteric peripherals — sticks with basic “PORT” GPIO and a timer interrupt. _Some exceptions were made for ESP32-S3 and -S3._ - Mostly avoids 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. - [Next Page](https://learn.adafruit.com/adafruit-protomatter-rgb-matrix-library/installing-arduino-library.md) ## Featured Products ### Adafruit Matrix Portal - CircuitPython Powered Internet Display [Adafruit Matrix Portal - CircuitPython Powered Internet Display](https://www.adafruit.com/product/4745) Folks love our [wide selection of RGB matrices](https://www.adafruit.com/category/327) and accessories, for making custom colorful LED displays... and our RGB Matrix Shields and FeatherWings can be quickly soldered together to make the wiring much easier. But what if we made it... In Stock [Buy Now](https://www.adafruit.com/product/4745) [Related Guides to the Product](https://learn.adafruit.com/products/4745/guides) ### Adafruit RGB Matrix FeatherWing Kit - For nRF52840 Feathers [Adafruit RGB Matrix FeatherWing Kit - For nRF52840 Feathers](https://www.adafruit.com/product/4702) Ahoy! It's time to create a dazzling light up project with our new **RGB Matrix FeatherWing for nRF52840**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards. Using our RGB Matrix library... In Stock [Buy Now](https://www.adafruit.com/product/4702) [Related Guides to the Product](https://learn.adafruit.com/products/4702/guides) ### Adafruit RGB Matrix Featherwing Kit [Adafruit RGB Matrix Featherwing Kit](https://www.adafruit.com/product/3036) Ahoy! It's time to create a dazzling light up project with our new **RGB Matrix FeatherWing**. Now you can quickly and easily create projects featuring your favorite 16 or 32-pixel tall matrix boards. Using our RGB Matrix library is easy and... Out of Stock [Buy Now](https://www.adafruit.com/product/3036) [Related Guides to the Product](https://learn.adafruit.com/products/3036/guides) ### Adafruit RGB Matrix Shield for Arduino [Adafruit RGB Matrix Shield for Arduino](https://www.adafruit.com/product/2601) Our RGB matrices are dazzling, with their hundreds or even _thousands_ of individual RGB LEDs. Compared to NeoPixels, they've got great density, power usage and the price-per-LED can't be beat. But...(isn't there always a _but_?) You need to use our special library to... In Stock [Buy Now](https://www.adafruit.com/product/2601) [Related Guides to the Product](https://learn.adafruit.com/products/2601/guides) ### 64x64 RGB LED Matrix - 2.5mm Pitch [64x64 RGB LED Matrix - 2.5mm Pitch](https://www.adafruit.com/product/3649) Winter time can be rough in the city. The sky is gray. The weather is unpredictable. So slough off those seasonal blues with some Times Square razzle dazzle from this sweet, ultra-high-density **64x64 RGB LED Matrix**. These panels are typically used to make video... In Stock [Buy Now](https://www.adafruit.com/product/3649) [Related Guides to the Product](https://learn.adafruit.com/products/3649/guides) ### 64x64 RGB LED Matrix - 3mm Pitch [64x64 RGB LED Matrix - 3mm Pitch](https://www.adafruit.com/product/4732) Winter time can be rough in the city. The sky is gray. The weather is unpredictable. So slough off those seasonal blues with some Times Square razzle dazzle from this sweet, ultra-high-density **64x64 RGB LED Matrix**. These panels are typically used to make video... In Stock [Buy Now](https://www.adafruit.com/product/4732) [Related Guides to the Product](https://learn.adafruit.com/products/4732/guides) ### 64x32 RGB LED Matrix - 3mm pitch [64x32 RGB LED Matrix - 3mm pitch](https://www.adafruit.com/product/2279) Bring a little bit of Times Square into your home with this sweet 64 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked... In Stock [Buy Now](https://www.adafruit.com/product/2279) [Related Guides to the Product](https://learn.adafruit.com/products/2279/guides) ### 64x32 RGB LED Matrix - 4mm pitch [64x32 RGB LED Matrix - 4mm pitch](https://www.adafruit.com/product/2278) Bring a little bit of Times Square into your home with this sweet 64 x 32 square RGB LED matrix panel. These panels are normally used to make video walls, here in New York we see them on the sides of busses and bus stops, to display animations or short video clips. We thought they looked... In Stock [Buy Now](https://www.adafruit.com/product/2278) [Related Guides to the Product](https://learn.adafruit.com/products/2278/guides) ## Related Guides - [Adafruit RGB Matrix FeatherWings](https://learn.adafruit.com/rgb-matrix-featherwing.md) - [Adafruit MatrixPortal M4](https://learn.adafruit.com/adafruit-matrixportal-m4.md) - [Raspberry Pi LED Matrix Display](https://learn.adafruit.com/raspberry-pi-led-matrix-display.md) - [Bluetooth-Controlled Matrix LED Sign using Bluefruit Connect](https://learn.adafruit.com/bluetooth-controlled-matrix-led-sign-using-bluefruit-connect.md) - [LED Matrix FIFA World Cup Scoreboard](https://learn.adafruit.com/led-matrix-fifa-world-cup-scoreboard.md) - [Adafruit RGB Matrix + Real Time Clock HAT for Raspberry Pi](https://learn.adafruit.com/adafruit-rgb-matrix-plus-real-time-clock-hat-for-raspberry-pi.md) - [Matrix Portal Flow Visualizer](https://learn.adafruit.com/matrix-portal-flow-visualizer.md) - [Matrix Portal Sand Handles](https://learn.adafruit.com/matrix-portal-sand.md) - [Matrix Portal Creature Eyes](https://learn.adafruit.com/matrix-portal-creature-eyes.md) - [Matrix Portal Scoreboard](https://learn.adafruit.com/matrix-portal-scoreboard.md) - [Image Correction for RGB LED Matrices](https://learn.adafruit.com/image-correction-for-rgb-led-matrices.md) - [Stream Deck controlled RGB Message Panel using Adafruit IO](https://learn.adafruit.com/stream-deck-controlled-rgb-message-panel-using-adafruit-io.md) - [RGB Matrix Automatic YouTube ON AIR Sign](https://learn.adafruit.com/rgb-matrix-automatic-youtube-on-air-sign.md) - [AdaBox 016](https://learn.adafruit.com/adabox016.md) - [Adafruit PiCowbell CAN Bus for Pico](https://learn.adafruit.com/adafruit-picowbell-can-bus-for-pico.md) - [Using Board Package Tool to Update Adafruit Arduino Packages](https://learn.adafruit.com/using-board-package-tool-to-update-adafruit-arduino-packages.md)