This is an Arduino library for chained 8x8 LED dot matrix modules driven by the MAX7219. The reference of every class and function is on GitHub Pages.
Features:
- set and get single dots, rows and columns, in the same coordinates on every type of module
- draw lines, rectangles, circles and pictures from flash
- print chars and text (ASCII 32 to 126, the German umlauts, ß and °, variable char width)
- shift a char or a text over the matrix without blocking
loop(), at a pace the library keeps, once or over and over - shift the matrix content left, right, up and down, with or without rotation
- send a picture drawn with many calls at once, in at most eight frames
- all eight ways a module can be wired, mirrored ones included, and a board mounted upside down
- bit banging (any pins) or hardware SPI
- a simulator that runs the examples on the PC, in the terminal or in a browser
- a control program for Linux and Windows that drives a board or the simulator over SerialControl
Download the repository as ZIP and add it in the Arduino IDE with Sketch > Include Library > Add .ZIP Library...,
or clone it into your Arduino/libraries folder.
| Module | Arduino Uno / Nano |
|---|---|
| VCC | 5V |
| GND | GND |
| DIN | 11 |
| CS | 10 |
| CLK | 13 |
In bit banging mode any digital pins can be used. With hardware SPI, DIN and CLK must be connected to the SPI pins of the board (MOSI and SCK).
The configuration is done in src/MaxMatrixConfig.h:
| Parameter | Default | Description |
|---|---|---|
MAXMATRIX_USE_SPI |
STD_OFF |
use hardware SPI instead of bit banging on any pins |
MAXMATRIX_SPI_CLOCK_SPEED |
10000000 |
SPI clock, the MAX7219 supports max. 10 MHz |
MAXMATRIX_SPACE_BETWEEN_CHARS_INIT_VALUE |
1 |
empty columns between chars |
MAXMATRIX_INTENSITY_INIT_VALUE |
5 |
LED intensity after Init() (0 to 15) |
MAXMATRIX_SHIFT_INTERVAL_INIT_VALUE |
50 |
ms per column of a shifting text, 0 for every call |
MAXMATRIX_COMMAND_LINE_LENGTH |
64 |
longest command line of max_matrix::Command, in chars |
MAXMATRIX_DEV_ERROR_DETECT |
STD_OFF |
report every failed call, see Functions |
The length of the chain is not configured here but in the sketch, where the Arduino IDE lets it change: max_matrix::MatrixOf<4>
is a matrix of four modules and brings their buffer, eight bytes per module, and max_matrix::MatrixOf<8> one of eight, up to 31.
A chain whose length is known only at run time hands MaxMatrix a buffer of its own, whose length says how many
modules there are:
max_matrix::array<max_matrix::Byte, max_matrix::BufferSize(6)> buffer;
max_matrix::Matrix matrix(11, 10, 13, buffer);#include <MaxMatrix.h>
max_matrix::MatrixOf<4> matrix(11, 10, 13); // a chain of 4 modules at DIN, CS, CLK
char const kText[] = "Hello World! ";
void setup()
{
matrix.Init();
matrix.SetModuleType(max_matrix::ModuleType::kFc16); // see "Module type"
matrix.SetTextWithShift(kText, true); // over and over
}
void loop()
{
matrix.ShiftTask(); // shifts the text one column every 50 ms
}ShiftTask() keeps the pace itself: call it on every loop(), and it takes a step only when the shift interval has
passed since the last one. SetShiftInterval() sets the interval in milliseconds per column; with 0 every call is a
step, for a sketch that times the steps itself. A call that comes late, because loop() was busy, takes one step and
does not catch up.
With true, SetTextWithShift() starts the text over with its first char right after its last, so the spaces at the
end of the text keep the two apart; StopShift() ends it. SetTextWithShift() only keeps where the text is and how
long, so the text has to stay valid as long as it shifts.
A text in quotes or in a char array passes as it is, and its length goes with it: the text ends at its null
character or at the end of its array, whichever comes first. A text known only by a pointer, as String::c_str()
gives one, goes with its length: matrix.SetText({text, strlen(text)}).
More examples can be found in examples/:
| Example | Shows |
|---|---|
| Basics | text, dots, rows, a picture drawn in one go, the intensity |
| ScrollText | one text scrolling endlessly, without blocking loop() |
| Messages | several texts in turn, each at its own speed, with umlauts |
| Animation | a ball bouncing off the edges, one picture per step |
| Sprites | a sprite of its own walking across, with two frames |
| Shapes | a frame, lines, circles and a picture from flash, one after the other |
| Shutdown | the LEDs off while drawing goes on, and the display test |
| Band | a heartbeat without end, a column from flash coming in at every step |
| SerialControl | the matrix controlled by lines of text over Serial |
SetDot(x, y) counts x from the left and y from the top, across all modules: x from 0 to
GetNumberOfColumns() - 1, eight columns per module, y from 0 to 7. Module 0 is the leftmost, at the far end of the chain from DIN.
This holds for every type of module once the module type is set, see Module type.
Eight LEDs at once are a max_matrix::Byte, a byte of dots that is no number, so that a column and its value
cannot be swapped: matrix.SetColumn(3, max_matrix::Byte{0x3C}). ToInteger() gives its bits as a number, and it
takes the bitwise operators &, |, ~, << and >>, as std::byte does. The two functions that set eight LEDs
at once read their byte in different directions:
SetColumn(x, value)sets a column, bit 0 at the top.SetRow(module, row, value)sets the row of one module, bit 7 on the left, so the byte reads as it is written:max_matrix::Byte{0b10000000}lights the leftmost LED.SetRow(row, values)sets a whole row, an array of oneByteper module, module 0 first.
| Function | What it does |
|---|---|
Init() |
sets up the pins and every MAX7219, clears the LEDs and sets the intensity |
Clear() |
turns every LED off |
SetDot(x, y, value), GetDot(x, y) |
one LED |
SetColumn(x, value), SetColumn(module, column, value), GetColumn(…) |
a column, bit 0 at the top |
SetRow(row, values), SetRow(module, row, value), GetRow(…) |
a row, bit 7 on the left |
SetChar(x, y, c), SetText(text) |
a char at x, y, or a text from the left edge |
SetSprite(x, y, sprite) |
a sprite of your own, up to 5 columns wide |
DrawLine(x0, y0, x1, y1, value) |
a straight line, both ends included |
DrawRect(x, y, width, height, value), FillRect(…) |
the outline of a rectangle, or the rectangle with its inside |
DrawCircle(x, y, radius, value) |
the outline of a circle; radius 3 fills the height |
DrawBitmap(x, y, bitmap), DrawBitmap(x, y, height, bitmap) |
a picture in PROGMEM, a column per byte as wide as its array, bit 0 at the top |
SetFont(font), GetFont() |
the font every char is drawn in, see below |
SetCharWithShift(c), SetTextWithShift(text, repeat), ShiftTask(), GetState() |
a char or a text that shifts in from the right, a text once or over and over |
StopShift() |
stops a shifting char or text where it stands |
SetShiftInterval(milliseconds), SetSpaceBetweenChars(columns) |
how fast a text shifts and how far apart its chars are |
ShiftLeft(fill), ShiftRight(fill), ShiftUp(fill), ShiftDown(fill) |
moves the whole picture by one dot; what comes in is empty, what fell out at the other edge, or kept: max_matrix::ShiftFill::kZero, kRotate, kKeep |
ShiftLeft(column), ShiftRight(column) |
moves the picture by one column and brings column in, bit 0 at the top; returns the column that fell out |
GetNumberOfModules(), GetNumberOfColumns() |
the length of the chain, eight columns per module |
SetIntensity(intensity) |
brightness of every module, 0 to 15 |
SetShutdown(on) |
turns the LEDs off without losing the picture, which still takes what is drawn |
SetDisplayTest(on) |
lights every LED at full brightness, to check the modules, and shows the picture again |
max_matrix::Batch, SetAutoUpdate(on), Update() |
holds the sending back, see below |
SetModuleType(…), SetMatrixOrientation(…) |
fits the coordinates to the module, see below |
RegisterWrite(address, value) |
writes a register of every MAX7219, past the picture |
max_matrix::Command, Feed(matrix, c, answer) |
carries out commands that arrive as lines of text, see below |
Drawing leaves out whatever lies off the panel, so that a sprite or a text may stand partly off it while it moves
in or out: SetDot(-1, 0, true) does nothing, and a char at x = -2 shows its right part. x and y may be negative,
and so may the ends of a line or the centre of a circle. value false turns the dots off rather than on.
A function that can fail says why, and changes nothing when it does. A getter returns the value together with the
error, so ask IsOk() before you use GetValue():
max_matrix::Result<bool> lit = matrix.GetDot(x, y);
if(lit.IsOk() && lit.GetValue()) { /* the LED at x, y is on */ }
max_matrix::Status status = matrix.SetText(text);
if(status == max_matrix::Error::kUnknownChar) { /* the font lacks a char of Text */ }The errors are max_matrix::Error::kOutOfRange, max_matrix::Error::kUnknownChar and max_matrix::Error::kNoText, and from
max_matrix::Command also max_matrix::Error::kNotANumber, max_matrix::Error::kUnknownCommand and max_matrix::Error::kLineTooLong;
max_matrix::Error::kOk means none. A status is not a bool: write Status.IsOk(), not if(Status).
Serial.println(Status.GetErrorText()) prints the error in words, such as out of range; the texts lie in flash,
and a sketch that never asks for one does not carry them.
To find a call that fails where the sketch checks nothing, switch MAXMATRIX_DEV_ERROR_DETECT to STD_ON: in
MaxMatrixConfig.h, as the Arduino IDE passes no define of a sketch to a library, or with arduino-cli as
--build-property "compiler.cpp.extra_flags=-DMAXMATRIX_DEV_ERROR_DETECT=STD_ON". Every function that fails then
prints a line on Serial, such as MaxMatrix SetText: unknown char, so call Serial.begin() in setup(). A sketch
whose Serial carries something else, or which would rather blink or halt, defines the report itself, and the one
that prints is left out:
void max_matrix::ReportError(__FlashStringHelper const* api, max_matrix::Error error)
{
digitalWrite(LED_BUILTIN, HIGH);
}Switched off, as it is by default, the reports cost nothing. Switched on, Basics grows by 1158 bytes of flash and
179 of RAM, most of it Serial; with a report of its own, by little more than the names of the functions it calls.
In SerialControl a text= with a char the font lacks is then reported as well, in a line before its answer.
Every call that draws shows its result before it returns, and sends only what it changed: at most eight frames to
the chain, however much it drew. A picture made of many calls would still be shown half drawn in between. For that,
draw it inside a block that starts with a max_matrix::Batch; the picture is sent at the end of the block:
{
max_matrix::Batch batch(matrix); // nothing is sent until the end of this block
matrix.Clear();
for(uint8_t column = 0; column < matrix.GetNumberOfColumns(); column++) matrix.SetDot(column, column % 8, true);
} // the whole picture at once, in at most eight framesThe batch needs a name: max_matrix::Batch{Matrix}; on its own is gone again before the next line and holds nothing
back. Batches can be nested; only the outermost one sends.
A picture that is built over several calls of loop() does not fit into a block. There, turn the automatic update
off with SetAutoUpdate(false) and send with Update() whenever the picture is complete.
SetIntensity() takes effect at once either way. Init() always clears the LEDs, whatever the setting.
max_matrix::Command carries out commands that arrive as lines of text, one command per line:
| Command | What it does |
|---|---|
text=Hello |
shows a text from the left edge, on a cleared matrix |
textShift=Hello |
shifts a text in from the right |
intensity=8 |
brightness, 0 to 15 |
speed=50 |
milliseconds per column of a shifting text |
space=1 |
empty columns between chars |
setDot=5,3,1 |
column, row, 1 for on and 0 for off |
clear |
turns every LED off |
picture |
answers with what the matrix shows |
A line ends in \n or \r\n. Feed() answers each line on the Print it is given, as a rule Serial, with one line:
ok, or error: and the reason, or for picture with picture= and two hex digits per column, from the left as the
viewer sees it, bit 0 the top row. The SerialControl example reads the lines from Serial at 115200 baud; the serial monitor of the
Arduino IDE sends them with "Newline" as line ending:
max_matrix::Command command;
void loop()
{
while(Serial.available() > 0) command.Feed(matrix, Serial.read(), Serial);
matrix.ShiftTask();
}Feed() also returns what became of the line: max_matrix::CommandState::kPending while it goes on,
max_matrix::CommandState::kDone when it is carried out, max_matrix::CommandState::kAnswered after picture, and
why it failed otherwise: intensity=16 is max_matrix::Error::kOutOfRange, intensity=x max_matrix::Error::kNotANumber. A line
longer than MAXMATRIX_COMMAND_LINE_LENGTH is dropped whole rather than carried out cut short. The class keeps the
line and the text of textShift=, so it takes twice that length in RAM; a sketch that does not use it pays nothing.
The simulator's page has buttons for the commands, and a click on an LED switches it. They drive the simulator when it
runs SerialControl, and a board running SerialControl as well, connected with Connect board over the browser's Web
Serial API: every command goes to both, so the panel shows what the board should. Web Serial needs Chrome or Edge, and
the page served by the simulator on localhost is enough for it, even with a board alone:
build/Simulator-SerialControl-bitbang --webOpening the port resets an Uno; the page sends the board nothing until SerialControl has said ready.
control/ holds the same controls as a program of its own, for a browser without Web Serial and for whoever wants a
window rather than a page, laid out as the Windows tool of Led-Matrix was,
but for its tabs: the whole panel on top, below it the text, Shift in, the space and the intensity and speed
sliders, and on the right the board's serial port, the simulator and a log of every line and answer. Every command goes
to the board and to the simulator, whichever is connected.
The panel shows what the board shows, or the simulator while no board is ready: the program asks SerialControl for
its picture up to twenty times a second, so a text that shifts in moves there as well, and a click switches the LED
that is lit or dark on the matrix; moved with the button held, the mouse paints every LED it passes the way the first
one went. Beside the text the window counts the bytes it may still take in SerialControl's line, an umlaut two, and
sends no line that would be dropped. When SerialControl starts, or the simulator is connected, the program sends it the
intensity, speed and space the window shows.
It is built with the rest when CMake finds wxWidgets 3.2 (apt install libwxgtk3.2-dev, in the dev container
already), and runs the simulator over a TCP port that --tcp opens beside the page:
build/Simulator-SerialControl-bitbang --tcp 8081 &
build/control/MaxMatrixControlOn Windows, cmake -S control -B build-control is meant to build the program alone, against a wxWidgets found by CMake;
its serial port and socket code compile with MinGW, but the program has not been built or run on Windows yet. The board's ports are listed as COM ports there and as /dev/ttyACM* and /dev/ttyUSB* on Linux; another name can
be typed into the box. As on the page, nothing goes to a board until SerialControl has said ready.
Two settings make the text upright:
SetModuleType()says how the LEDs of a module are wired to its MAX7219. The types are named as the hardware types of MD_MAX72XX, so a module that works there withFC16_HWtakesmax_matrix::ModuleType::kFc16here.SetMatrixOrientation()turns the whole display by 0 or 180 degrees, for a board mounted upside down, with the input (DIN) on the left.
| Module | Module type |
|---|---|
FC-16 (FC16_HW), the common 4-in-1 boards |
max_matrix::ModuleType::kFc16 (checked on hardware) |
Parola (PAROLA_HW) |
max_matrix::ModuleType::kParola |
ICStation (ICSTATION_HW) |
max_matrix::ModuleType::kIcstation |
Generic (GENERIC_HW) |
max_matrix::ModuleType::kGeneric |
DR0CR0RR0_HW to DR1CR1RR1_HW |
max_matrix::ModuleType::kDr0Cr0Rr0 to kDr1Cr1Rr1 |
For a module of unknown type, try the four named ones first; if none of them shows the text upright, one of the four others does. With the input on the right, the matrix orientation stays at max_matrix::MatrixOrientation::k0; mounted upside down, it is max_matrix::MatrixOrientation::k180 with the same module type.
How the bytes of the MAX7219 lie on the LEDs of each module type is drawn in docu/; a sketch does not need it, only work on the library does.
The German umlauts Ä, Ö, Ü, ä, ö and ü, the ß and the degree sign ° are supported in texts. SetText() and SetTextWithShift() accept UTF-8 (the encoding of the Arduino IDE) and ISO 8859-1.
SetChar() and SetCharWithShift() take a single char, so these have to be passed as ISO 8859-1 code there, e.g. '\xE4' for ä, '\xDF' for ß or '\xB0' for °.
The € is not in ISO 8859-1, and its three bytes of UTF-8 are not read.
While shifting a text, chars which are not part of the font are skipped.
A font is an array of bytes in flash, in the font format of MD_MAX72XX,
so that its fonts and its font builder serve here as well: 'F', the version, the code of the first char, that of
the last, and the height in rows, and then every char from the first to the last as its width and that many columns,
bit 0 the top row. A char of width 0 is not in the font. Version 1 gives each code in one byte, version 2 in two, high
byte first. A char may be wider than a sprite's 5 columns.
The bytes go into max_matrix::make_array<uint8_t>(), which counts them, rather than a C array: a font of
MD_MAX72XX keeps its bytes as they are, and only its first and its last line change. A value that does not fit a byte
stops the build.
constexpr auto kDigits PROGMEM{max_matrix::make_array<uint8_t>(
'F', 1, '0', '1', 7, // version 1, the chars 0 to 1, 7 rows high
3, B00111110, B01000001, B00111110, // 0
2, B01000010, B01111111)}; // 1
matrix.SetFont(kDigits); // max_matrix::Error::kNotAFont for an array that is not a font of its length
matrix.SetText("10");
matrix.SetFont(max_matrix::kDefaultFont); // the font MaxMatrix starts withSetFont() takes the array with its length, so that the chars from the first to the last have to fill it exactly,
and no char can then be read past its end. A font forgotten in RAM, without PROGMEM, is refused as well, almost
always, as the Uno reads it from flash. A font known only by its address, from a table of fonts, goes with its
length: SetFont({font, sizeof(kDigits)}).
The font has to stay where it is as long as it is set, as a PROGMEM array does. Chars are looked up by their latin-1
code, the one DecodeChar() makes of UTF-8. The default font holds ASCII and the chars of Umlauts, 8 rows
high, in 614 bytes; a sketch that draws no char does not link it.
The host-side tests build the library against a mock of the Arduino core, once with bit banging and once with SPI:
cmake --workflow --preset defaultThey need g++, CMake, Ninja and GoogleTest (apt install cmake ninja-build libgtest-dev). Compiling the examples with the real AVR toolchain needs arduino-cli with the arduino:avr core:
arduino-cli compile --fqbn arduino:avr:uno --library . examples/ScrollTextBoth run in CI on every pull request, together with arduino-lint.
Every example also builds into a simulator, which runs the sketch unchanged on the PC and draws the panel in the terminal, as a module of the given type would show it:
build/Simulator-ScrollText-bitbang --wiring FC16--wiring takes FC16 (the default), GENERIC, PAROLA, ICSTATION or DR0CR0RR0 to DR1CR1RR1, and --upside-down turns the board around. A sketch with the wrong module type shows the text turned or mirrored, as the hardware would.
With --web it draws in a browser instead, on http://localhost:8080/, which VS Code forwards out of the dev container: the panel with the brightness of every module, the frames on the wire, the module type and mounting to switch while the sketch runs, and the controls of Control over Serial. --port picks another port, for a second simulator beside it. --tcp PORT opens the sketch's Serial as a TCP port on localhost, for the control program: what it sends, the sketch reads, and what the sketch prints, it gets back.
build/SimulatorAvr runs the same, but with the binary avr-gcc made for the Uno rather than with the sketch built for
the PC: simavr simulates the ATmega328P, and its pins and SPI drive the MAX7219
model. CMake builds the examples for it with arduino-cli into build/avr/ when it finds both:
build/SimulatorAvr --elf build/avr/bitbang/ScrollText/ScrollText.ino.elf --wiring FC16Wokwi runs the real AVR binary as well, on a simulated Uno with four FC-16 modules at pins 11, 10
and 13, so that the bit banging and the SPI of the board are what drive the LEDs. diagram.json and wokwi.toml in
the root describe that board; build an example into the file wokwi.toml names and start it with Wokwi: Start
Simulator from the Wokwi extension for VS Code, which is free for
open source:
tools/wokwi.py Sprites # or with --spi, for hardware SPI on the same pinsWokwi has two of the eight module types (FC-16 and Parola) and shows no frames; the simulator above covers those.
The pictures in docu/ are drawn from the library and the MAX7219 model, not by hand. After a change
that moves a dot, build/DocuPictures --write docu draws them again; until then the test docu/pictures fails.