Libraries

First, make sure you've installed the fundamental MagTag libraries as shown on the MagTag CircuitPython Setup page.

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.

Code

Click the Download: Project 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 on the CIRCUITPY drive.

Also copy the whole /bmps directory from the zip file and place and its contents it on the CIRCUITYPY drive. These are some sample images you can start with.

Copy the /fonts directory from the zip file and place and its contents it on the CIRCUITYPY drive.

# SPDX-FileCopyrightText: 2020 Limor Fried for Adafruit Industries
#
# SPDX-License-Identifier: MIT

# MagTag Quote Board
# Displays Quotes from the Adafruit quotes server
# Be sure to put WiFi access point info in secrets.py file to connect

import time
from adafruit_magtag.magtag import MagTag

# Set up where we'll be fetching data from
DATA_SOURCE = "https://www.adafruit.com/api/quotes.php"
QUOTE_LOCATION = [0, "text"]
AUTHOR_LOCATION = [0, "author"]
# in seconds, we can refresh about 100 times on a battery
TIME_BETWEEN_REFRESHES = 1 * 60 * 60  # one hour delay

magtag = MagTag(
    url=DATA_SOURCE,
    json_path=(QUOTE_LOCATION, AUTHOR_LOCATION),
)

magtag.graphics.set_background("/bmps/magtag_quotes_bg.bmp")

# quote in bold text, with text wrapping
magtag.add_text(
    text_font="/fonts/Arial-Bold-12.bdf",
    text_wrap=28,
    text_maxlen=120,
    text_position=(
        (magtag.graphics.display.width // 2),
        (magtag.graphics.display.height // 2) - 10,
    ),
    line_spacing=0.75,
    text_anchor_point=(0.5, 0.5),  # center the text on x & y
)

# author in italic text, no wrapping
magtag.add_text(
    text_font="/fonts/Arial-Italic-12.bdf",
    text_position=(magtag.graphics.display.width // 2, 118),
    text_anchor_point=(0.5, 0.5),  # center it in the nice scrolly thing
)

# OK now we're ready to connect to the network, fetch data and update screen!
try:
    magtag.network.connect()
    value = magtag.fetch()
    print("Response is", value)
except (ValueError, RuntimeError, ConnectionError, OSError) as e:
    magtag.set_text(e)
    print("Some error occured, retrying later -", e)
# wait 2 seconds for display to complete
time.sleep(2)
magtag.exit_and_deep_sleep(TIME_BETWEEN_REFRESHES)

How It Works

Libraries

We import a few libraries to take care of the heavy lifting, in this case:

import time
from adafruit_magtag.magtag import MagTag

The time library allows us to do some pausing between steps.

The adafruit_magtag library makes it very simple to set up the MagTag's display, get online via WiFi, and to request and parse .json files.

Quote Variables

We'll set up some variables for the sources of our quote data.

DATA_SOURCE = "https://www.adafruit.com/api/quotes.php"
QUOTE_LOCATION = [0, "text"]
AUTHOR_LOCATION = [0, "author"]

Sleepy Time

The MagTag uses a deep sleep mode to conserve battery power between updates. We'll set the quotes to refresh every hour, which means we can get days of use on a single charge of a LiPo battery!

TIME_BETWEEN_REFRESHES = 1 * 60 * 60  # one hour delay

Setup

There are a number of setup steps we'll take next. First, we create the MagTag() object named magtag (all lower-case is easier to type anyway!).

Then we'll set the background graphic to the on-disk bitmap file.

magtag = MagTag(
    url=DATA_SOURCE,
    json_path=(QUOTE_LOCATION, AUTHOR_LOCATION),
)
magtag.graphics.set_background("/bmps/magtag_quotes_bg.bmp")

Text

Next up, we'll use the magtag library's text commands to create the two text objects, one for the quote and one for the author.

The magtag.add_text() command has arguments for the font, wrap width, maximum length of text glyphs, position, line spacing, and anchor point for the text.

magtag.add_text(
    text_font="/fonts/Arial-Bold-12.bdf",
    text_wrap=28,
    text_maxlen=120,
    text_position=(
        (magtag.graphics.display.width // 2),
        (magtag.graphics.display.height // 2) - 10,
    ),
    line_spacing=0.75,
    text_anchor_point=(0.5, 0.5),  # center the text on x & y
)

# author in italic text, no wrapping
magtag.add_text(
    text_font="/fonts/Arial-Italic-12.bdf",
    text_position=(magtag.graphics.display.width // 2, 118),
    text_anchor_point=(0.5, 0.5),  # center it in the nice scrolly thing
)

Connect

Next we'll get online, using the authentication details in the secrets.py file to connect to the network.

Then, we'll use the magtag.fetch() command which will go to the specified DATA_SOURCE url, grab the .json file, and parse it for the QUOTE_LOCATION text and AUTHOR_LOCATION text. (We include some error checking just in case. That's Internet!)

Once retrieved and parsed, the text is displayed on the MagTag.

Next, the MagTag takes an hour long nap, then wakes up to do it all over again. This then repeats until the end of time, keeping you happy with fresh quotes!

try:
    magtag.network.connect()
    value = magtag.fetch()
    print("Response is", value)
except (ValueError, RuntimeError) as e:
    magtag.set_text(e)
    print("Some error occured, retrying later -", e)
# wait 2 seconds for display to complete
time.sleep(2)
magtag.exit_and_deep_sleep(TIME_BETWEEN_REFRESHES)

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

This page (Code the MagTag Quotes Board) was last updated on Sep 22, 2023.

Text editor powered by tinymce.