Arduino - LED Matrix
LED matrix display, also known as LED display, or dot matrix display, are wide-used. In this tutorial, we are going to learn:
- LED matrix
- How to connect Arduino to 8x8 LED matrix
- How to connect Arduino to 32x8 LED matrix
- How to connect Arduino to display text, numbers, and animated effects on the LED matrix.
After that, you can easily adapt the code for other LED matrices such as 16x8 LED matrix, 64x8 LEd matrix ...
Hardware Required
Or you can buy the following kits:
| 1 | × | DIYables STEM V3 Starter Kit (Arduino included) | |
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Disclosure: Some links in this section are Amazon affiliate links. If you make a purchase through these links, we may earn a commission at no extra cost to you.
Additionally, some links direct to products from our own brand, DIYables .
Additionally, some links direct to products from our own brand, DIYables .
About LED Matrix
There are many kinds of LED Matrix. With Arduino, the MAX7219-based LED matrix is widely used. MAX7219-based LED matrix has the following features:
- A base unit of an LED matrix is a block
- Each block has an 8x8 LED matrix (64 LED) and a MAX7219 driver.
- There are two popular block forms: the generic module and the FC-16 module.
- A LED matrix can be composed of a single block or multiple blocks in a daisy-chain
- You can buy a pre-built multiple-block LED Matrix (e.g. 4-in-1, 8-in-1)
- You can also buy multiple blocks and wire them to form a LED matrix with the desired size.
- You will declare the size of the LED matrix you use in the Arduino code.
Pinout
A LED Matrix is formed by a single or multiple blocks. Each block includes two groups of pins:
- Input pins group:
- VCC: connected to 5V.
- GND: connected to GND.
- DIN is the Data pin, Connect it to SPI MOSI pin of the Arduino.
- CS: Chip Select, Connect it to any digital pin of the Arduino.
- CLK: Clock pin, Connect it to SPI CLK pin of the Arduino.
- Output pins group:
- VCC: connects to VCC on the next module.
- GND: connects to GND on the next module.
- DOUT: Data Out, connects to the DIN pin of the next module.
- CS: connects to CS on the next module.
- CLK connects to CLK on the next module.
Wiring Diagram
If the LED matrix is made of a single block:
- Connect the input pins groups to Arduino
- Let the output pins group unconnected
This image is created using Fritzing. Click to enlarge image
This image is created using Fritzing. Click to enlarge image
If the LED matrix is pre-built multiple blocks:
- Connect the input pins groups to Arduino
- Let the output pins group unconnected
This image is created using Fritzing. Click to enlarge image
If the LED matrix is made of multiple blocks by yourself:
- Connect the input pins groups of the first block to Arduino
- Connect the output pins groups of each block to the input pins groups of the next block
- Let the output pins group of the last block unconnected
This image is created using Fritzing. Click to enlarge image
This image is created using Fritzing. Click to enlarge image
Because the display draws a lot of currents (up to 1A at maximum brightness):
- Do not use the power from the 5V pin of Arduino.
- Use an external 5V power supply instead. Arduino and LED matrix can share power from a 5V power adapter
Because Arduino connects to LED matrix via SPI pins:
- Pin 13 (SCK) and 11 (MOSI) on Arduino Uno must be used. If you’re using another Arduino board, check the official documentation for equivalent SPI pins.
- Pin 3 (CS) can be changed to any pin
How To Program For LED Matrix
It is not easy to control the LED matrix. Fortunately, libraries are available to make it easy. Below is a step-by-step on how to write Arduino code to control the LED matrix
- Include libraries:
#include <MD_Parola.h>
#include <MD_MAX72xx.h>
- Specify which hardware is being used: GENERIC_HW or FC16_HW.
#define HARDWARE_TYPE MD_MAX72XX::FC16_HW
- Define how many LED block is used. for example, a 4-in-1 LED matrix has 4 blocks.
#define MAX_DEVICES 4
- Define the pin that connects to the LED matrix’s CS pin. For example, pin D3
#define CS_PIN 3
- Create a new instance of the MD_Parola class for the LED matrix display.
MD_Parola ledMatrix = MD_Parola(HARDWARE_TYPE, CS_PIN, MAX_DEVICES);
- Code in the setup() function:
void setup() {
ledMatrix.begin(); // initialize the object
ledMatrix.setIntensity(0); // set the brightness of the LED matrix display (from 0 to 15)
ledMatrix.displayClear(); // clear led matrix display
}
- Display text, number and show animated effects: see next part
Arduino - LED Matrix Code
The below code is for 32x8 FC-16 LED matrix display (4 blocks). But you can easily adapt it for 8x8, 16x8, 64x8...
/*
* Created by ArduinoGetStarted.com
*
* This example code is in the public domain
*
* Tutorial page: https://arduinogetstarted.com/tutorials/arduino-led-matrix
*/
#include <MD_Parola.h>
#include <MD_MAX72xx.h>
#define HARDWARE_TYPE MD_MAX72XX::FC16_HW
#define MAX_DEVICES 4 // 4 blocks
#define CS_PIN 3
// create an instance of the MD_Parola class
MD_Parola ledMatrix = MD_Parola(HARDWARE_TYPE, CS_PIN, MAX_DEVICES);
void setup() {
ledMatrix.begin(); // initialize the object
ledMatrix.setIntensity(15); // set the brightness of the LED matrix display (from 0 to 15)
ledMatrix.displayClear(); // clear LED matrix display
}
void loop() {
ledMatrix.setTextAlignment(PA_LEFT);
ledMatrix.print("Left"); // display text
delay(2000);
ledMatrix.setTextAlignment(PA_CENTER);
ledMatrix.print("Center"); // display text
delay(2000);
ledMatrix.setTextAlignment(PA_RIGHT);
ledMatrix.print("Right"); // display text
delay(2000);
ledMatrix.setTextAlignment(PA_CENTER);
ledMatrix.setInvert(true);
ledMatrix.print("Invert"); // display text inverted
delay(2000);
ledMatrix.setInvert(false);
ledMatrix.print(1234); // display number
delay(2000);
}
Quick Steps
- Connect Arduino to LED matrix as above wiring diagram
- Connect Arduino to PC via USB cable
- Navigate to the Libraries icon on the left bar of the Arduino IDE.
- Search “MD_Parola”, then find the MD_Parola library
- Click Install button.
- You will be asked to install the MD_MAX72XX library for dependency. Click Install All button.
- Copy the above code and open it with Arduino IDE
- Click Upload button on Arduino IDE to upload code to Arduino
- See the LED matrix display
Arduino LED Matrix Code – Scrolling Text
When you want to print a long message that is too long to fit on a LED matrix display, you can use the scroll text effect technique.
The below Arduino code shows how to scroll a message on the LED matrix display.
/*
* Created by ArduinoGetStarted.com
*
* This example code is in the public domain
*
* Tutorial page: https://arduinogetstarted.com/tutorials/arduino-led-matrix
*/
#include <MD_Parola.h>
#include <MD_MAX72xx.h>
#define HARDWARE_TYPE MD_MAX72XX::FC16_HW
#define MAX_DEVICES 4 // 4 blocks
#define CS_PIN 3
// create an instance of the MD_Parola class
MD_Parola ledMatrix = MD_Parola(HARDWARE_TYPE, CS_PIN, MAX_DEVICES);
void setup() {
ledMatrix.begin(); // initialize the object
ledMatrix.setIntensity(15); // set the brightness of the LED matrix display (from 0 to 15)
ledMatrix.displayClear(); // clear led matrix display
ledMatrix.displayScroll("Hello, DIYables", PA_CENTER, PA_SCROLL_LEFT, 100);
}
void loop() {
if (ledMatrix.displayAnimate()) {
ledMatrix.displayReset();
}
}
For more text effects, please visit MD_Parola Library Reference.
Video Tutorial
We are considering to make the video tutorials. If you think the video tutorials are essential, please subscribe to our YouTube channel to give us motivation for making the videos.
The below video demo uses the below code:
/*
* Created by ArduinoGetStarted.com
*
* This example code is in the public domain
*
* Tutorial page: https://arduinogetstarted.com/tutorials/arduino-led-matrix
*/
#include <MD_MAX72xx.h>
#include <SPI.h>
// ============================================================
// MAX7219
// ============================================================
#define HARDWARE_TYPE MD_MAX72XX::FC16_HW
#define MAX_DEVICES 4
#define CS_PIN 9
MD_MAX72XX mx =
MD_MAX72XX(HARDWARE_TYPE, CS_PIN, MAX_DEVICES);
// ============================================================
// BUTTONS
// ============================================================
#define BTN_LEFT 2
#define BTN_RIGHT 3
#define BTN_ROTATE 4
#define BUZZER_PIN 6
// ============================================================
// GAME BOARD
// ============================================================
#define BOARD_W 8
#define BOARD_H 32
bool board[BOARD_H][BOARD_W];
// ============================================================
// TIMING
// ============================================================
unsigned long lastFallTime = 0;
const unsigned long NORMAL_FALL = 700;
const unsigned long SOFT_DROP_FALL = 80;
#define LONG_PRESS_TIME 400
// ============================================================
// SCORE
// ============================================================
unsigned long score = 0;
unsigned int lines = 0;
unsigned int level = 1;
unsigned long highScore = 0;
// ============================================================
// GAME STATE
// ============================================================
bool gameOver = false;
bool gameStarted = false;
// ============================================================
// TETROMINO DEFINITIONS
// ============================================================
struct Point {
int x;
int y;
};
struct Tetromino {
Point block[4];
uint8_t color;
};
Tetromino pieces[7] = {
// I
{
{{0,0}, {1,0}, {2,0}, {3,0}},
0
},
// O
{
{{0,0}, {1,0}, {0,1}, {1,1}},
1
},
// T
{
{{1,0}, {0,1}, {1,1}, {2,1}},
2
},
// L
{
{{0,0}, {0,1}, {0,2}, {1,2}},
3
},
// J
{
{{1,0}, {1,1}, {1,2}, {0,2}},
4
},
// S
{
{{1,0}, {2,0}, {0,1}, {1,1}},
5
},
// Z
{
{{0,0}, {1,0}, {1,1}, {2,1}},
6
}
};
// ============================================================
// CURRENT PIECE
// ============================================================
int currentPiece;
int currentX;
int currentY;
int rotationState = 0;
// ============================================================
// BUTTON STATE
// ============================================================
bool lastLeftState = HIGH;
bool lastRightState = HIGH;
bool lastRotateState = HIGH;
unsigned long rotatePressTime = 0;
bool softDrop = false;
bool rotateHandled = false;
// ============================================================
// DISPLAY COORDINATE MAPPING
// ============================================================
void setPixel(int x, int y, bool state) {
if (x < 0 || x >= BOARD_W ||
y < 0 || y >= BOARD_H) {
return;
}
// Reverse vertical direction
int physicalColumn = (BOARD_H - 1) - y;
int physicalRow = x;
mx.setPoint(
physicalRow,
physicalColumn,
state
);
}
// ============================================================
// CLEAR DISPLAY
// ============================================================
void clearDisplay() {
mx.clear();
}
// ============================================================
// DRAW BOARD
// ============================================================
void drawBoard() {
clearDisplay();
// Draw fixed blocks
for (int y = 0; y < BOARD_H; y++) {
for (int x = 0; x < BOARD_W; x++) {
if (board[y][x]) {
setPixel(
x,
y,
true
);
}
}
}
// Draw falling piece
drawCurrentPiece();
}
// ============================================================
// GET ROTATED BLOCK POSITION
// ============================================================
Point getRotatedPoint(
Point p,
int rotation
) {
Point r;
switch (rotation % 4) {
case 0:
r.x = p.x;
r.y = p.y;
break;
case 1:
r.x = -p.y;
r.y = p.x;
break;
case 2:
r.x = -p.x;
r.y = -p.y;
break;
case 3:
r.x = p.y;
r.y = -p.x;
break;
}
return r;
}
// ============================================================
// CHECK COLLISION
// ============================================================
bool checkCollision(
int pieceX,
int pieceY,
int rotation
) {
for (int i = 0; i < 4; i++) {
Point p = getRotatedPoint(
pieces[currentPiece].block[i],
rotation
);
int x = pieceX + p.x;
int y = pieceY + p.y;
// Left / Right wall
if (x < 0 || x >= BOARD_W) {
return true;
}
// Bottom
if (y >= BOARD_H) {
return true;
}
// Existing block
if (y >= 0 && board[y][x]) {
return true;
}
}
return false;
}
// ============================================================
// DRAW CURRENT PIECE
// ============================================================
void drawCurrentPiece() {
for (int i = 0; i < 4; i++) {
Point p = getRotatedPoint(
pieces[currentPiece].block[i],
rotationState
);
int x = currentX + p.x;
int y = currentY + p.y;
if (x >= 0 && x < BOARD_W &&
y >= 0 && y < BOARD_H) {
setPixel(
x,
y,
true
);
}
}
}
// ============================================================
// RANDOM PIECE
// ============================================================
void spawnPiece() {
currentPiece = random(0, 7);
rotationState = 0;
currentX = 3;
currentY = 0;
// I piece
if (currentPiece == 0) {
currentX = 2;
}
// Game over if piece cannot spawn
if (checkCollision(
currentX,
currentY,
rotationState)) {
gameOver = true;
if (score > highScore) {
highScore = score;
}
soundGameOver();
}
}
// ============================================================
// LOCK PIECE
// ============================================================
void lockPiece() {
for (int i = 0; i < 4; i++) {
Point p = getRotatedPoint(
pieces[currentPiece].block[i],
rotationState
);
int x = currentX + p.x;
int y = currentY + p.y;
if (x >= 0 && x < BOARD_W &&
y >= 0 && y < BOARD_H) {
board[y][x] = true;
}
}
soundLock();
// Check completed lines
clearLines();
// New piece
spawnPiece();
lastFallTime = millis();
}
// ============================================================
// CLEAR LINES
// ============================================================
void clearLines() {
int cleared = 0;
for (int y = BOARD_H - 1; y >= 0; y--) {
bool full = true;
for (int x = 0; x < BOARD_W; x++) {
if (!board[y][x]) {
full = false;
break;
}
}
if (full) {
cleared++;
// Move rows down
for (int yy = y; yy > 0; yy--) {
for (int x = 0; x < BOARD_W; x++) {
board[yy][x] =
board[yy - 1][x];
}
}
// Clear top row
for (int x = 0; x < BOARD_W; x++) {
board[0][x] = false;
}
// Check same row again
y++;
}
}
// Scoring
if (cleared > 0) {
lines += cleared;
switch (cleared) {
case 1:
score += 100 * level;
break;
case 2:
score += 300 * level;
break;
case 3:
score += 500 * level;
break;
case 4:
score += 800 * level;
break;
}
// Increase level every 10 lines
level =
(lines / 10) + 1;
soundLineClear(cleared);
}
}
// ============================================================
// MOVE LEFT
// ============================================================
void moveLeft() {
if (gameOver) {
return;
}
if (!checkCollision(
currentX - 1,
currentY,
rotationState)) {
currentX--;
drawBoard();
soundLeft();
}
}
// ============================================================
// MOVE RIGHT
// ============================================================
void moveRight() {
if (gameOver) {
return;
}
if (!checkCollision(
currentX + 1,
currentY,
rotationState)) {
currentX++;
drawBoard();
soundRight();
}
}
// ============================================================
// ROTATE
// ============================================================
void rotatePiece() {
if (gameOver) {
return;
}
int newRotation =
(rotationState + 1) % 4;
// Normal rotation
if (!checkCollision(
currentX,
currentY,
newRotation)) {
rotationState =
newRotation;
drawBoard();
return;
}
// Wall kick LEFT
if (!checkCollision(
currentX - 1,
currentY,
newRotation)) {
currentX--;
rotationState =
newRotation;
drawBoard();
return;
}
// Wall kick RIGHT
if (!checkCollision(
currentX + 1,
currentY,
newRotation)) {
currentX++;
rotationState =
newRotation;
drawBoard();
return;
}
}
// ============================================================
// MOVE DOWN
// ============================================================
bool moveDown() {
if (gameOver) {
return false;
}
if (!checkCollision(
currentX,
currentY + 1,
rotationState)) {
currentY++;
return true;
}
// Cannot move further
lockPiece();
return false;
}
// ============================================================
// SOFT DROP
// ============================================================
void handleSoftDrop() {
if (gameOver) {
return;
}
static unsigned long lastSoftDrop = 0;
if (millis() - lastSoftDrop >=
SOFT_DROP_FALL) {
lastSoftDrop = millis();
if (moveDown()) {
score += 1;
}
drawBoard();
}
}
// ============================================================
// NORMAL FALL
// ============================================================
void handleNormalFall() {
if (gameOver) {
return;
}
unsigned long fallSpeed;
fallSpeed =
NORMAL_FALL -
((level - 1) * 50);
if (fallSpeed < 100) {
fallSpeed = 100;
}
if (millis() - lastFallTime >=
fallSpeed) {
lastFallTime = millis();
moveDown();
drawBoard();
}
}
// ============================================================
// BUTTON HANDLING
// ============================================================
void handleButtons() {
bool leftState =
digitalRead(BTN_LEFT);
bool rightState =
digitalRead(BTN_RIGHT);
bool rotateState =
digitalRead(BTN_ROTATE);
// ==========================================================
// LEFT
// ==========================================================
if (leftState == LOW &&
lastLeftState == HIGH) {
moveLeft();
}
// ==========================================================
// RIGHT
// ==========================================================
if (rightState == LOW &&
lastRightState == HIGH) {
moveRight();
}
// ==========================================================
// ROTATE BUTTON PRESSED
// ==========================================================
if (rotateState == LOW &&
lastRotateState == HIGH) {
rotatePressTime = millis();
rotateHandled = false;
}
// ==========================================================
// ROTATE BUTTON HELD
// ==========================================================
if (rotateState == LOW) {
if (!rotateHandled &&
millis() - rotatePressTime >=
LONG_PRESS_TIME) {
rotateHandled = true;
softDrop = true;
}
}
// ==========================================================
// ROTATE BUTTON RELEASED
// ==========================================================
if (rotateState == HIGH &&
lastRotateState == LOW) {
unsigned long pressDuration =
millis() - rotatePressTime;
// Short press = ROTATE
if (pressDuration <
LONG_PRESS_TIME &&
!rotateHandled) {
rotatePiece();
soundRotate();
}
// Stop soft drop
softDrop = false;
}
lastLeftState =
leftState;
lastRightState =
rightState;
lastRotateState =
rotateState;
}
// ============================================================
// START MUSIC
// ============================================================
//
// Arcade-style startup melody.
//
// Không dùng tone liên tục.
// Mỗi nốt kết thúc trước khi nốt tiếp theo bắt đầu.
// ============================================================
void playStartMusic() {
clearDisplay();
// ----------------------------------------------------------
// Intro LED sweep
// ----------------------------------------------------------
for (int y = 0; y < BOARD_H; y++) {
for (int x = 0; x < BOARD_W; x++) {
setPixel(
x,
y,
true
);
}
// Melody notes during sweep
if (y == 0) {
tone(BUZZER_PIN, 523, 100);
}
if (y == 4) {
tone(BUZZER_PIN, 659, 100);
}
if (y == 8) {
tone(BUZZER_PIN, 784, 100);
}
if (y == 12) {
tone(BUZZER_PIN, 1047, 150);
}
if (y == 18) {
tone(BUZZER_PIN, 784, 100);
}
if (y == 22) {
tone(BUZZER_PIN, 1047, 100);
}
if (y == 26) {
tone(BUZZER_PIN, 1319, 180);
}
delay(18);
}
delay(100);
clearDisplay();
// ----------------------------------------------------------
// READY melody
// ----------------------------------------------------------
tone(BUZZER_PIN, 784, 120);
delay(150);
tone(BUZZER_PIN, 988, 120);
delay(150);
tone(BUZZER_PIN, 1175, 120);
delay(150);
tone(BUZZER_PIN, 1568, 250);
delay(300);
clearDisplay();
noTone(BUZZER_PIN);
}
// ============================================================
// LEFT SOUND
// ============================================================
void soundLeft() {
tone(
BUZZER_PIN,
650,
70
);
}
// ============================================================
// RIGHT SOUND
// ============================================================
void soundRight() {
tone(
BUZZER_PIN,
850,
70
);
}
// ============================================================
// ROTATE SOUND
// ============================================================
void soundLock() {
tone(BUZZER_PIN, 450, 120);
delay(130);
tone(BUZZER_PIN, 300, 100);
}
// ============================================================
// ROTATE SOUND
// ============================================================
void soundRotate() {
tone(
BUZZER_PIN,
1200,
100
);
}
// ============================================================
// LINE CLEAR SOUND
// ============================================================
void soundLineClear(int count) {
if (count == 1) {
tone(
BUZZER_PIN,
1000,
120
);
delay(150);
tone(
BUZZER_PIN,
1400,
160
);
}
else if (count == 2) {
tone(
BUZZER_PIN,
1000,
100
);
delay(120);
tone(
BUZZER_PIN,
1300,
100
);
delay(120);
tone(
BUZZER_PIN,
1700,
180
);
}
else {
tone(
BUZZER_PIN,
1200,
100
);
delay(120);
tone(
BUZZER_PIN,
1500,
100
);
delay(120);
tone(
BUZZER_PIN,
1800,
100
);
delay(120);
tone(
BUZZER_PIN,
2200,
250
);
}
}
// ============================================================
// GAME OVER SOUND
// ============================================================
void soundGameOver() {
tone(
BUZZER_PIN,
700,
180
);
delay(210);
tone(
BUZZER_PIN,
500,
180
);
delay(210);
tone(
BUZZER_PIN,
350,
220
);
delay(250);
tone(
BUZZER_PIN,
220,
450
);
delay(500);
noTone(BUZZER_PIN);
}
// ============================================================
// GAME OVER ANIMATION
// ============================================================
void gameOverAnimation() {
for (int i = 0; i < 4; i++) {
drawBoard();
delay(250);
clearDisplay();
delay(250);
}
}
// ============================================================
// RESET GAME
// ============================================================
void resetGame() {
for (int y = 0; y < BOARD_H; y++) {
for (int x = 0; x < BOARD_W; x++) {
board[y][x] = false;
}
}
score = 0;
lines = 0;
level = 1;
gameOver = false;
spawnPiece();
lastFallTime =
millis();
drawBoard();
}
// ============================================================
// SETUP
// ============================================================
void setup() {
Serial.begin(115200);
// Buttons
pinMode(
BTN_LEFT,
INPUT_PULLUP
);
pinMode(
BTN_RIGHT,
INPUT_PULLUP
);
pinMode(
BTN_ROTATE,
INPUT_PULLUP
);
// Buzzer
pinMode(
BUZZER_PIN,
OUTPUT
);
// MAX7219
mx.begin();
mx.control(
MD_MAX72XX::INTENSITY,
5
);
mx.control(
MD_MAX72XX::UPDATE,
true
);
mx.clear();
// Random seed
randomSeed(
analogRead(A0)
);
// ==========================================================
// START MUSIC
// ==========================================================
playStartMusic();
// ==========================================================
// START GAME
// ==========================================================
resetGame();
gameStarted = true;
}
// ============================================================
// MAIN LOOP
// ============================================================
void loop() {
if (!gameStarted) {
return;
}
// ==========================================================
// GAME OVER
// ==========================================================
if (gameOver) {
gameOverAnimation();
delay(500);
// Restart
resetGame();
return;
}
// ==========================================================
// INPUT
// ==========================================================
handleButtons();
// ==========================================================
// SOFT DROP
// ==========================================================
if (softDrop) {
handleSoftDrop();
}
else {
handleNormalFall();
}
}