Project Overview

The six projects covered in this tutorial:

• Project 1 – Moving Dot (basic matrix setup)
• Project 2 – Text Scroll on the 8 × 8 matrix
• Project 3 – HTTP Text: send text from your phone or PC via Wi-Fi
• Project 4 – Tilt Dot, controlled by the QMI8658 accelerometer
• Project 5 – Arrow Always Up (orientation pointer using QMI8658)
• Project 6 – Target Game with buzzer and tilt control

If you get lost at any stage, compare your settings with the snippets provided for each project below.

Introduction

The projects begin with the simplest possible animation (a single moving dot) and gradually add text, Wi-Fi control, and finally sensor-based interaction using the QMI8658 accelerometer. By the end, you will understand how to control the LED matrix and react to board orientation.

Installing ESP32-S3 Boards in Arduino IDE

Before uploading any code, install the official ESP32 board support in the Arduino IDE and select an ESP32-S3 board profile (for example, an ESP32-S3 dev module). This ensures the correct flash size, frequency, and USB settings are applied when compiling and uploading.

Installing the Required Libraries

The following libraries are required for these projects:

• Adafruit NeoPixel
• Adafruit GFX
• Adafruit NeoMatrix
• QMI8658 (by Lahav Gahali)

Install them once using the Arduino Library Manager, then you can reuse them for all six projects.

About the QMI8658 Accelerometer

The QMI8658 is a 6-axis IMU combining a 3-axis accelerometer and 3-axis gyroscope. In these projects, the accelerometer values are used to detect tilt and orientation of the board.

Axis convention used throughout the projects:

• X – left / right
• Y – forward / backward
• Z – vertical (up / down)

In all tilt-based projects you will configure the accelerometer range and output data rate once, and then read the values to move a dot, orient an arrow, or control a game.

// Common QMI8658 configuration used in tilt projects
// (Projects 4, 5, and 6)

const auto ACC_RANGE   = QMI8658AccRange_2g;
const auto ACC_ODR     = QMI8658AccODR_31_25Hz;
const auto GYR_RANGE   = QMI8658GyrRange_256dps;
const auto GYR_ODR     = QMI8658GyrODR_31_25Hz;

// Sensitivity factor for converting tilt to pixels
const float TILT_TO_PIXEL_SCALE = 4.0f;   // increase for more sensitivity
    

Project 1 – Moving Dot (Basic Matrix Settings)

Project 1 is a simple moving dot animation that verifies your LED matrix wiring and basic NeoMatrix settings. You define the matrix dimensions, data pin, brightness, and the dot movement speed.

Key Settings

// Project 1 – Moving Dot (basic matrix setup)

// Matrix geometry
#define MATRIX_PIN       14
#define MATRIX_WIDTH      8
#define MATRIX_HEIGHT     8

// Layout (choose one; many boards use ZIGZAG or PROGRESSIVE)
#define MATRIX_LAYOUT  (NEO_MATRIX_TOP + NEO_MATRIX_LEFT + \
                        NEO_MATRIX_ROWS + NEO_MATRIX_ZIGZAG)
// Alternative if needed:
// #define MATRIX_LAYOUT  (NEO_MATRIX_TOP + NEO_MATRIX_LEFT + \
//                         NEO_MATRIX_ROWS + NEO_MATRIX_PROGRESSIVE)

// Visual parameters
const uint8_t  P1_BRIGHTNESS     = 40;         // overall brightness (0–255)
const uint16_t P1_DOT_COLOR      = matrix.Color(0, 255, 0); // green dot
const uint16_t P1_STEP_DELAY_MS  = 80;         // smaller = faster movement
    

By changing P1_DOT_COLOR and P1_STEP_DELAY_MS, you can quickly test different colors and animation speeds.

Project 2 – Text Scroll

Project 2 displays scrolling text such as Robojax. You control the message itself, the scroll direction, text color, and speed. This project introduces text rendering on a very small matrix.

Key Settings

// Project 2 – Text Scroll

// Scrolling message
const char* P2_MESSAGE = "Robojax";

// Text color (R, G, B)
const uint16_t P2_TEXT_COLOR = matrix.Color(255, 0, 0);  // red text

// Scroll speed
const uint16_t P2_SCROLL_DELAY_MS = 70;  // smaller = faster scroll

// Scroll direction (you will use this in your logic)
// Possible values: -1 for left, +1 for right, or use an enum
const int8_t P2_SCROLL_DIR_X = -1;  // -1 = scroll left, +1 = scroll right
const int8_t P2_SCROLL_DIR_Y =  0;  //  0 = no vertical scroll
    

If you later decide to scroll vertically (up or down), set P2_SCROLL_DIR_X to 0 and use P2_SCROLL_DIR_Y instead.

Project 3 – Mobile Phone Text (Wi-Fi Controlled Message)

Project 3 turns the ESP32-S3 into a small web server. You connect to the board over Wi-Fi, open its web page, and type a message. The text, color, and scroll speed are then used to drive the same text scroll effect on the matrix in real time.

Wi-Fi and Text Settings

// Project 3 – HTTP Text

// Wi-Fi credentials (change to your own network)
const char* P3_WIFI_SSID     = "YourWiFiName";
const char* P3_WIFI_PASSWORD = "YourWiFiPassword";

// Default text before anything is sent from the browser
String P3_currentText = "Robojax";

// Default color for the HTTP-controlled text
uint16_t P3_TEXT_COLOR = matrix.Color(0, 255, 255); // cyan

// Scroll speed for HTTP text
uint16_t P3_SCROLL_DELAY_MS = 80;  // can be updated from web page

// Allowed scroll directions (used as options in the HTML form)
enum P3_Direction {
  P3_LEFT,
  P3_RIGHT,
  P3_UP,
  P3_DOWN
};
P3_Direction P3_scrollDirection = P3_LEFT;
    

On the web page, the user chooses the direction and speed. Your code simply updates P3_scrollDirection and P3_SCROLL_DELAY_MS based on the selected options.

Project 4 – Tilt Dot (Using QMI8658)

Project 4 reads the QMI8658 accelerometer and moves a single dot around the matrix according to the tilt of the board. When the board is flat, the dot is in the center. Tilting the board moves the dot in that direction.

`

Matrix and Tilt Settings

// Project 4 – Tilt Dot

// Matrix geometry / brightness
#define MATRIX_PIN_TILT       14
#define MATRIX_WIDTH_TILT      8
#define MATRIX_HEIGHT_TILT     8

const uint8_t  P4_BRIGHTNESS   = 40;
const uint16_t P4_DOT_COLOR    = matrix.Color(0, 255, 0); // green
const uint16_t P4_UPDATE_DELAY = 30;  // ms between updates

// QMI8658 configuration (reuse from common settings if desired)
const auto P4_ACC_RANGE = QMI8658AccRange_2g;
const auto P4_ACC_ODR   = QMI8658AccODR_125Hz;

// Mapping accelerometer to pixel offset
// Negative sign may be adjusted depending on how the board is held
const float P4_TILT_SCALE_X = 3.5f; // affects left/right sensitivity
const float P4_TILT_SCALE_Y = 3.5f; // affects up/down sensitivity
    

In your code, you clamp the accelerometer readings to a range like [-1, 1], multiply them by P4_TILT_SCALE_X and P4_TILT_SCALE_Y, and add them to the center coordinates. If the movement feels reversed, simply invert the sign.

Project 5 – Arrow Always Up

Project 5 displays an arrow on the 8 × 8 matrix that always points toward the “up” side of the board. When you rotate the board, the arrow rotates so that it points to the side that is facing up.

Arrow and Orientation Settings

// Project 5 – Arrow Always Up

// Matrix brightness and color for the arrow
const uint8_t  P5_BRIGHTNESS     = 50;
const uint16_t P5_ARROW_COLOR    = matrix.Color(255, 150, 0);  // orange

// How often to update orientation
const uint16_t P5_UPDATE_DELAY_MS = 40;

// Tilt thresholds (in g) used to decide which side is "up"
// Adjust according to the board orientation in your video/demo
const float P5_TILT_THRESHOLD_LOW  = -0.25f;
const float P5_TILT_THRESHOLD_HIGH =  0.25f;

// Example mapping corners/sides based on accelerometer values
// (used in your logic to choose which arrow shape to draw)
/*
  ax, ay conditions (examples):
    ax >  P5_TILT_THRESHOLD_HIGH  -> USB side up
    ax <  P5_TILT_THRESHOLD_LOW   -> opposite USB side up
    ay >  P5_TILT_THRESHOLD_HIGH  -> one lateral side up
    ay <  P5_TILT_THRESHOLD_LOW   -> other lateral side up
*/
    

The actual drawing of the arrow is implemented with matrix.drawPixel() and matrix.drawLine(). The key part is deciding which arrow orientation to use based on the tilt zones defined by P5_TILT_THRESHOLD_LOW and P5_TILT_THRESHOLD_HIGH.

Project 6 – Target Game (Tilt-Controlled)

Project 6 is a small game where you control a player dot using the accelerometer, try to move it onto a target pixel, and get feedback from both the matrix and a buzzer when you hit the target.

Game and Buzzer Settings

// Project 6 – Tilt-Based Target Game

// Matrix brightness
const uint8_t P6_BRIGHTNESS = 60;

// Colors for game elements
const uint16_t P6_PLAYER_COLOR    = matrix.Color(0, 255, 0);   // green
const uint16_t P6_TARGET_COLOR    = matrix.Color(255, 0, 0);   // red
const uint16_t P6_BACKGROUND_COLOR = matrix.Color(0, 0, 0);    // off
const uint16_t P6_HIT_FLASH_COLOR = matrix.Color(255, 255, 0); // yellow on hit

// Buzzer pin and timing
const int      P6_BUZZER_PIN       = 4;       // change if wired differently
const uint16_t P6_BUZZER_ON_MS     = 120;     // beep duration
const uint16_t P6_BUZZER_OFF_MS    = 80;      // pause between beeps
const uint8_t  P6_BUZZER_VOLUME    = 128;     // if using PWM, duty cycle (0–255)

// Movement and game timing
const uint16_t P6_UPDATE_DELAY_MS  = 35;      // game loop delay
const float    P6_TILT_SCALE_X     = 3.5f;    // convert tilt to pixels (left/right)
const float    P6_TILT_SCALE_Y     = 3.5f;    // convert tilt to pixels (up/down)

// Minimum distance in pixels to count as a "hit"
const uint8_t  P6_HIT_DISTANCE_MAX = 0;       // 0 = exact same pixel
    

In the game logic you will:

• Read the accelerometer and move the player dot by a scaled amount.
• Clamp the player position inside the 8 × 8 grid.
• Check if the player position matches the target position (or is within the allowed distance).
• On hit, flash the matrix using P6_HIT_FLASH_COLOR and activate the buzzer using P6_BUZZER_ON_MS and P6_BUZZER_OFF_MS.
• Then move the target to a new random position and continue.

Pin Map

Conclusion

These six projects cover the essential building blocks for working with the Waveshare ESP32-S3 RGB LED Matrix: basic pixel control, text scrolling, Wi-Fi-based interaction, and tilt-based graphics and games using the QMI8658 accelerometer.

You can mix and match these ideas to build your own projects, such as scoreboards, small status displays, mini-games, or notification panels, all driven by tilt, touch, or messages from your phone or computer.