Arduino library · LEDs

FastLED NeoMatrix: draw on a WS2812 LED matrix

Yes. You can use the FastLED NeoMatrix library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (Addressable RGB LEDs). The example below, "A box drawn into a FastLED CRGB array laid out as an 8x8 matrix", runs on the Arduino Uno R3.

Built in on Mokxi: #include <FastLED_NeoMatrix.h> and it builds, with nothing to install. Free, and no account needed.

What FastLED NeoMatrix does

FastLED NeoMatrix puts the Adafruit GFX drawing calls on a grid of WS2812 LEDs that FastLED drives. You get drawPixel(), drawRect(), fillScreen(), setCursor() and print() on an 8 by 8 panel or a longer strip folded into a grid, and FastLED does the colors, brightness and timing underneath.

The LED colors live in a CRGB array that your sketch owns, one entry for each LED. You give the array, the width and the height to the constructor, plus layout flags that say where the first LED is and how the strip snakes across the grid: from the top or bottom, left or right, in rows or columns, in a zigzag or all the same direction.

On a strip wired as a zigzag, the LEDs of the second row run backward. The layout flags are how the library knows that, so the pictures come out the right way up. The data pin goes to the first LED’s DIN, and the pin is named in FastLED.addLeds(), as it is for any FastLED strip.

Library Manager nameFastLED NeoMatrix
AuthorMarc Merlin
Include#include <FastLED_NeoMatrix.h>
BoardsArduino Uno, Arduino Nano, Arduino Mega 2560, Arduino Leonardo, SparkFun Pro Micro, Arduino Micro, Arduino Pro Mini 3.3 V, ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesAddressable RGB LEDs

Install it

It builds on Arduino Uno, Arduino Nano, Arduino Mega 2560, Arduino Leonardo, SparkFun Pro Micro, Arduino Micro, Arduino Pro Mini 3.3 V, ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6.

In Mokxi it is built in: #include <FastLED_NeoMatrix.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "FastLED NeoMatrix" by Marc Merlin from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add FastLED NeoMatrix to lib_deps in PlatformIO. Mokxi follows the calls of release 1.2.0, so a sketch written here builds there too.

What to know in the simulator: Colors widen each 5 or 6 bit channel to eight bits with no gamma curve. The boards are FastLED’s one-wire ones.

The calls you will use

In the order a sketch meets them.

CRGB leds[mw * mh]

One color for every LED in the matrix. The library draws into this array.

FastLED_NeoMatrix *matrix = new FastLED_NeoMatrix(leds, mw, mh, NEO_MATRIX_TOP + NEO_MATRIX_LEFT + NEO_MATRIX_ROWS + NEO_MATRIX_ZIGZAG)

Makes the matrix. The flags say the first LED is top left, the rows run across, and each row runs back the other way.

FastLED.addLeds<NEOPIXEL, PIN>(leds, mw * mh)

Tells FastLED which pin the data goes out on. The pin must be a constant known when the sketch compiles.

matrix->setBrightness(40)

Overall brightness from 0 to 255. A full-bright panel draws a lot of current, so a low value is gentler on the supply.

matrix->fillScreen(0)

Clears the matrix to black. The LEDs change at the next show().

matrix->drawRect(2, 2, 4, 4, matrix->Color(255, 0, 0))

Draws a rectangle outline from a corner, a width and a height, here in red.

matrix->drawPixel(0, 7, CRGB(0, 0, 255))

Sets one pixel, here the bottom left corner, to blue. It also takes a 16-bit color from Color().

matrix->XY(0, 7)

The position in the leds array of a pixel at x, y, which accounts for the layout flags. Use it to write the array directly.

matrix->show()

Sends the array to the strip, which is the same as FastLED.show().

Example: A box drawn into a FastLED CRGB array laid out as an 8x8 matrix

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
#include <Adafruit_GFX.h>
#include <FastLED_NeoMatrix.h>
#include <FastLED.h>

#define PIN 6
#define mw 8
#define mh 8

CRGB leds[mw * mh];
FastLED_NeoMatrix *matrix = new FastLED_NeoMatrix(leds, mw, mh,
  NEO_MATRIX_TOP + NEO_MATRIX_LEFT + NEO_MATRIX_ROWS + NEO_MATRIX_ZIGZAG);

void setup() {
  Serial.begin(9600);
  FastLED.addLeds<NEOPIXEL, PIN>(leds, mw * mh);
  matrix->begin();
  matrix->setBrightness(40);
  matrix->fillScreen(0);
  matrix->drawRect(2, 2, 4, 4, matrix->Color(255, 0, 0));  // 12 LEDs
  matrix->drawPixel(0, 7, CRGB(0, 0, 255));                // and a corner
  matrix->show();
  Serial.print("LED at (0, 7): ");
  Serial.println(matrix->XY(0, 7));
}

void loop() {}

Wiring

  • Arduino Uno R3 6 to Addressable RGB LEDs DIN
  • Arduino Uno R3 5V to Addressable RGB LEDs VDD
  • Arduino Uno R3 GND to Addressable RGB LEDs VSS

Open it in the editor, wired and ready to run

Common errors and how to fix them

The picture is mirrored, upside down or scrambled

The layout flags do not match how the panel is wired. Find the first LED, then set NEO_MATRIX_TOP or BOTTOM and LEFT or RIGHT for it, choose ROWS or COLUMNS for the direction the strip runs, and PROGRESSIVE or ZIGZAG for whether each row turns back.

A template argument must be a constant expression

FastLED.addLeds<NEOPIXEL, PIN> takes the pin as a template argument, so PIN must be a #define or a constant and not a variable. This is the most common FastLED compile error.

The colors on the LEDs are slightly different from the ones in the sketch

Color() makes a 16-bit 5-6-5 color, as Adafruit GFX does everywhere, so each channel loses a few low bits. For exact colors, pass a CRGB to drawPixel() as the example does for its corner pixel.

Try FastLED NeoMatrix without installing anything

Open the example, change the sketch, and keep your version in a free account.