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 secrets.py 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 secrets.py file:

secrets = {
	'ssid' : 'your_wifi_ssid',
	'password : 'your_wifi_password',
	'aio_username' : 'your_aio_username',
	'aio_key' : 'your_big_huge_super_long_aio_key'

Add Libraries

You will need the following libraries on your CIRCUITPY volume:

  • adafruit_bitmap_font
  • adafruit_esp32spi
  • adafruit_matrixportal
  • adafruit_bus_device
  • adafruit_io
  • adafruit_requests.mpy
  • adafruit_display_text
  • adafruit_lis3dh.mpy
  • neopixel.mpy

Your CIRCUITPY drive should look like the following screenshot:

NOTE: Do not copy the contents of the library folders into the /lib directory, keep folder-style libraries in their named folder on copy.

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.


Click the Download: Zip File link below in the code window to get a zip file with all the files needed for the project. Copy code.py from the zip file and place it on the CIRCUITPY drive of your board which appears on your computer when the Matrix Portal board is connected via USB.

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) - 4,

# 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 Oct 28, 2020.

This page (Code the Matrix Portal) was last updated on Apr 18, 2021.

Text editor powered by tinymce.