ESP32-S3 RGB LED矩陣項目2 - 滾動文字

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引腳。

• ESP32-S3 – 主要CPU，帶Wi-Fi/BLE，用於進階項目。
• 8×8 RGB矩陣 – 64粒RGB LED，用於圖示、文字同動畫。
• QMI8658C加速度計 – 喺之後嘅項目中用於傾斜同方向感應。
• USB端口 – 用於供電同透過Arduino IDE編程。
• 外露引腳 – 令你可以好似普通ESP32咁用呢塊板做其他IO。
• Boot / Reset按鈕 – 用於韌體上傳同重新啟動草圖。

喺項目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支援：

1. 開啟File > Preferences，將ESP32板嘅URL加入「Additional Boards Manager URLs」。
2. 去Tools > Board > Boards Manager…，搜尋ESP32，然後安裝官方ESP32套件。
3. 從Tools > Board選擇你嘅ESP32-S3 RGB矩陣板。
4. 透過USB連接模組，然後喺Tools > Port下面選擇正確嘅COM/串行端口。

如果板類型或者端口唔正確，草圖就唔會上傳到。

安裝NeoMatrix同所需函式庫

文字滾動係用Adafruit NeoMatrix同佢嘅依賴函式庫實現嘅。喺影片入面，佢哋係透過Library Manager安裝嘅。

你需要：

• Adafruit NeoMatrix
• Adafruit NeoPixel
• Adafruit GFX Library

1. 開啟Sketch > Include Library > Manage Libraries…。
2. 搜尋Adafruit NeoMatrix，然後撳Install。
3. 系統提示時，允許佢安裝Adafruit GFX同Adafruit NeoPixel作為依賴函式庫。

如果安裝成功，你應該會喺File > Examples > Adafruit NeoMatrix同File > Examples > Adafruit NeoPixel下面見到範例草圖。

項目2 – 程式碼設定（文字滾動）

完整嘅文字滾動草圖會自動載入喺網站上呢篇文章下面。呢度我哋只集中喺你大概想改嘅設定值：引腳、矩陣尺寸、亮度、文字字串、顏色、滾動速度，同埋可選嘅方向。

下面所有片段都係取自草圖頂部嘅設定部分，等你可以快速調整行為，而唔使掂到主要邏輯。

矩陣引腳同尺寸

同項目1一樣，RGB矩陣連接去GPIO 14，包含64粒LED（8×8）。確保呢兩行同你嘅模組匹配：

 // 連接去8×8 RGB矩陣嘅引腳 
const int MATRIX_PIN = 14; // 喺呢個模組上必須係14 // 矩陣尺寸（寬度同高度）
 const int MATRIX_WIDTH = 8; 
const int MATRIX_HEIGHT = 8; 

如果你從NeoMatrix函式庫複製範例，佢可能用唔同嘅引腳或者尺寸；一定要改返做同呢塊板匹配。

文字嘅亮度

亮度通常用0到255之間嘅值控制，0係熄，255係最大亮度。一個中等嘅值通常已經夠：

// 整體矩陣亮度（0–255）
uint8_t matrixBrightness = 40; // 室內舒適亮度 // 喺
setup():
matrix.setBrightness(matrixBrightness);

如果你喺光猛環境或者短時間用塊面板，可以加大呢個值，但如果你近距離睇顯示屏，就唔好校得太高。

要滾動嘅文字

實際訊息係以字串形式儲存。喺影片入面，例子文字係Robojax。你可以改成任何你鍾意嘅短標籤或者訊息：

 // 要喺8×8矩陣上滾動嘅文字 const char scrollText[] = "Robojax";
 // 改成你嘅訊息

記住呢個只係一個8×8矩陣，所以好長嘅訊息會滾動得耐啲，而且可能難啲睇。

文字顏色（RGB數值）

滾動文字嘅顏色係由紅、綠、藍三個部分（0–255）設定。例如，純紅色係(255, 0, 0)，純綠色係(0, 255, 0)，純藍色係(0, 0, 255)。喺程式入面你會見到類似咁嘅嘢：

 // 文字顏色（R, G, B） uint8_t textRed = 255; // 紅色部分 uint8_t textGreen = 0; // 綠色部分 uint8_t textBlue = 0; // 藍色部分 

要改顏色：

• 黃色：textRed = 255; textGreen = 255; textBlue = 0;
• 青色：textRed = 0; textGreen = 255; textBlue = 255;
• 白色：textRed = 255; textGreen = 255; textBlue = 255;

影片入面仲示範咗用網上顏色揀選器嚟搵RGB數值，然後輸入落程式度。

滾動速度（幀之間嘅延遲）

滾動速度係由每次更新步驟之間嘅延遲值（以毫秒計）控制。數值越細，文字郁得越快；數值越大，就慢啲。喺程式入面，你應該會搵到一個變數好似：

// 滾動步驟之間嘅延遲（以毫秒計） int scrollDelayMs = 50;
// 越細越快，越大越慢

例子：

• scrollDelayMs = 20; → 快速滾動。
• scrollDelayMs = 50; → 中等速度（同影片差唔多）。
• scrollDelayMs = 100; 或者更多 → 慢速，容易閱讀嘅滾動。

喺loop()入面，呢個值會喺每次重新繪製文字位置之後用喺delay(scrollDelayMs);嘅呼叫度。

滾動方向（可選）

喺「基本文字滾動」項目入面，我哋通常向左滾動，但定義一個符號方向變數會有用，等你可以之後試其他方向（左、右、上、下）。

一個常見嘅模式係：

 // 滾動方向選擇器 // 0 = 左，1 = 右，2 = 上，3 = 下
int scrollDirection = 0; // 預設：向左滾動

主循環跟住檢查scrollDirection，然後將文字移向所選方向。對於項目2，你可以將佢設為0（左），但如果你之後擴展程式，你可以加條件好似：

 if (scrollDirection == 0) {
// 將文字移向左
} else if (scrollDirection == 1) {
// 將文字移向右
} else if (scrollDirection == 2) {
// 將文字移向上
} else if (scrollDirection == 3) {
// 將文字移向下
}

呢篇文章只記錄設定。完整實現係喺文章下面載入嘅程式碼入面。

總結

項目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 Matrix

ESP32 S3 Matrix pin out

ESP32-S3_RGB_8x8_matrix1

ESP32-S3_RGB_8x8_matrix-2

ESP32-S3-Mtrix - Alway Up

/* 
  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();
  }
}