Arduino_LED_Matrix: the Uno R4 WiFi’s 12 by 8 LEDs
The Arduino Uno R4 WiFi has a grid of 96 red LEDs on the board itself, 12 columns by 8 rows, and Arduino_LED_Matrix is the library its core includes for drawing on it. Nothing needs installing: select the Uno R4 WiFi board and the header is there. On the Uno R4 Minima, which has no matrix, the header does not exist.
Built in on Mokxi: #include <Arduino_LED_Matrix.h> and it builds, with nothing to install. Free, and no account needed.
What Arduino_LED_Matrix (Uno R4 core) does
The LEDs are charlieplexed on eleven pins, so a picture is never on all at once. The library lights them a few at a time from a timer interrupt, fast enough to look steady, which is why you should always draw through it rather than toggling the pins yourself.
A picture can be given two ways. renderBitmap() takes a plain 8 by 12 array of ones and zeros, easy to type by hand. loadFrame() takes three 32-bit numbers, the compact form Arduino’s online LED Matrix Editor exports, along with whole animations you play with loadSequence() and play().
| Library Manager name | Arduino_LED_Matrix (Uno R4 core) |
|---|---|
| Author | Arduino |
| Include | #include <Arduino_LED_Matrix.h> |
| Boards | Arduino Uno R4 WiFi |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
Install it
It builds on Arduino Uno R4 WiFi.
In Mokxi it is built in: #include <Arduino_LED_Matrix.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board it comes with the board package (Arduino), so the Arduino IDE has it as soon as the board is installed: there is nothing to add from the Library Manager.
The calls you will use
In the order a sketch meets them.
ArduinoLEDMatrix matrix
The board’s matrix. There is only one, so one object.
matrix.begin()
Starts the timer that keeps the LEDs lit. Call it once in setup().
matrix.renderBitmap(frame, 8, 12)
Shows an 8 by 12 array where each element is 1 for on and 0 for off, row by row from the top left.
uint8_t frame[8][12] = {0};
frame[3][5] = 1;
frame[3][6] = 1;
matrix.renderBitmap(frame, 8, 12);matrix.loadFrame(heart)
Shows a frame of three uint32_t values, 96 bits, as the LED Matrix Editor exports it.
matrix.loadSequence(animation)
Loads an animation: an array of frames, each three words of LEDs and a fourth giving how many milliseconds to show it.
matrix.play(true)
Plays the loaded sequence, looping when passed true. sequenceDone() tells you when a one-shot sequence has finished.
matrix.clear()
Turns every LED off.
Example: Uno R4 WiFi heart
On the Arduino Uno R4 WiFi. It runs in the browser exactly as printed.
// Matrix: a heart on the Uno R4 WiFi's 12 x 8 LED matrix, beating.
//
// The picture is eight rows of twelve, written the way it looks: a 1 is a lit
// LED. renderBitmap() hands it to the library, and the library does the hard
// part in the background: the matrix is ninety-six LEDs on only eleven pins,
// so it lights one pin's worth at a time, a millisecond each, faster than an
// eye can follow. Nothing on the board remembers the picture; the sketch just
// changes it.
//
// The LED on pin 13 blinks with the beat, so the two lamps show the same
// thing: one on its own pin, one ninety-sixth of a charlieplexed panel.
#include "Arduino_LED_Matrix.h"
ArduinoLEDMatrix matrix;
const uint8_t BIG[8][12] = {
{0, 0, 1, 1, 0, 0, 0, 0, 1, 1, 0, 0},
{0, 1, 1, 1, 1, 0, 0, 1, 1, 1, 1, 0},
{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1},
{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1},
{0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0},
{0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0},
{0, 0, 0, 1, 1, 1, 1, 1, 1, 0, 0, 0},
{0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0},
};
const uint8_t SMALL[8][12] = {
{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
{0, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 0},
{0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0},
{0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0},
{0, 0, 0, 1, 1, 1, 1, 1, 1, 0, 0, 0},
{0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0},
{0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0},
{0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
};
void setup() {
Serial.begin(115200);
pinMode(LED_BUILTIN, OUTPUT);
matrix.begin();
Serial.println("a heart on the LED matrix");
}
void loop() {
matrix.renderBitmap(BIG, 8, 12);
digitalWrite(LED_BUILTIN, HIGH);
delay(400);
matrix.renderBitmap(SMALL, 8, 12);
digitalWrite(LED_BUILTIN, LOW);
delay(600);
}Open it in the editor, wired and ready to run · Uno R4 WiFi heart: the project page
Common errors and how to fix them
fatal error: Arduino_LED_Matrix.h: No such file or directory
The selected board is not the Uno R4 WiFi. Choose Arduino Uno R4 WiFi under Arduino UNO R4 Boards; the Uno R4 Minima and the classic Uno have no matrix and no such header.
The picture is drawn sideways or squashed
renderBitmap() expects 8 rows of 12 columns. Declare the array as [8][12], not [12][8], and pass 8 and 12 in that order.
An animation shows one frame and stops
play() without an argument plays the sequence once. Call matrix.play(true) to loop it, and do not call loadFrame() afterward, which replaces the sequence.
Keep going
More leds libraries
Try Arduino_LED_Matrix (Uno R4 core) without installing anything
Open the example, change the sketch, and keep your version in a free account.