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.
- If you want to make your own font, follow this excellent guide.
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
CIRCUITPYcode.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.
CIRCUITPY
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.
Code
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
DISPLAY_NUM_GUIDES = 5
# Data source URL
DATA_SOURCE = (
"https://learn.adafruit.com/api/guides/new.json?count=%d" % DISPLAY_NUM_GUIDES
)
TITLE_DATA_LOCATION = ["guides"]
matrixportal = MatrixPortal(
url=DATA_SOURCE,
json_path=TITLE_DATA_LOCATION,
status_neopixel=board.NEOPIXEL,
)
# --- Display Setup --- #
# Colors for guide name
colors = [0xFFA500, 0xFFFF00, 0x008000, 0x0000FF, 0x4B0082, 0xEE82EE]
# Delay for scrolling the text
SCROLL_DELAY = 0.03
FONT = "/IBMPlexMono-Medium-24_jep.bdf"
# Learn guide count (ID = 0)
matrixportal.add_text(
text_font=FONT,
text_position=(
(matrixportal.graphics.display.width // 12) - 1,
(matrixportal.graphics.display.height // 2) - 8,
),
text_color=0x800000,
)
matrixportal.preload_font("0123456789")
# Learn guide title (ID = 1)
matrixportal.add_text(
text_font=terminalio.FONT,
text_position=(2, 25),
text_color=0x000080,
scrolling=True,
)
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:
try:
print("obtaining time from adafruit.io server...")
matrixportal.get_local_time()
refresh_time = time.monotonic()
except RuntimeError as e:
print("Unable to obtain time from Adafruit IO, retrying - ", e)
continue
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:
get_guide_info(guide_idx)
# Scroll the scrollable text block
matrixportal.scroll_text(SCROLL_DELAY)
guide_idx += 1
else:
guide_idx = 0
time.sleep(0.05)
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"
Page last edited February 24, 2025
Text editor powered by tinymce.
