This project requires CircuitPython 6.1.0 beta 2 or higher.

Libraries

The project needs no other libraries other than those in the MagTag CircuitPython Libraries page.

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. The font files below can be placed in the fonts/ directory on the CIRCUITPY drive which appears on your computer when the MagTag is plugged into your computer via a known good data USB-C cable.

  • 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.

Code

Click the "Download Project Zip" link in the code window below and save the file to your computer in a place you can remember. Plug your MagTag into your computer via a known good USB-A to USB-C data cable. A new drive named CIRCUITPY should appear. Open up the Zip file and copy out the contents to your computer. Copy the code.py file from the directory you unzip the files to the MagTag in the main directory on the CIRCUITPY drive. Copy the four .bdf font files to the root directory also.

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
# 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) 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)

All Files

The directory listings at left show the main/root directory of the CIRCUITPY drive, the /lib directory, and the /fonts directory to illustrate which files are needed on the device.

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 Oct 23, 2021.

Text editor powered by tinymce.