ESP32-S3 RGB LED矩阵项目2

本教程是的一部分: ESP32-S3 RGB LED 点阵

这是一个很棒的项目，可以使用 ESP32-S3 RGB 矩阵模块进行创作，兼具趣味性和实用性。本文下方有其他相关视频的链接。

ESP32-S3 RGB LED矩阵项目2 - 滚动文字

项目2 - 在ESP32-S3 RGB LED矩阵上的文本滚动

在这个项目中，我们将ESP32-S3 RGB LED矩阵变成一个小型的文本横幅。一条简短的信息（例如Robojax在8×8 RGB显示屏上滚动，您可以直接在代码中轻松更改文本、颜色、亮度和滚动速度。这对于简单的通知、姓名标签或小状态消息非常有用。

本系列中的所有六个项目都在一个YouTube视频中进行了展示和解释。该视频嵌入在此页面上，因此您可以实时看到文本滚动的效果，以及每个设置如何影响动画。该项目的完整代码会自动加载在文章下方，您可以从代码部分列出的附属商店购买ESP32-S3 RGB LED矩阵模块。

此项目基于项目 1 的基础（移动点和颜色控制），并使用 NeoMatrix 库添加文本渲染和滚动功能。

ESP32-S3 RGB LED矩阵模块概述

硬件在所有六个项目中都是相同的：一个带有Wi-Fi和蓝牙的ESP32-S3微控制器，一个8×8 RGB LED矩阵（64个可寻址的RGB LED），一个QMI8658C加速度计，USB端口，以及可访问的IO引脚。:contentReference[oaicite:0]{index=0}

ESP32-S3- 主 CPU 带 Wi-Fi/BLE 适用于高级项目。
8×8 RGB 矩阵- 64个RGB LED用于图标、文本和动画。
QMI8658C 加速度计- 在后来的项目中用于倾斜和方向。
USB接口- 用于通过 Arduino IDE 进行电源和编程。
裸露引脚让你像正常的ESP32一样使用板子进行其他输入输出。
启动 / 重置按钮- 用于固件上传和重启草图。

在项目2中，我们主要关注矩阵和NeoMatrix文本函数。加速度计尚未使用，但同一块电路板将处理后续的所有交互和游戏项目。

视频中涵盖的项目（时间戳）

与本文相关的视频涵盖了所有六个项目。大致的时间戳是：

00:00- 介绍
02:01- 安装ESP32开发板
03:32- 安装库
05:32- 项目 1：移动点
11:11- 项目2：文本滚动
12:59- 项目 3：HTTP 文本
16:41- 项目 4：倾斜点
18:55- 项目 5：向上箭头
20:02项目6：目标游戏

建议您在阅读本文时观看视频。视频展示了LED矩阵上实时滚动的文字，并逐步演示了Arduino IDE中的所有步骤。

在Arduino IDE中安装ESP32开发板

在运行文本滚动代码之前，请确保您的Arduino IDE中已安装ESP32支持：

打开File > Preferences并将ESP32板的URL添加到“附加开发板管理器URLs”。
去Tools > Board > Boards Manager…, 搜索ESP32，安装官方的 ESP32 包。
从中选择您的 ESP32-S3 RGB 矩阵板Tools > Board.
通过USB连接模块，并在下方选择正确的COM/串口。Tools > Port.

如果电路板类型或端口不正确，草图将无法上传。

安装NeoMatrix和所需库

文本滚动是使用Adafruit NeoMatrix及其依赖项实现的。在视频中，它们通过库管理器安装。

您需要：

Adafruit NeoMatrix
Adafruit NeoPixel
Adafruit GFX Library

打开Sketch > Include Library > Manage Libraries….
搜索Adafruit NeoMatrix并点击安装.
当被提示时，允许它安装Adafruit GFX和Adafruit NeoPixel作为依赖项。

如果安装成功，您应该在下方看到示例草图。File > Examples > Adafruit NeoMatrix和File > Examples > Adafruit NeoPixel.

项目2 - 代码设置（文本滚动）

本文下方的网站会自动加载完整的文本滚动示意图。这里我们仅关注您可能想要编辑的配置值：引脚、矩阵大小、亮度、文本字符串、颜色、滚动速度和可选方向。

下面的所有代码片段都来自草图顶部的配置部分，因此您可以快速调整行为，而无需修改主要逻辑。

矩阵销和尺寸

与项目 1 一样，RGB 矩阵连接到 GPIO 14，并包含 64 个 LED（8×8）。请确保这两行与您的模块匹配：


 // Pin connected to 8×8 RGB matrix 
const int MATRIX_PIN = 14; // must be 14 on this module // Matrix size (width and height)
 const int MATRIX_WIDTH = 8; 
const int MATRIX_HEIGHT = 8;

如果您从NeoMatrix库复制示例，它可能会使用不同的引脚或大小；请始终将它们更改为与此板匹配。

文本的亮度

亮度通常通过0到255之间的值来控制，其中0表示关闭，255表示最大亮度。通常适中的值就足够了：


// Overall matrix brightness (0–255) 
uint8_t matrixBrightness = 40; // comfortable indoor brightness // In 
setup(): 
matrix.setBrightness(matrixBrightness);

如果您在明亮的环境中或短时间使用面板，可以提高这个值，但如果您靠近显示屏，请避免设置得过高。

滚动文本

实际消息作为字符串存储。在视频中，示例文本是Robojax您可以将其更改为您喜欢的任何简短标签或消息：


 // Text to scroll on the 8×8 matrix const char scrollText[] = "Robojax";
 // change this to your message

请记住，这只是一个8×8的矩阵，因此非常长的信息滚动会需要更长的时间，并且可能变得难以阅读。

文本颜色（RGB 值）

滚动文本的颜色由红色、绿色和蓝色分量（0-255）设置。例如，纯红色是(255, 0, 0)纯绿色是(0, 255, 0)，纯蓝是(0, 0, 255)在草图中你会看到类似的东西：


 // Text color (R, G, B) uint8_t textRed = 255; // red component uint8_t textGreen = 0; // green component uint8_t textBlue = 0; // blue component

更改颜色：

黄色：textRed = 255; textGreen = 255; textBlue = 0;
青色textRed = 0; textGreen = 255; textBlue = 255;
白色：textRed = 255; textGreen = 255; textBlue = 255;

该视频还演示了如何使用在线颜色选择器查找RGB值，然后将其输入代码中。:contentReference[oaicite:1]{index=1}

滚动速度（帧之间的延迟）

滚动速度由每次更新步骤之间的毫秒延迟值控制。较小的值使文本移动得更快；较大的值则减慢速度。在草图中，您应该找到一个类似的变量：


// Delay between scroll steps (in milliseconds) int scrollDelayMs = 50; 
// smaller = faster, larger = slower

示例：

scrollDelayMs = 20;快速滚动。
scrollDelayMs = 50;→ 中速（与视频类似）。
scrollDelayMs = 100;或更多 → 缓慢、易于阅读的滚动。

内部的loop()，这个值用于一个delay(scrollDelayMs);在每次重新绘制文本位置后调用。

滚动方向（可选）

在“基本文本滚动”项目中，我们通常向左滚动，但定义一个符号方向变量是有用的，这样你可以稍后尝试其他方向（左、右、上、下）。

一种常见的模式是：


 // Scroll direction selector // 0 = left, 1 = right, 2 = up, 3 = down 
int scrollDirection = 0; // default: scroll to the left

主循环接着检查scrollDirection并将文本移动到所选方向。在项目 2 中，您可以将其保留在0（左边），但如果您稍后扩展草图，可以添加以下条件：


 if (scrollDirection == 0) { 
// move text left 
} else if (scrollDirection == 1) { 
// move text right 
} else if (scrollDirection == 2) { 
// move text up
 } else if (scrollDirection == 3) { 
// move text down 
}

对于这篇文章，我们只记录了设置。完整的实现是文章下方加载的代码的一部分。

摘要

项目 2 将您的 ESP32-S3 RGB LED 矩阵变成一个简单但引人注目的文本显示器。通过编辑代码顶部的几个变量，您可以快速更改：

哪个消息被显示scrollText).
文本的颜色textRed,textGreen,textBlue).
矩阵的亮度（matrixBrightness).
滚动速度（scrollDelayMs).
滚动的方向scrollDirection如果您选择使用它)。

本项目的完整草图可在本文下方查看（由网站自动加载）。有关详细的逐步配置和滚动文本实际演示，请务必观看视频的相应部分。如果您喜欢这个项目并想自己动手制作，您还可以从代码下方列出的附属链接购买ESP32-S3 RGB LED矩阵模块。

图像

ESP32 S3 Matrix

ESP32 S3 Matrix pin out

ESP32-S3_RGB_8x8_matrix1

ESP32-S3_RGB_8x8_matrix-2

ESP32-S3-Mtrix - Alway Up

本教程是……的一部分: ESP32-S3 RGB LED 点阵

如果代码不可见，请查看该页面的英文版。对此造成的不便我们深表歉意。

800-ESP32-S3 RGB LED Matrix Project 2 - Scrolling Text

语言: C++

/* 
  Project 2: Text scroll – ESP32-S3 RGB LED Matrix (Waveshare)

  This sketch displays the scrolling text on 8x8 matrix

  ▶️ Video Tutorial:
  https://youtu.be/JKLuYrRcLMI

  📚⬇️ Resources & Code Page:
  https://robojax.com/RJT829

  QMI8658_RGB_2
*/
#include <Arduino.h>
#include <Adafruit_GFX.h>
#include <Adafruit_NeoMatrix.h>
#include <Adafruit_NeoPixel.h>

// -------- LED MATRIX SETUP --------
#define MATRIX_PIN    14
#define MATRIX_WIDTH  8
#define MATRIX_HEIGHT 8

Adafruit_NeoMatrix matrix = Adafruit_NeoMatrix(
  MATRIX_WIDTH, MATRIX_HEIGHT, MATRIX_PIN,
  NEO_MATRIX_TOP + NEO_MATRIX_LEFT +
  NEO_MATRIX_ROWS + NEO_MATRIX_PROGRESSIVE,
  NEO_RGB + NEO_KHZ800
);

// =========================
// USER SETTINGS
// =========================

// Text to scroll
const char* MESSAGE = "ROBOJAX ";

// Brightness (0–255)
uint8_t BRIGHTNESS = 10;

// Scroll speed (milliseconds between steps)
// Smaller = faster
uint16_t SCROLL_DELAY = 80;

// Scroll direction
enum ScrollDir {
  SCROLL_LEFT,
  SCROLL_RIGHT,
  SCROLL_UP,
  SCROLL_DOWN
};

// Change this to set direction
ScrollDir DIRECTION = SCROLL_LEFT;

// Text color (set RGB here)
uint8_t COLOR_R = 255; 
uint8_t COLOR_G = 0;
uint8_t COLOR_B = 0;

// =========================
// INTERNAL STATE
// =========================
uint16_t textColor;
int16_t posX, posY;
int16_t textWidth, textHeight;
uint32_t lastStepTime = 0;

// Compute text size in pixels for default 5x7 font
void computeTextSize() {
  int16_t x1, y1;
  uint16_t w, h;
  matrix.getTextBounds((char*)MESSAGE, 0, 0, &x1, &y1, &w, &h);
  textWidth  = (int16_t)w;
  textHeight = (int16_t)h;
}

// Initialize starting position based on direction
void resetScrollPosition() {
  switch (DIRECTION) {
    case SCROLL_LEFT:
      // Start just off the right edge
      posX = matrix.width();
      posY = 0; // top row for 8x8
      break;

    case SCROLL_RIGHT:
      // Start just off the left edge
      posX = -textWidth;
      posY = 0;
      break;

    case SCROLL_UP:
      posX = 0;
      posY = matrix.height(); // start below bottom
      break;

    case SCROLL_DOWN:
      posX = 0;
      posY = -textHeight; // start above top
      break;
  }
}

// One scroll step
void stepScroll() {
  // Move position
  switch (DIRECTION) {
    case SCROLL_LEFT:
      posX--;
      if (posX < -textWidth) {
        posX = matrix.width();
      }
      break;

    case SCROLL_RIGHT:
      posX++;
      if (posX > matrix.width()) {
        posX = -textWidth;
      }
      break;

    case SCROLL_UP:
      posY--;
      if (posY < -textHeight) {
        posY = matrix.height();
      }
      break;

    case SCROLL_DOWN:
      posY++;
      if (posY > matrix.height()) {
        posY = -textHeight;
      }
      break;
  }

  // Draw frame
  matrix.fillScreen(0);
  matrix.setCursor(posX, posY);
  matrix.print(MESSAGE);
  matrix.show();
}

void setup() {
  matrix.begin();
  matrix.setBrightness(BRIGHTNESS);
  matrix.setTextWrap(false);       // No automatic wrapping
  matrix.setTextSize(1);           // Default 5x7 font
  textColor = matrix.Color(COLOR_R, COLOR_G, COLOR_B);
  matrix.setTextColor(textColor);

  computeTextSize();
  resetScrollPosition();

  matrix.fillScreen(0);
  matrix.show();
}

void loop() {
  uint32_t now = millis();
  if (now - lastStepTime >= SCROLL_DELAY) {
    lastStepTime = now;
    stepScroll();
  }
}