Text Editor

Adafruit recommends using the Mu editor for editing your CircuitPython code. You can get more info in this guide.

Alternatively, you can use any text editor that saves simple text files.

Add Font

Instead of the standard terminalio typeface, this project uses a lovely typeface converted to a bitmap font for use on the matrix display.

We'll be using a 64x32 version of the IBM Plex Mono Medium typeface. Download and uncompress the zip file and then drag it onto the board's CIRCUITPY drive. 

Secrets Setup

Instead of relying on a real-time-clock or the microcontroller's software timers, this code uses Adafruit IO's time service to query an exact time for your location. You will need an Adafruit IO account to use this service. If you don't already have an Adafruit login, create one here.

Once you have logged into your account, there are two pieces of information you'll need to place in your settings.toml file: your Adafruit IO username, and Adafruit IO key. Head to io.adafruit.com and simply click the Adafruit IO Key link on the left hand side of the Adafruit IO page to obtain this information.

Then, add them to the settings.toml file:

CIRCUITPY_WIFI_SSID = "your_wifi_ssid"
CIRCUITPY_WIFI_PASSWORD = "your_wifi_password"
AIO_USERNAME = "your_aio_username"
AIO_KEY = "your_aio_key"

Install Code

To use with CircuitPython, you need to first install a few libraries, into the lib folder on your CIRCUITPY drive. Then you need to update code.py with the example script.

Thankfully, we can do this in one go. In the example below, click the Download Project Bundle button below to download the necessary libraries and the code.py file in a zip file. Extract the contents of the zip file, open the directory Matrix_Portal_Learn_Stats/ and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:


Connect to the Internet

Once you have CircuitPython setup and libraries installed, next is to get your board connected to the Internet. The process for connecting can be found here. Once you've connected to WiFi using the code on that guide, come back to this page.


If you copied a different code.py over when testing the internet connection, make sure to copy the one from this project over again.

# SPDX-FileCopyrightText: 2020 Brent Rubell for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
from random import randrange
import board
import terminalio
from adafruit_matrixportal.matrixportal import MatrixPortal

# --- Data Setup --- #
# Number of guides to fetch and display from the Adafruit Learning System
# Data source URL
    "https://learn.adafruit.com/api/guides/new.json?count=%d" % DISPLAY_NUM_GUIDES

matrixportal = MatrixPortal(

# --- Display Setup --- #

# Colors for guide name
colors = [0xFFA500, 0xFFFF00, 0x008000, 0x0000FF, 0x4B0082, 0xEE82EE]

# Delay for scrolling the text

FONT = "/IBMPlexMono-Medium-24_jep.bdf"

# Learn guide count (ID = 0)
        (matrixportal.graphics.display.width // 12) - 1,
        (matrixportal.graphics.display.height // 2) - 8,

# Learn guide title (ID = 1)
    text_position=(2, 25),

def get_guide_info(index):
    """Parses JSON data returned by the DATA_SOURCE
    to obtain the ALS guide title and number of guides and
    sets the text labels.
    :param int index: Guide index to display

    if index > DISPLAY_NUM_GUIDES:
        raise RuntimeError("Provided index may not be larger than DISPLAY_NUM_GUIDES.")
    print("Obtaining guide info for guide %d..." % index)

    # Traverse JSON data for title
    guide_count = matrixportal.network.json_traverse(als_data.json(), ["guide_count"])

    # Set guide count
    matrixportal.set_text(guide_count, 0)

    guides = matrixportal.network.json_traverse(als_data.json(), TITLE_DATA_LOCATION)
    guide_title = guides[index]["guide"]["title"]
    print("Guide Title", guide_title)

    # Select color for title text
    color_index = randrange(0, len(colors))

    # Set the title text color
    matrixportal.set_text_color(colors[color_index], 1)

    # Set the title text
    matrixportal.set_text(guide_title, 1)

refresh_time = None
guide_idx = 0
prv_hour = 0
while True:
    if (not refresh_time) or (time.monotonic() - refresh_time) > 900:
            print("obtaining time from adafruit.io server...")
            refresh_time = time.monotonic()
        except RuntimeError as e:
            print("Unable to obtain time from Adafruit IO, retrying - ", e)

    if time.localtime()[3] != prv_hour:
        print("New Hour, fetching new data...")
        # Fetch and store guide info response
        als_data = matrixportal.network.fetch(DATA_SOURCE)
        prv_hour = time.localtime()[3]

    # Cycle through guides retrieved
    if guide_idx < DISPLAY_NUM_GUIDES:

        # Scroll the scrollable text block
        guide_idx += 1
        guide_idx = 0

Code Usage

Every hour, the code will fetch and scroll the five latest guides from the Adafruit Learning System. The number of guides on the Adafruit Learning System will be displayed on top of the scrolling text.

Customize Colors

You can change the colors of the scrolling text. In the code, the scrolling text's color is defined as a list of hex color values.

# Colors for guide name
colors = [0xffa500, 0xffff00,
          0x008000, 0x0000ff,
          0x4b0082, 0xee82ee]

To add a new color, convert a RGB color to a hex color and add it to the colors list.

Customize Fonts

This code uses the IBMPlexMono Medium typeface to display the number of guides in the Adafruit Learning System. To change the font, you'll first need to convert it to a single bitmap font in a size that works for the 64x32 pixel matrix display.

Then, change the following code in this guide to the name of your new font:

FONT = "/IBMPlexMono-Medium-24_jep.bdf"

Change the Scrolling Speed

You can also change the speed of text scrolling across the bottom of the MatrixPortal by editing the following line. The scrolling delay is measured in seconds.

# Delay for scrolling the text


This guide was first published on Oct 28, 2020. It was last updated on Jul 24, 2024.

This page (Code the Matrix Portal) was last updated on Jul 24, 2024.

Text editor powered by tinymce.