This project requires CircuitPython 6.1.0 beta 2 or higher.

Fonts

To take advantage of the lovely eInk display, 4 different fonts are used. They are obtained when downloading all the project resources using "Download Project Zip" in the code window below.

  • Lato-Bold-ltd-25.bdf
  • Arial-Bold-12.bdf
  • Arial-12.bdf

Note the Lato-Bold-ltd-25.bdf font only has the letters to display "Next SpaceX Launch". This is to save space on the limited amount of flash on the MagTag. Lato is a freely licensed version of Arial provided by Google. An additional, built-in font in the terminalio library is used for the details.

If you want to look at using your own fonts, see the excellent guide Custom Fonts for CircuitPython Displays.

Installing Project 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 MagTag_SpaceX/ 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:

CIRCUITPY
If you're having difficulty running this example, it could be because your MagTag CircuitPython firmware or library needs to be upgraded! Please be sure to follow https://learn.adafruit.com/adafruit-magtag/circuitpython to install the latest CircuitPython firmware and then also replace/update ALL the MagTag-specific libraries mentioned here https://learn.adafruit.com/adafruit-magtag/circuitpython-libraries-2
# SPDX-FileCopyrightText: 2020 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT

# SpaceX Launch Display, by Anne Barela November 2020
# MIT License - for Adafruit Industries LLC
# See https://github.com/r-spacex/SpaceX-API for API info

import time
import terminalio
from adafruit_magtag.magtag import MagTag

months = ["January", "February", "March", "April", "May", "June", "July",
          "August", "September", "October", "November", "December"]
USE_24HR_TIME = True
# in seconds, we can refresh about 100 times on a battery
TIME_BETWEEN_REFRESHES = 24 * 60 * 60  # once a day delay

# Set up data location and fields
DATA_SOURCE = "https://api.spacexdata.com/v4/launches/next"
DETAIL_LOCATION = ['details']
NAME_LOCATION = ['name']
DATE_LOCATION = ['date_local']

# These functions take the JSON data keys and does checks to determine
#   how to display the data. They're used in the add_text blocks below

def mission_transform(val):
    if val == None:
        val = "Unavailable"
    return "Mission: " + val

def time_transform(val2):
    if val2 == None:
        return "When: Unavailable"
    month = int(val2[5:7])
    day = int(val2[8:10])
    hour = int(val2[11:13])
    min = int(val2[14:16])

    if USE_24HR_TIME:
        timestring = "%d:%02d" % (hour, min)
    elif hour > 12:
        timestring = "%d:%02d pm" % (hour-12, min)
    else:
        timestring = "%d:%02d am" % (hour, min)

    return "%s %d, at %s" % (months[month-1], day, timestring)

def details_transform(val3):
    if val3 == None or not len(val3):
        return "Details: To Be Determined"
    return "Details: " + val3[0:166] + "..."

# Set up the MagTag with the JSON data parameters
magtag = MagTag(
    url=DATA_SOURCE,
    json_path=(NAME_LOCATION, DATE_LOCATION, DETAIL_LOCATION)
)

magtag.add_text(
    text_font="/fonts/Lato-Bold-ltd-25.bdf",
    text_position=(10, 15),
    is_data=False
)
# Display heading text below with formatting above
magtag.set_text("Next SpaceX Launch")

# Formatting for the mission text
magtag.add_text(
    text_font="/fonts/Arial-Bold-12.pcf",
    text_position=(10, 38),
    text_transform=mission_transform
)

# Formatting for the launch time text
magtag.add_text(
    text_font="/fonts/Arial-12.bdf",
    text_position=(10, 60),
    text_transform=time_transform
)

# Formatting for the details text
magtag.add_text(
    text_font=terminalio.FONT,
    text_position=(10, 94),
    line_spacing=0.8,
    text_wrap=47,     # wrap text at this count
    text_transform=details_transform
)

try:
    # Have the MagTag connect to the internet
    magtag.network.connect()
    # This statement gets the JSON data and displays it automagically
    value = magtag.fetch()
    print("Response is", value)
except (ValueError, RuntimeError, ConnectionError, OSError) as e:
    print("Some error occured, retrying! -", e)

# wait 2 seconds for display to complete
time.sleep(2)
magtag.exit_and_deep_sleep(TIME_BETWEEN_REFRESHES)

Code Runthrough

The adafruit_magtag library handles much of the internet data fetching and data display for guides like this.

Three magtag.add_text transform functions are defined. They each specify how three different JSON text fields are displayed. time_transform has two different ways to display the time. One in month, day, year, time format and one in year, month, day, time format. Select the one you want and  comment out the other (or create your own, the data returned is formatted as follows: 

2020-12-05T11:39:00-05:00

Error checking is used if fields are blank to note that status on the display.

The MagTag is then invoked with the JSON data.

Each magtag.add_text block defines the data to display. There are four, the first one for the title (is_data = False to set so the function knows this is not a JSON text field). Each text display as a different font in this example (although you can use the same font for multiple fields). The text_position varies for each to spread text over the display. On the last field, there is a text_wrap property to automatically wrap long lines of text, perfect for the long description.

Finally a 2 second delay allows the screen to refresh. Then the board deep sleeps for the specified delay in seconds (set to 24 hours by default).

This guide was first published on Dec 02, 2020. It was last updated on Dec 02, 2020.

This page (Code) was last updated on May 26, 2023.

Text editor powered by tinymce.