|
MaxMatrix
Drive chained 8x8 LED dot matrix modules with MAX7219.
|
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:
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:
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:
| 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():
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:
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:
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.
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:
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:
Opening 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:
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.
Two settings make the text upright:
| 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.
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.
The host-side tests build the library against a mock of the Arduino core, once with bit banging and once with SPI:
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:
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:
--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:
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:
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.