This example uses 4 64×32 matrices attached to a single MatrixPortal using the "serpentine" wiring style.

Place the code below on CIRCUITPY (as and the bitmap image (as wales.bmp). You can change the bitmap to any other file that works with OnDiskBitmap, up to 128x64 pixels. No additional libraries are required. You can adapt it to other boards by changing the lines that create the RGBMatrix object.

# SPDX-FileCopyrightText: 2021 Jeff Epler for Adafruit Industries
# SPDX-License-Identifier: MIT

# Minimal example displaying an image tiled across multiple RGB LED matrices.
# This is written for MatrixPortal and four 64x32 pixel matrices, but could
# be adapted to different boards and matrix combinations.
# No additional libraries required, just uses displayio.
# Image wales.bmp should be in CIRCUITPY root directory.

import board
import displayio
import framebufferio
import rgbmatrix

displayio.release_displays() # Release current display, we'll create our own

# Create RGB matrix object for a chain of four 64x32 matrices tiled into
# a single 128x64 pixel display -- two matrices across, two down, with the
# second row being flipped. width and height args are the combined size of
# all the tiled sub-matrices. tile arg is the number of rows of matrices in
# the chain (horizontal tiling is implicit from the width argument, doesn't
# need to be specified, but vertical tiling must be explicitly stated).
# The serpentine argument indicates whether alternate rows are flipped --
# cabling is easier this way, downside is colors may be slightly different
# when viewed off-angle. bit_depth and pins are same as other examples.
MATRIX = rgbmatrix.RGBMatrix(
    width=128, height=64, bit_depth=6, tile=2, serpentine=True,
    clock_pin=board.MTX_CLK, latch_pin=board.MTX_LAT,

# Associate matrix with a Display to use displayio features
DISPLAY = framebufferio.FramebufferDisplay(MATRIX, auto_refresh=False,

# Load BMP image, create Group and TileGrid to hold it
FILENAME = "wales.bmp"

# CircuitPython 6 & 7 compatible
BITMAP = displayio.OnDiskBitmap(open(FILENAME, "rb"))
TILEGRID = displayio.TileGrid(
    pixel_shader=getattr(BITMAP, 'pixel_shader', displayio.ColorConverter()),

# # CircuitPython 7+ compatible
# BITMAP = displayio.OnDiskBitmap(FILENAME)
# TILEGRID = displayio.TileGrid(
#     BITMAP,
#     pixel_shader=BITMAP.pixel_shader,
#     tile_width=BITMAP.width,
#     tile_height=BITMAP.height
# )

GROUP = displayio.Group()
DISPLAY.root_group = GROUP

# Nothing interactive, just hold the image there
while True:

This guide was first published on Apr 20, 2020. It was last updated on Jun 20, 2024.

This page (Advanced Example: Big, big flag of Wales) was last updated on Jun 19, 2024.

Text editor powered by tinymce.