•

EMQ Technologies

Published November 18, 2023

ESP32 LED Marquee using MQTT

Learn how to build a scrolling text display using MQTT, neopixels, and an ESP32

BeginnerFull instructions provided1 hour615

Things used in this project

Hardware components

Espressif ESP32

RGB LED Pixel Matrix, NeoPixel NeoMatrix

Jumper wires (generic)

Software apps and online services

EMQX

MQTTX

Hand tools and fabrication machines

Soldering iron (generic)

Story

In this guide I'll walk you through creating an internet controlled LED matrix that lets you display scrolling text. The device uses any off the shelf ESP32 wifi enabled programmable IoT development board and addressable LEDS often referred to as Neopixels. It connects using MQTT, so you can integrate any custom app as well as many existing IoT platforms.

If you’re unfamiliar, MQTT stands for Message Queuing Telemetry Transport. It’s a robust messaging protocol with a publish and subscriber model - using topics to define where messages are coming from or going to.

EMQX is the most feature rich, secure, and reliable MQTT broker available as both an open-source project and as a managed cloud service. This guide will be using EMQX.

Install EMQX

You have a number of options for deploying EMQX. You can install it locally or use our cloud platform to deploy a dedicated deployment. We also provide a serverless deployment, which does require modifying the code to use a certificate file.

For a local deployment using the EMQX Community edition, follow this Hackster guide.

https://www.hackster.io/virgilvox/mqtt-basics-with-the-emqx-community-edition-58f18f

Wiring

1 / 2

There are a couple of different ways to wire an LED matrix that uses Neopixel compatible addressable LEDs. You can create one by wiring together individual LED strips in a zigzag pattern or you can use a premade LED Matrix panel.

1 / 2

There are three pins on the ESP32 that need to be connected.

Din > Pin 2
5V > 5V
GND > GND

Setting up the Arduino IDE and Libraries

Install the latest Arduino IDE.
Install the ArduinoMqttClient, Adafruit Neopixel,Adafruit Neomatrix, and Adafruit GFX libraries. You can do so easily from the Library Manger.

Install the ESP32 boards following this guide https://randomnerdtutorials.com/installing-esp32-arduino-ide-2-0/

Program the Arduino Sketch

The Arduino sketch creates a basic program that connects to your WiFi network, connects to the broker as the user created on your EMQX broker, subscribes to messages on a topic led/matrix and when a message is received it will display it as scrolling text on the LED Matrix.

Create a blank sketch in the Arduino IDE and copythe sketch included at the bottom of this guide.
At the top of the sketch configure your WiFi credentials, the user credentials from your EMQX broker, and the IP addressor Hostname.

Plug the ESP32 to your computer.
In Tools > Board select the type of ESP32 development board that you are using.
In Tools > Port select the corresponding port for your ESP32.
Click the Upload arrow.
Once uploaded open the Serial Monitor from the Tools menu in order to monitor the device logs and view messages received.

Change the text using MQTT

The Arduino code subscribes to the MQTT topic led/matrix on the EMQX broker. When a message {"message": "your text here"} is published to that topic, the text in the value of the message key is displayed on the LED matrix.

You can test this using MQTTX, a free test client provided by EMQX.

What next?!

Now that you know how to program an ESP32 to control an LED matrix and connect to an EMQX MQTT broker, you can easily build more applications around this. You could create an app that runs in the cloud or somewhere else that can send text to the LED matrix. For example, a news crawler that pulls the latest news from an API and displays it. You could make a notification panel or a leaderboard. You can even use it to make internet controlled holiday lights if you ditch the matrix for just LED strips. The framework is there, all you need is your creativity!

Join Our Community!

We have an amazing community of open-source contributors and users of the EMQX project and cloud service. Join in on the discussions, share your projects, or feel free to ask any questions! We'd love to hear from you!

mqtt_marquee.ino

#include <Adafruit_GFX.h>
#include <Adafruit_NeoMatrix.h>
#include <Adafruit_NeoPixel.h>
#include <WiFi.h>
#include <ArduinoMqttClient.h>
#include <ArduinoJson.h>

char ssid[] = "";    // your network SSID (name)
char pass[] = "";    // your network password 

char mqtt_user[] = "test";
char mqtt_pass[] = "test";

WiFiClient wifiClient;
MqttClient mqttClient(wifiClient);

const char broker[] = "";
int        port     = 1883;
const char subscribe_topic[]  = "led/matrix";

#define LED_BLACK		0
#define LED_RED_HIGH 		(31 << 11) 
#define LED_GREEN_HIGH 		(63 << 5)  
#define LED_BLUE_HIGH 		31

#define PIN 2
// Max is 255, 32 is a conservative value to not overload
// a USB power supply (500mA) for 12x12 pixels.
#define BRIGHTNESS 32

// Define matrix width and height.
#define mw 32
#define mh 8
Adafruit_NeoMatrix *matrix = new Adafruit_NeoMatrix(mw, mh, 
  PIN,
  NEO_MATRIX_TOP     + NEO_MATRIX_LEFT +
    NEO_MATRIX_ROWS + NEO_MATRIX_ZIGZAG,
  NEO_GRB            + NEO_KHZ800 );

const uint16_t colors[] = {

 LED_RED_HIGH, LED_GREEN_HIGH, LED_BLUE_HIGH 

};


void setup() {
  matrix->begin();
  matrix->setTextWrap(false);
  matrix->setBrightness(40);
  matrix->setTextColor(colors[0]);
  // Create serial connection and wait for it to become available.
  Serial.begin(9600);
  while (!Serial) {
    ; 
  }

  // Connect to WiFi
  Serial.print("Attempting to connect to WPA SSID: ");
  Serial.println(ssid);
  int tryDelay = 500;
    int numberOfTries = 20;
  WiFi.begin(ssid, pass);
  while (WiFi.status() != WL_CONNECTED) {
    // failed, retry
    Serial.print(".");
    delay(5000);
  }

  Serial.println("You're connected to the network");
  Serial.println();

  // You can provide a username and password for authentication
  mqttClient.setUsernamePassword(mqtt_user, mqtt_pass);

  Serial.print("Attempting to connect to the MQTT broker.");

  if (!mqttClient.connect(broker, port)) {
    Serial.print("MQTT connection failed! Error code = ");
    Serial.println(mqttClient.connectError());

    while (1);
  }

  Serial.println("You're connected to the MQTT broker!");

  mqttClient.onMessage(onMqttMessage);

  Serial.print("Subscribing to topic: ");
  Serial.println(subscribe_topic);

  // subscribe to a topic
  mqttClient.subscribe(subscribe_topic);

  Serial.print("Waiting for messages on topic: ");
  Serial.println(subscribe_topic);
}

int x    = matrix->width();

int passes = 0;

String text = "";

void onMqttMessage(int messageSize) {
  Serial.print("Received a message with topic '");
  Serial.println(mqttClient.messageTopic());
  StaticJsonDocument<256> doc;
  deserializeJson(doc, mqttClient);
  const char* message = doc["message"];
  Serial.print("Message: '");
  Serial.println(message);
  text = message;
}

void loop() {

  mqttClient.poll();

  int totalShifts = (text.length() *6);   // Total shifts needed

  matrix->fillScreen(0);
  matrix->setCursor(x, 0);
  matrix->print(text);

  if(--x < -totalShifts) {  
    x = matrix->width();
    if(++passes >= 3) passes = 0;
    matrix->setTextColor(colors[passes]);

  }
   matrix->show();
   delay(50);
}

Credits

Moheeb Zara

39 projects • 137 followers

Developer Advocate at EMQ Technologies - . Co-founder - South West Maker Festival. Hardware hacker, artist, robots, HeatSync Labs

EMQ Technologies

5 projects • 6 followers

World's leading cloud-native MQTT-based IoT messaging platform and streaming database

ESP32 LED Marquee using MQTT