ESP32 RGB Matrix Project

DIY LED Matrix Picture Frame

In this ElektroBox project, I build a small LED matrix picture frame using an ESP32 and two chained RGB LED matrix panels.

The picture frame displays a custom 64 × 64 pixel image stored as an RGB565 bitmap. The ESP32 reads the bitmap data from program memory and draws it across both matrix panels.

DIY LED matrix picture frame with ESP32 and two RGB matrix panels

1. Project Idea

The idea for this project came from leftover parts from my ElektroClock build. While working with LED matrix displays, I noticed that multiple panels can be chained together. This makes it possible to create a larger display area and use it as a small pixel-art picture frame.

Main controllerESP32 development board.

DisplayTwo chained 64 × 32 RGB HUB75 LED matrix panels.

Image format64 × 64 pixel RGB565 bitmap stored in program memory.

2. Required Parts

ESP32 development board
Two RGB LED matrix panels
HUB75 ribbon cable or jumper wires
Stable 5 V power supply
Leftover PCB from the ElektroClock project or a prototype wiring setup
Jumper wires
3D-printed mounting plate
Prototype case or enclosure
Optional screws and spacers

3. How the System Works

The two matrix panels are chained together. The ESP32 controls the input of the first panel, and the display data continues from the first panel to the second one. In the software, both physical panels are handled as one virtual 64 × 64 pixel display.

Image file → converted to 64 × 64 RGB565 bitmap

Bitmap header file → added to the Arduino sketch folder

ESP32 → sends the pixel data to the chained HUB75 panels

Two 64 × 32 panels → displayed as one 64 × 64 picture frame

4. Designing the Mount

To align both LED matrix panels correctly, I designed a simple mounting plate. The plate keeps both displays in the correct position and makes the complete frame more stable.

First, I measured the mounting holes and outer dimensions of the LED matrix panels. Then I designed the back plate and prepared it for 3D printing. The design is kept simple, so it is easy to print and modify for different panel sizes.

5. Connecting the LED Matrix Panels

The LED matrix panels use the HUB75 interface. Several signal wires are required for the RGB channels, row selection, latch, output enable, and clock signal.

In the final version, I reused a leftover PCB from the ElektroClock project. This keeps the wiring cleaner and more reliable. For a first prototype, jumper wires can also be used.

Important: The output connector of the first panel must be connected to the input connector of the second panel. The ESP32 only controls the first panel directly.

Pin overview

ESP32 to HUB75 matrix wiring

ESP32 to HUB75 panel wiring used in this sketch:

R1  -> GPIO 25
G1  -> GPIO 26
B1  -> GPIO 27
R2  -> GPIO 14
G2  -> GPIO 12
B2  -> GPIO 13

A   -> GPIO 23
B   -> GPIO 19
C   -> GPIO 5
D   -> GPIO 17
E   -> not used / -1

LAT -> GPIO 4
OE  -> GPIO 15
CLK -> GPIO 16

Panel setup:
Two 64 x 32 RGB matrix panels
Stacked vertically
Virtual display size: 64 x 64 px
Chain type: CHAIN_BOTTOM_LEFT_UP

6. Image Conversion

The ESP32 sketch does not load PNG or JPG files directly. The image first has to be resized to 64 × 64 pixels and converted to RGB565. The Python converter below creates two files: a .h header file for the Arduino sketch and a .bin file for testing or reuse.

Offline converter: The Python script runs locally on your computer. It does not use Wi-Fi, sockets, requests, a web server, or any internet connection. This makes it firewall-friendly and avoids unnecessary network permission prompts. The code block is displayed as plain copyable text and is not executed by the website.

Install required Python package

Install Pillow

pip install pillow

Python image to RGB565 converter

Save this script as image_to_rgb565_converter.py, run it, select your image, and copy the generated header file into the same folder as your Arduino sketch.

image_to_rgb565_converter.py

from __future__ import annotations

from pathlib import Path
import re
import tkinter as tk
from tkinter import filedialog, messagebox

from PIL import Image, ImageOps


WIDTH = 64
HEIGHT = 64


def rgb888_to_rgb565(r: int, g: int, b: int) -> int:
    “””
    Convert RGB888 to RGB565:
    RRRRRGGGGGGBBBBB
    “””
    return ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)


def make_c_identifier(name: str) -> str:
    “””
    Create a safe C/Arduino identifier from the image file name.
    Example: “my picture.png” -> “my_picture”
    “””
    name = re.sub(r”\W+”, “_”, name).strip(“_”)

    if not name:
        name = “bitmap”

    if name[0].isdigit():
        name = “_” + name

    return name


def convert_image(input_path: str | Path, crop: bool = True) -> tuple[Path, Path]:
    “””
    Convert an image to:
    – a 64×64 RGB565 Arduino header file
    – a 64×64 RGB565 binary file

    This script is offline-only. It does not open a socket, start a server,
    download anything, or contact the internet, so it should not trigger a
    firewall network prompt.
    “””
    input_path = Path(input_path)

    output_name = make_c_identifier(input_path.stem) + “_64x64”
    header_path = input_path.with_name(output_name + “.h”)
    bin_path = input_path.with_name(output_name + “.bin”)

    img = Image.open(input_path).convert(“RGBA”)

    # Replace transparency with black background
    background = Image.new(“RGBA”, img.size, (0, 0, 0, 255))
    img = Image.alpha_composite(background, img).convert(“RGB”)

    # Resize image to 64×64
    if crop:
        img = ImageOps.fit(
            img,
            (WIDTH, HEIGHT),
            method=Image.Resampling.LANCZOS
        )
    else:
        img = ImageOps.pad(
            img,
            (WIDTH, HEIGHT),
            method=Image.Resampling.LANCZOS,
            color=(0, 0, 0)
        )

    pixels_rgb565: list[int] = []

    for y in range(HEIGHT):
        for x in range(WIDTH):
            r, g, b = img.getpixel((x, y))
            pixels_rgb565.append(rgb888_to_rgb565(r, g, b))

    # Save binary file, little-endian RGB565
    bin_data = bytearray()
    for value in pixels_rgb565:
        bin_data.extend(value.to_bytes(2, byteorder=”little”))

    bin_path.write_bytes(bin_data)

    # Save C / Arduino header file
    lines: list[str] = []
    lines.append(f”// Auto-generated from ‘{input_path.name}'”)
    lines.append(f”// {WIDTH}x{HEIGHT} pixels, RGB565, row-major”)
    lines.append(“#pragma once”)
    lines.append(“#include <stdint.h>”)
    lines.append(“#include <pgmspace.h>”)
    lines.append(“”)
    lines.append(f”const uint16_t {output_name}[{WIDTH * HEIGHT}] PROGMEM = {{“)

    for i, value in enumerate(pixels_rgb565):
        if i % 16 == 0:
            lines.append(”  “)

        lines[-1] += f”0x{value:04X}”

        if i != len(pixels_rgb565) – 1:
            lines[-1] += “, ”

        if i % 16 == 15:
            continue

    lines.append(“};”)
    lines.append(“”)

    header_path.write_text(“\n”.join(lines), encoding=”utf-8″)

    return header_path, bin_path


def select_file() -> None:
    file_path = filedialog.askopenfilename(
        title=”Select image file”,
        filetypes=[
            (“Image files”, “*.png *.jpg *.jpeg *.bmp *.gif *.webp”),
            (“All files”, “*.*”)
        ]
    )

    if not file_path:
        return

    try:
        crop = bool(crop_var.get())
        header_path, bin_path = convert_image(file_path, crop=crop)

        messagebox.showinfo(
            “Conversion finished”,
            “RGB565 bitmap created successfully!\n\n”
            f”Header file:\n{header_path}\n\n”
            f”Binary file:\n{bin_path}”
        )

    except Exception as exc:
        messagebox.showerror(
            “Error”,
            f”Could not convert image:\n\n{exc}”
        )


# GUI setup
root = tk.Tk()
root.title(“Image to 64×64 RGB565 Converter”)
root.geometry(“420×220″)
root.resizable(False, False)

title_label = tk.Label(
    root,
    text=”Image to 64×64 RGB565 Converter”,
    font=(“Arial”, 14, “bold”)
)
title_label.pack(pady=15)

info_label = tk.Label(
    root,
    text=”Select an image file.\nThe script creates a .h and .bin RGB565 bitmap.”,
    font=(“Arial”, 10)
)
info_label.pack(pady=5)

crop_var = tk.BooleanVar(value=True)

crop_checkbox = tk.Checkbutton(
    root,
    text=”Crop image to fill 64×64″,
    variable=crop_var
)
crop_checkbox.pack(pady=10)

select_button = tk.Button(
    root,
    text=”Select Image”,
    command=select_file,
    width=20,
    height=2
)
select_button.pack(pady=15)

root.mainloop()

Generated bitmap header structure

The generated header file contains the 4096 RGB565 pixel values. The array name is based on the image file name. If the generated array is called mhf_64x64, the Arduino sketch must use the same name.

Example RGB565 header structure

// Auto-generated from ‘my_picture.png’
// 64×64 pixels, RGB565, row-major
#pragma once
#include <stdint.h>
#include <pgmspace.h>

const uint16_t mhf_64x64[4096] PROGMEM = {
  // 4096 RGB565 values are generated by the Python converter
  // Example:
  0x0000, 0x0000, 0xFFFF
};

7. Firmware Structure

The firmware initializes the matrix library, configures the HUB75 pins, creates the virtual 64 × 64 matrix, and draws the generated RGB565 bitmap from program memory.

Name check: The header file name and the array name must match your generated file. In the code below, the header is mhf_64x64.h and the bitmap array is mhf_64x64. If your converter creates a different name, change both places in the sketch.

Complete Arduino sketch

ESP32 HUB75 LED matrix picture frame sketch

#include <Arduino.h>
#include <ESP32-HUB75-MatrixPanel-I2S-DMA.h>
#include <ESP32-VirtualMatrixPanel-I2S-DMA.h>
#include “mhf_64x64.h”

/*——————— Pins ————————-*/
#define R1_PIN 25
#define G1_PIN 26
#define B1_PIN 27
#define R2_PIN 14
#define G2_PIN 12
#define B2_PIN 13
#define A_PIN 23
#define B_PIN 19
#define C_PIN 5
#define D_PIN 17
#define E_PIN -1
#define LAT_PIN 4
#define OE_PIN 15
#define CLK_PIN 16

/*——————— Matrix config —————-*/
#define PANEL_RES_X 64
#define PANEL_RES_Y 32
#define PANEL_CHAIN  2

// Two 64×32 panels stacked vertically = 64×64
#define NUM_ROWS 2
#define NUM_COLS 1

#define VIRTUAL_MATRIX_CHAIN_TYPE CHAIN_BOTTOM_LEFT_UP

MatrixPanel_I2S_DMA *dma_display = nullptr;
VirtualMatrixPanel  *vpanel = nullptr;

HUB75_I2S_CFG mxconfig(PANEL_RES_X, PANEL_RES_Y, PANEL_CHAIN);

/*——————— Blit helper ——————*/
void drawRGB565Image_P(int x0, int y0, const uint16_t* img, int w, int h) {
  for (int y = 0; y < h; y++) {
    for (int x = 0; x < w; x++) {
      uint16_t c = pgm_read_word(img + y * w + x);
      vpanel->drawPixel(x0 + x, y0 + y, c);
    }
  }
}

void setup() {
  Serial.begin(115200);
  delay(150);

  mxconfig.gpio.r1 = R1_PIN;
  mxconfig.gpio.g1 = G1_PIN;
  mxconfig.gpio.b1 = B1_PIN;
  mxconfig.gpio.r2 = R2_PIN;
  mxconfig.gpio.g2 = G2_PIN;
  mxconfig.gpio.b2 = B2_PIN;

  mxconfig.gpio.a = A_PIN;
  mxconfig.gpio.b = B_PIN;
  mxconfig.gpio.c = C_PIN;
  mxconfig.gpio.d = D_PIN;
  mxconfig.gpio.e = E_PIN;

  mxconfig.gpio.lat = LAT_PIN;
  mxconfig.gpio.oe  = OE_PIN;
  mxconfig.gpio.clk = CLK_PIN;

  // Important for chained panels with color/data problems
  mxconfig.clkphase = false;                 // Try false first. If worse, try true.
  mxconfig.i2sspeed = HUB75_I2S_CFG::HZ_10M; // Slower and more stable for chained panels

  dma_display = new MatrixPanel_I2S_DMA(mxconfig);

  if (!dma_display->begin()) {
    Serial.println(“Matrix begin failed!”);
    return;
  }

  dma_display->setBrightness8(90); // Lower brightness reduces power/noise problems

  vpanel = new VirtualMatrixPanel(
    *dma_display,
    NUM_ROWS,
    NUM_COLS,
    PANEL_RES_X,
    PANEL_RES_Y,
    VIRTUAL_MATRIX_CHAIN_TYPE
  );

  vpanel->clearScreen();

  drawRGB565Image_P(0, 0, mhf_64x64, 64, 64);
}

void loop() {
  // Static picture frame: the bitmap only needs to be drawn once in setup().
}

8. Common Problems

The second panel shows wrong colors

Check the RGB pin mapping, scan pattern, panel type, and HUB75 library configuration. For chained panels, the slower HZ_10M I2S speed and the correct clock phase can improve stability.

The image is mirrored or split incorrectly

Check the virtual matrix chain type and the physical orientation of both matrix panels. For two 64 × 32 panels stacked vertically, this project uses CHAIN_BOTTOM_LEFT_UP.

The display flickers or resets

Use a stable 5 V power supply, short power wires, and a common ground between the ESP32 and panels. Lowering the brightness can also reduce current peaks and noise problems.

The Arduino sketch does not compile because the bitmap name is missing

Open the generated .h file and check the exact array name after const uint16_t. Use exactly this name in drawRGB565Image_P(). C++ is case-sensitive.

9. Final Result

The final result is a compact LED matrix picture frame that displays a custom pixel-art image on two chained RGB matrix panels. It is a useful project for reusing leftover display hardware and testing RGB565 image workflows.