I'm not sure where I first saw the RGB Matrices that Adadfruit sells. Probably Twitter. I know I saw a few people post about their last subscription box, which contained one (and I subsequently decided to also subscribe to Adabox - I'll get my first box sometime in December). I really liked the idea of making a digital display, and, in this time of isolation, I've acquired an itch to build and create things.

I ordered the following from Adafruit, taking advantage of a 20% off coupon code they offered for securing one's account:

• Adafruit Matrix Portal - CircuitPython Powered Internet Display - This is the wifi-enabled electronics board that powers the display and contains the programming that tells it what to display.
• 5V 2.5A Switching Power Supply with 20AWG MicroUSB Cable - This powers the electronics board.
• Micro B USB to USB C Adapter - Adapter necessary to hook up either the power adapter or to use a micro USB cable to hook the Matrix Portal up to the computer for reprogramming.
• Medium 16x32 RGB LED matrix panel - 6mm Pitch - The actual RGB matrix display.

The display is the smallest (and thus cheapest) RGB option they have; I considered it smart to start small in case I couldn't figure things out. It features 512 LEDs.

I also used the following:

• 10" x 10" Art Canvas - The LEDs are bright. Extremely bright. Putting the display behind an art canvas is a cheap way to diffuse the light.
• Thin Basswood Board - Cut to pin to the back of the canvas to hold the electronics in place.
• Tacks - Used to hold the basswood on to the back of the art canvas.
• Cushioning foam from the RGB LED matrix panel's box - Used to help keep the electronics in place and force the LEDs up against the back of the canvas.
• Acrylic Paint

Adafruit has a lot of useful tutorials on their website. I borrowed liberally from a number of guides while building my wall display, though I had to make modifications since I only had a fourth of the pixels available:

• Weather Display Matrix
• Moon Phase Clock for Adafruit Matrix Portal
• LED Matrix Display for Bitmap Pixel Art and Animation
• Use an Art Canvas to Diffuse an RGB Matrix

Finally, I used the Tom Thumb super tiny pixel font, various sprite sheets from video games, MU for programming in Circuit Python, Pixelorama for creating the BMP sprite sheets, and, finally, GIMP for making color corrections to the sprite sheets, since LEDs do not exactly see color the same way we do.

The first step was simply plugging the matrix portal into the back of the RGB Display, which embarrassingly took a couple of tries as I initially plugged it into the wrong place, and then again messed up by putting it in upside down...

Now the hard part: telling it what I wanted it to do. I wanted the display to rotate between showing the weather, the date, the time, and a series of animations. While waiting for the electronics to arrive in the mail, I worked on creating the sprite sheets for the various animations - each 32px wide and multiples of 16px tall. I created one animation each to represent the months of the year, and then I animated 11 "silly" ones to randomly appear on the display. Most of these were video game themed (Koopas, Link from the Legend of Zelda, Kirby, Ms Pacman, etc), but I also created a couple around internet memes (Nyan Cat and the "This is fine" dog). Each animation had to be arranged as a single image with the frames stacked top to bottom; to the right is an example of the Nyan Cat animation and its 23 frames.

I installed Circuit Python onto the RGB Matrix Portal, following the above Adafruit guides, and added the following libraries to the "lib" folder: adafruit_bitmap_font, adafruit_bus_device, adafruit_display_text, adafruit_esp32spi, adafruit_io, adafruit_matrixportal, adafruit_debouncer, adafruit_lis3dh, adafruit_requests, adafruit_slideshow, and neopixel. I created a "bmps" folder and put my 23 animation sprite sheets in there. I also added a "fonts" folder with the Tom Thumb font. Finally, in the base "CIRCUITPY" folder, I added the weather-icons.bmp file from the Weather Display tutorial, and three python scripts.

The code is all available here on Github. The first python file is secrets.py - this contains user-specific information for Wifi settings, location, API keys, etc. Here is a blank template:

secrets = {
    'ssid'      : '',
    'password'  : '',
    'latitude'  : ,
    'longitude' : ,
    'timezone' : "",
    'openweather_token' : '',
    'aio_username' : '',
    'aio_key' : ''
}

I modified the openweather-graphics.py script from the "Weather Display Matrix" tutorial. I reduced the number of font sizes down to one and had it use the Tom Thumb font. I then went through and commented out every line that referenced self.medium_font.

small_font = cwd + "/fonts/tom-thumb.bdf"
# medium_font = cwd + "/fonts/Arial-14.bdf"

I altered the positioning of the temperature and icon to better suit the smaller display, and I also commented out the self.description_text, self.humidity_text, and self.wind_text sections, choosing to just stick with the temperature and weather icons.

self.temp_text = Label(self.small_font, max_glyphs=8)
        self.temp_text.x = 0
        self.temp_text.y = 3
        self.temp_text.color = TEMP_COLOR
        self._text_group.append(self.temp_text)

The Tom Thumb font does not have a degrees symbol, so I replaced that in the code with an apostrophe. I also added a couple of small definitions to have the temperature replaced by the date and the time which the main code would pass along to it - this way the date and time would appear with the chosen weather icon:

def display_time(self, the_time):
        self.temp_text.text = the_time
        self.display.show(self.root_group)

def display_date(self, the_date):
        self.temp_text.text = the_date
        self.display.show(self.root_group)

And now for the main event! The code.py file is what Circuit Python runs when power is supplied to the Matrix Portal. Here's a walk through of my code.py file:

import time
import os
import board
import displayio
import random
from digitalio import DigitalInOut, Pull, Direction
from adafruit_matrixportal.network import Network
from adafruit_matrixportal.matrix import Matrix
from adafruit_debouncer import Debouncer
from secrets import secrets
import openweather_graphics  # pylint: disable=wrong-import-position

# --- Constants ---
UNITS = "imperial"
LOCATION = "Saint Louis, US"
WEATHER_SOURCE = ("http://api.openweathermap.org/data/2.5/weather?q="
                  + LOCATION + "&units=" + UNITS)
WEATHER_SOURCE += "&appid=" + secrets["openweather_token"]
DATA_LOCATION = []
SCROLL_HOLD_TIME = 0
SPRITESHEET_FOLDER = "/bmps"
DEFAULT_FRAME_DURATION = 1  # 100ms
AUTO_ADVANCE_LOOPS = 3
TIMEZONE = secrets['timezone']
TWELVE_HOUR = True

First we import all of the libraries we need as well as declare our constants. I want the weather to pull for my current location (St. Louis) and display the temperature in Fahrenheit. I tell it where to find my animations and also define how long it should pause between frames - I have my animations running at a turtle speed of 1 frame per second.

# --- Display setup ---
matrix = Matrix(width=32, height=16, bit_depth=4)
sprite_group = displayio.Group(max_size=1)
network = Network(status_neopixel=board.NEOPIXEL, debug=False)
gfx = openweather_graphics.OpenWeather_Graphics(matrix.display,
                                                am_pm=True, units=UNITS)
matrix.display.show(sprite_group)

It is extremely important to alter the Matrix() function when using the smaller RGB matrix; most of the tutorials assume you have default 64x32 matrix, and the code will not work correctly if the proper width and height are not specified. This was a source of frustration until I figured it out - the RGB matrix was just displaying garbage until this was corrected. We essentially define two display sources here - gfx is the weather/date/time display and sprite_group is the animations. We'll flip between the two later in the code.

localtime_refresh = None
weather_refresh = None
auto_advance = True

file_list = sorted(
    [
        f
        for f in os.listdir(SPRITESHEET_FOLDER)
        if (f.endswith(".bmp") and not f.startswith("."))
    ]
)

current_image = None
current_frame = 0
current_loop = 1
frame_count = 0
frame_duration = DEFAULT_FRAME_DURATION

Here we define some more variables that will be used in the various loops. The file_list pulls in an alphabetical list of the animations in the bmps folder.

def load_image():
    """
    Load an image as a sprite
    """
    # pylint: disable=global-statement
    global current_frame, current_loop, frame_count, frame_duration
    while sprite_group:
        sprite_group.pop()

    bitmap = displayio.OnDiskBitmap(
        open(SPRITESHEET_FOLDER + "/" + file_list[current_image], "rb")
    )
    frame_count = int(bitmap.height / matrix.display.height)
    frame_duration = DEFAULT_FRAME_DURATION

    sprite = displayio.TileGrid(
        bitmap,
        pixel_shader=displayio.ColorConverter(),
        width=1,
        height=1,
        tile_width=bitmap.width,
        tile_height=matrix.display.height,
    )

    sprite_group.append(sprite)
    current_frame = 0
    current_loop = 0

I use the unaltered load_image function from the "Bitmap Pixel Art and Animation" tutorial.

def advance_image(which_image):
    """
    Advance to the next image in the list and loop back at the end
    """
    # pylint: disable=global-statement
    global current_image
    current_image = which_image
    load_image()

I did alter the advance_image function from that tutorial. In the tutorial, the code advances from one image to the next in order. I modified this to use specifically the image I passed to it, as I wanted to introduce an amount of randomness into the equation.

def advance_frame():
    """
    Advance to the next frame and loop back at the end
    """
    # pylint: disable=global-statement
    global current_frame, current_loop
    current_frame = current_frame + 1
    if current_frame >= frame_count:
        current_frame = 0
        current_loop = 1
    sprite_group[0][0] = current_frame

The advance_frame function is mostly the same as it is in the tutorial, but I am using current_loop in a different capacity - for me, it will let the code know when the current animation is done and it is time to go back to the weather/date/time, and vice-versa.

def hh_mm(time_struct):
    """ Given a time.struct_time, return a string as H:MM or HH:MM, either
        12- or 24-hour style depending on global TWELVE_HOUR setting.
        This is ONLY for 'clock time,' NOT for countdown time, which is
        handled separately in the one spot where it's needed.
    """
    if TWELVE_HOUR:
        if time_struct.tm_hour > 12:
            hour_string = str(time_struct.tm_hour - 12) # 13-23 -> 1-11 (pm)
        elif time_struct.tm_hour > 0:
            hour_string = str(time_struct.tm_hour) # 1-12
        else:
            hour_string = '12' # 0 -> 12 (am)
    else:
        hour_string = '{0:0>2}'.format(time_struct.tm_hour)
    return hour_string + ':' + '{0:0>2}'.format(time_struct.tm_min)

Here I am using the hh_mm time formating function from the "Moon Phases Clock" tutorial. It's unaltered. Now for the main loop:

while True:
    if (not localtime_refresh) or (time.monotonic() -
                                   localtime_refresh) > 3600:
        try:
            network.get_local_time()
            localtime_refresh = time.monotonic()
            value = network.fetch_data(WEATHER_SOURCE,
                                       json_path=(DATA_LOCATION,))
            weather_refresh = time.monotonic()
        except RuntimeError as e:
            print(e)
            continue

I have it set up to update the weather and sync the clock once per hour.

if (current_loop == 1):
        NOW = time.localtime()
        gfx.display_weather(value)
        time.sleep(10)
        gfx.display_time(hh_mm(NOW))
        time.sleep(10)
        gfx.display_date(str(NOW.tm_mon) + '/' + str(NOW.tm_mday))
        time.sleep(10)
        gfx.display_weather(value)
        time.sleep(10)
        gfx.display_time(hh_mm(NOW))
        time.sleep(10)
        gfx.display_date(str(NOW.tm_mon) + '/' + str(NOW.tm_mday))
        time.sleep(10)

If current_loop is 1, then we proceed through the weather/time/date section (otherwise we will cycle through the frames of an animation). On top of a backdrop with the weather icon, the code displays in turn the temperature, the time, and the date (and then repeats this once) with a ten second pause on each.

if (NOW.tm_mon == 1):  # Month Pictures
            which_pic = 4
        if (NOW.tm_mon == 2):
            which_pic = 3
        if (NOW.tm_mon == 3):
            which_pic = 10
        if (NOW.tm_mon == 4):
            which_pic = 0
        if (NOW.tm_mon == 5):
            which_pic = 11
        if (NOW.tm_mon == 6):
            which_pic = 6
        if (NOW.tm_mon == 7):
            which_pic = 5
        if (NOW.tm_mon == 8):
            which_pic = 1
        if (NOW.tm_mon == 9):
            which_pic = 21
        if (NOW.tm_mon == 10):
            which_pic = 15
        if (NOW.tm_mon == 11):
            which_pic = 13
        if (NOW.tm_mon == 12):
            which_pic = 2

Based on the date, the code selects the appropriate month animation. The animation file list is alphabetically ordered; the numbers refer to the position in that list (starting at 0). "Jan.bmp" is the 5th image in the folder, so if it is January, the code picks picture position 4.

current_loop = 0
        random_image_control = random.randint(1,22)
        if (random_image_control == 2):
            which_pic = 7  #Kirby
        if (random_image_control == 4):
            which_pic = 8  #Koopas
        if (random_image_control == 6):
            which_pic = 9  #Link
        if (random_image_control == 8):
            which_pic = 12  #Mermaid
        if (random_image_control == 10):
            which_pic = 14  #Nyan
        if (random_image_control == 12):
            which_pic = 16  #Pac1
        if (random_image_control == 14):
            which_pic = 17  #Pac2
        if (random_image_control == 16):
            which_pic = 18  #Pac3
        if (random_image_control == 18):
            which_pic = 19  #Pac4
        if (random_image_control == 20):
            which_pic = 20  #Penny
        if (random_image_control == 22):
            which_pic = 22  #ThisIsFine

We set current_loop to 0 because it is now animation time. But first, I throw some randomness into the loop. The code pics a random number between 1 and 22. If the number is odd, it keeps the selected month-specific animation. If the number is even, it replaces the picture choice with one of the 11 "silly" animations.

advance_image(which_pic)
        #advance_image(15)
        matrix.display.show(sprite_group)

The code then loads up the chosen animation and switches from the weather/time/date display to the animation display. The commented out line was for testing the appearance of the specific animations - I ended up having to color/brightness correct a number of them.

    if (current_loop == 0):
        advance_frame()
        time.sleep(frame_duration)

The code loops through the main loop for infinity. If the current_loop variable is set to 0, it skips the weather/date/time and image selection section and comes here, which simply has the display advance to the next frame of the animation and wait the defined amount of time before preceeding (1 second).

With the programming done, it was time to mount the electronics into the back of the art canvas in a secure way. I measured and cut some thin basswood to use as backing, and attached that to the canvas with thumbtacks. I adjusted the positioning and pressure on the board (so that the LEDs would press against the back of the canvas - otherwise the image would not be in focus) using bits of foam that came in the box with the display itself. Finally, I had to saw off and sand down a bit of the frame for the matrix portal to have room; otherwise it was being forced to sit at an angle that made me uncomfortable.

And that's it! I painted the front with no real plan and declared the project completed. I'll be hanging this in our living room 🙂

12/2/2020 UPDATE!

My project made it onto today's Adafruit ASK AN ENGINEER livestream!