MaxMatrix
Drive chained 8x8 LED dot matrix modules with MAX7219.
Loading...
Searching...
No Matches
MaxMatrix

CI static analysis issues

[license](LICENSE) release

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

Installation

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.

Wiring

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).

Configuration

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::Matrix matrix(11, 10, 13, buffer);
constexpr size_t BufferSize(size_t modules)
The bytes of the buffer of a chain, one per column.
Definition MaxMatrixConfig.h:100
A byte of raw data: eight dots of a column or a row, or the value of a register of the MAX7219.
Definition Byte.h:45
The matrix a sketch draws on: a chain of 8x8 modules, in the coordinates the viewer sees.
Definition MaxMatrix.h:81
A C array of N elements that knows its size.
Definition array.h:42

Usage

#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
}
The header a sketch includes: the matrix it draws on.
@ kFc16
Definition Panel.h:71
A Matrix with the buffer for a chain of NumberOfModules modules.
Definition MaxMatrix.h:734

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

Coordinates

Coordinates as a sketch uses them

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 one Byte per module, module 0 first.

Functions

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 */ }
@ kUnknownChar
Definition MaxMatrixError.h:49
What a getter of a single value returns: the value, or why there is none.
Definition MaxMatrixError.h:141
MAXMATRIX_NODISCARD ValueType GetValue() const
Returns the value; 0, or what ValueType() is, after an error.
Definition MaxMatrixError.h:170
MAXMATRIX_NODISCARD bool IsOk() const
Returns whether there is a value.
Definition MaxMatrixError.h:181
What a function that can fail returns when it has no value to return.
Definition MaxMatrixError.h:73

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);
}
Error
Why a call did not do what it was asked; one byte, so that it returns in a register.
Definition MaxMatrixError.h:45

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.

Drawing a picture in one go

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 frames
Holds the sending back for as long as it exists, as std::lock_guard holds a mutex.
Definition MaxMatrix.h:670

The 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.

Control over Serial

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:

void loop()
{
while(Serial.available() > 0) command.Feed(matrix, Serial.read(), Serial);
matrix.ShiftTask();
}
The lines of text a control page or program sends, carried out on a Matrix.
Definition Command.h:75
Result< CommandState > Feed(Matrix &matrix, char c, Print &answer)
Takes the next char of a command line, and carries the line out and answers it at its end.

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 --web

Opening the port resets an Uno; the page sends the board nothing until SerialControl has said ready.

The control program

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/MaxMatrixControl

On 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.

Module type

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 with FC16_HW takes max_matrix::ModuleType::kFc16 here.
  • 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.

Umlauts

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.

Fonts

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 with
array< uint8_t, kDefaultFontSize > const kDefaultFont
The font MaxMatrix starts with: ASCII from the space to the tilde, the German umlauts,...
constexpr array< T, sizeof...(Values)> make_array(Values... values)
Returns an array of T of its values, with the size taken from them.
Definition array.h:185

SetFont() 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.

Development

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 default

They 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/ScrollText

Both 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 FC16

Wokwi 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 pins

Wokwi 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.