LedControl: MAX7219 matrices and digit displays
LedControl, by Eberhard Fahle, drives the MAX7219: the chip on the red 8x8 dot matrix modules and the eight-digit seven-segment boards. One MAX7219 handles 64 LEDs, and up to eight of them can be chained, each passing data on to the next, all from three Arduino pins: DIN (data), CLK and CS (also marked LOAD).
Built in on Mokxi: #include <LedControl.h> and it builds, with nothing to install. Free, and no account needed.
What LedControl does
Every call takes the device number first, 0 for the module nearest the board. The library talks to the chip over software SPI, so the three pins can be any digital pins, and it starts every chip in power-saving shutdown. Nothing lights until the sketch wakes each one with shutdown(addr, false), which is the single most common reason a first LedControl sketch shows nothing.
On a matrix, setRow() takes a byte where each bit is one LED, which makes drawing small pictures easy: write the picture as eight binary numbers. The four-in-one FC-16 boards are wired rotated, so on those a row in the code can come out as a column on the module.
| Library Manager name | LedControl |
|---|---|
| Author | Eberhard Fahle |
| Include | #include <LedControl.h> |
| Boards | every board Mokxi compiles for but ATtiny85 |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | LED matrix, 8x8, Eight-digit display, MAX7219 |
Install it
It builds on every board Mokxi compiles for but ATtiny85.
In Mokxi it is built in: #include <LedControl.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "LedControl" by Eberhard Fahle from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add LedControl to lib_deps in PlatformIO. Mokxi follows the calls of release 1.0.6, so a sketch written here builds there too.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
LedControl lc = LedControl(12, 11, 10, 1)
DIN, CLK and CS pins, and how many chips are chained (1 to 8).
lc.shutdown(0, false)
Wakes device 0 from the power-saving mode it starts in. Call it for every device in the chain in setup().
for (int d = 0; d < lc.getDeviceCount(); d++) {
lc.shutdown(d, false);
lc.setIntensity(d, 8);
lc.clearDisplay(d);
}lc.setIntensity(0, 8)
Brightness of one device, from 0 to 15.
lc.clearDisplay(0)
Turns every LED of one device off.
lc.setRow(0, row, 0b00111100)
Sets the eight LEDs of a row from one byte, a bit per LED. setColumn() does the same for a column.
byte smile[8] = {0x3C, 0x42, 0xA5, 0x81, 0xA5, 0x99, 0x42, 0x3C};
for (int r = 0; r < 8; r++) lc.setRow(0, r, smile[r]);lc.setLed(0, row, col, true)
Turns a single LED on or off, for a moving dot or a snake game.
lc.setDigit(0, 3, 7, false)
On a seven-segment board, shows digit 7 in position 3; the last argument lights the decimal point. setChar() shows the few letters the chip knows.
Example: Light-up Valentine heart
On the Arduino Uno R3. It runs in the browser exactly as printed.
// Light-up Valentine heart: a heart on an 8x8 LED matrix that beats, a big
// beat and a small one, lub-dub, at a pace you set with a knob.
//
// MAX7219 8x8 matrix module: DIN -> pin 11, CLK -> pin 13, CS -> pin 10,
// VCC -> 5 V, GND -> GND
// knob potentiometer wiper -> A0, ends to 5 V and GND
//
// Each picture is eight bytes, one per row, a 1 for every lit LED, so the big
// heart and the small heart are two short tables. A heartbeat is not one
// thump: it is two close together and then a rest, so the sketch shows the
// big heart, the small one, the big one again, then rests on the small one.
//
// The knob sets the beats a minute, from a calm 50 to an excited 140. Put the
// matrix behind a sheet of red tissue paper in a card or a little frame and
// it glows like one heart instead of 64 dots.
//
// Things to try. Turn the knob. Draw your own picture in BIG or SMALL: a
// smiling face, or your initials.
#include <LedControl.h>
LedControl matrix(11, 13, 10, 1); // DIN, CLK, CS, one module
const uint8_t BIG[8] = {
0b01100110,
0b11111111,
0b11111111,
0b11111111,
0b01111110,
0b00111100,
0b00011000,
0b00000000,
};
const uint8_t SMALL[8] = {
0b00000000,
0b00100100,
0b01111110,
0b01111110,
0b00111100,
0b00011000,
0b00000000,
0b00000000,
};
int beats = 0;
void draw(const uint8_t picture[8]) {
for (int row = 0; row < 8; row++) matrix.setRow(0, row, picture[row]);
}
void setup() {
Serial.begin(9600);
matrix.shutdown(0, false);
matrix.setIntensity(0, 8);
matrix.clearDisplay(0);
draw(SMALL);
Serial.println("Be my Valentine: the heart is beating");
}
void loop() {
int bpm = map(analogRead(A0), 0, 1023, 50, 140);
unsigned long beat = 60000UL / bpm;
// Lub, dub, rest.
draw(BIG);
delay(beat / 8);
draw(SMALL);
delay(beat / 10);
draw(BIG);
delay(beat / 8);
draw(SMALL);
beats++;
if (beats % 10 == 1) {
Serial.print("Beat ");
Serial.print(beats);
Serial.print(" at ");
Serial.print(bpm);
Serial.println(" beats a minute");
}
delay(beat - beat / 8 - beat / 10 - beat / 8);
}Open it in the editor, wired and ready to run 路 Light-up Valentine heart: the project page
Common errors and how to fix them
The module stays dark after upload
The MAX7219 starts in shutdown. Call lc.shutdown(0, false) in setup() for each device, then set an intensity; without it the chip receives data but never lights.
Only the first module of a chain shows anything
The last constructor argument is the number of devices and defaults to 1. Pass the real count, and address the others as 1, 2 and so on.
Pictures come out rotated or mirrored on a 4-in-1 board
FC-16 style modules wire the matrix turned 90 degrees. Draw with setColumn() in place of setRow(), flip the bit order, or use the MD_MAX72XX library, which knows that hardware type.
Projects that use LedControl
Built-in projects that include it. Each page has the full sketch and opens in the editor, already wired.
Keep going
Learn
More displays libraries
Try LedControl without installing anything
Open the example, change the sketch, and keep your version in a free account.