ESP32 - LED Matrix via Web

#esp32 #electronics #iot #tutorial

This build turns an ESP32 into a web-controlled signboard. You type text into a web page, it travels over WebSocket to the ESP32, and the ESP32 scrolls it across an FC-16 LED matrix. It's a neat way to see how a browser, a web server running on a microcontroller, and a physical display can talk to each other in real time.

The full tutorial, with every detail and the line-by-line code explanation, is on our site: ESP32 - LED Matrix via Web

What you need

Wiring

The FC-16 LED matrix connects to the ESP32 over a few data lines, with its CS (chip select) pin going to GPIO21 as set by CS_PIN in the sketch. If you're not sure how to power the ESP32 and the matrix together, it's worth checking a dedicated guide on powering ESP32 and displays before wiring things up, since a matrix made of multiple LED blocks can draw more current than the ESP32's own pins can supply.

How it works

The ESP32 runs two things at once: a web server that serves a page to your browser, and a WebSocket server that keeps a live connection open. When you type text on the page and send it, the message travels over the WebSocket to the ESP32 instead of as a regular HTTP request, which keeps things fast and responsive. On the ESP32 side, the MD_Parola library takes that text and scrolls it across the LED matrix, while the ESP32 sends a short confirmation message back to the browser over the same WebSocket connection.

Code

The sketch is split into two files: an .ino file with the ESP32 logic, and an index.h file holding the webpage's HTML, CSS and JavaScript. The .ino file sets up the web server and WebSocket server using the DIYables_ESP32_WebServer library, initializes the LED matrix with MD_Parola, and defines handlers for when a WebSocket connection opens, receives a message, or closes. The message handler clears the display and scrolls the incoming text with displayScroll(), then broadcasts a reply to connected clients.

esp32-led-matrix-via-web.ino

/*
 * This ESP32 code is created by esp32io.com
 *
 * This ESP32 code is released in the public domain
 *
 * For more detail (instruction and wiring diagram), visit https://esp32io.com/tutorials/esp32-led-matrix-via-web
 */

#include <DIYables_ESP32_WebServer.h>
#include "index.h"

#include <MD_Parola.h>
#include <MD_MAX72xx.h>

#define HARDWARE_TYPE MD_MAX72XX::FC16_HW
#define MAX_DEVICES 4  // 4 blocks
#define CS_PIN 21      // ESP32 pin GPIO21

// WiFi credentials
const char WIFI_SSID[] = "YOUR_WIFI_SSID";
const char WIFI_PASSWORD[] = "YOUR_WIFI_PASSWORD";

// Create web server instance
DIYables_ESP32_WebServer server;
DIYables_ESP32_WebSocket* webSocket;

// create an instance of the MD_Parola class
MD_Parola ledMatrix = MD_Parola(HARDWARE_TYPE, CS_PIN, MAX_DEVICES);


// Web Page handlers
void handleHome(WiFiClient& client, const String& method, const String& request, const QueryParams& params, const String& jsonData) {
  server.sendResponse(client, HTML_CONTENT);
}

// WebSocket event handlers
void onWebSocketOpen(net::WebSocket& ws) {
  Serial.println("New WebSocket connection");
  // Send welcome message
  const char welcome[] = "Connected to ESP32 WebSocket Server!";
}

void onWebSocketMessage(net::WebSocket& ws, const net::WebSocket::DataType dataType, const char* message, uint16_t length) {

  Serial.print("WebSocket Received (");
  Serial.print(length);
  Serial.print(" bytes): ");
  Serial.println(message);

  ledMatrix.displayClear();  // clear led matrix display
  ledMatrix.displayScroll(message, PA_CENTER, PA_SCROLL_LEFT, 100);

  // Broadcast response to all connected clients using the library
  if (webSocket != nullptr) {
    String response = "Displayed: " + String(message) + "on LED Matrix";
    webSocket->broadcastTXT(response);

    Serial.print("WebSocket sent (");
    Serial.print(response.length());
    Serial.print(" bytes): ");
    Serial.println(response);
  }
}

void onWebSocketClose(net::WebSocket& ws, const net::WebSocket::CloseCode code, const char* reason, uint16_t length) {
  Serial.println("WebSocket client disconnected");
}

void setup() {
  Serial.begin(9600);
  delay(1000);

  Serial.println("ESP32 Web Server and WebSocket Server");

  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("esp32io.com", PA_CENTER, PA_SCROLL_LEFT, 100);


  // Configure web server routes
  server.addRoute("/", handleHome);

  // Start web server with WiFi connection
  server.begin(WIFI_SSID, WIFI_PASSWORD);

  // Enable WebSocket functionality
  webSocket = server.enableWebSocket(81);

  if (webSocket != nullptr) {
    // Set up WebSocket event handlers
    webSocket->onOpen(onWebSocketOpen);
    webSocket->onMessage(onWebSocketMessage);
    webSocket->onClose(onWebSocketClose);
  } else {
    Serial.println("Failed to start WebSocket server");
  }
}

void loop() {
  // Then handle HTTP requests
  server.handleClient();

  // Handle WebSocket
  server.handleWebSocket();

  if (ledMatrix.displayAnimate()) {
    ledMatrix.displayReset();
  }
}

Things that go wrong

Before uploading, replace the placeholder WIFI_SSID and WIFI_PASSWORD values with your actual network credentials, otherwise the ESP32 never gets online. Make sure you've installed both the DIYables ESP32 WebServer library and MD_Parola through the Arduino IDE Library Manager, and that you've selected the correct ESP32 board and COM port, since a mismatched board selection is a common reason uploads fail silently.

Full tutorial

The complete tutorial - wiring diagram, code explanation and troubleshooting - is here: https://esp32io.com/tutorials/esp32-led-matrix-via-web

DEV Community