Installing the Project Code

Download a zip of the project by clicking 'Download: Project Zip' below.

After unzipping the file, copy its contents to the CIRCUITPY drive which appears when the MagTag is connected to your computer via a USB cable and turned on via a small on/off switch onboard.

The files for this project just barely fit on the MagTag. To make sure you have enough space, you'll have to clear the MagTag filesystem which requires you to enter the REPL over a serial console. To do that, read through the three pages linked below.

Now that you have done that, enter the following two lines and it will erase all the files on your MagTag.

import storage

At this point, I would recommend going through the other guides that this project makes use of, which are linked below. For most of the projects, you can copy all of their contents to the CIRCUITPY drive. However, for the MagTag Progress Displays guide, only the epilogue18.bdf font and should be copied over.

All the .py files for the individual projects need to be put in a new directory on the CIRCUITPY drive named projects/ and renamed

Here is a list of all the libraries required, since it's a lot easier to just copy them all over at once:

  • adafruit_bitmap_font
  • adafruit_display_shapes
  • adafruit_display_text
  • adafruit_imageload
  • adafruit_io
  • adafruit_magtag
  • adafruit_portalbase
  • adafruit_fakerequests
  • adafruit_miniqr
  • adafruit_progressbar
  • adafruit_requests
  • adafruit_slideshow
  • neopixel
  • simpleio

As far as the file goes, one with all the necessary fields has been included in the project zip that you can just fill out as you go through each guide.

After you've copied everything over, this is what the CIRCUITPY drive should look like (you can click on each image to expand it since the text might be small on some screens).

# SPDX-FileCopyrightText: 2020 Eva Herrada for Adafruit Industries
# SPDX-License-Identifier: MIT

# Based on code written by @DavidGlaude on Twitter

import time
import alarm
import displayio
import board
import adafruit_imageload
from adafruit_display_shapes.rect import Rect
from adafruit_magtag.magtag import Graphics
from digitalio import DigitalInOut, Direction, Pull

projects = [

btnA = DigitalInOut(board.D15)
btnA.direction = Direction.INPUT
btnA.pull = Pull.UP

btnB = DigitalInOut(board.D14)
btnB.direction = Direction.INPUT
btnB.pull = Pull.UP

btnC = DigitalInOut(board.D12)
btnC.direction = Direction.INPUT
btnC.pull = Pull.UP

btnD = DigitalInOut(board.D11)
btnD.direction = Direction.INPUT
btnD.pull = Pull.UP

graphics = Graphics(auto_refresh=False)
display = graphics.display
group = displayio.Group()

selector = False
if not btnA.value or not btnB.value or not btnC.value or not btnD.value:
    selector = True

if selector:
    background = Rect(0, 0, 296, 128, fill=0xFFFFFF)
    for i in range(8):
        sprite_sheet, palette = adafruit_imageload.load(
        sprite = displayio.TileGrid(
            x=6 + 74 * (i % 4),
            y=6 + 62 * (i // 4),

    rect = Rect(4, 4, 66, 58, outline=0x000000, stroke=2)

    selected = 0
    while True:
        if not btnA.value and not btnD.value:
            alarm.sleep_memory[0] = selected

        if not btnA.value and selected != 0 and selected != 4:
            selected -= 1
            rect.x -= 74

        if not btnB.value and selected > 3:
            selected -= 4
            rect.y -= 62

        if not btnC.value and selected < 4:
            selected += 4
            rect.y += 62

        if not btnD.value and selected != 3 and selected != 7:
            selected += 1
            rect.x += 74


print("Starting ", projects[int(alarm.sleep_memory[0])])
__import__("/projects/" + projects[int(alarm.sleep_memory[0])])
Be sure you have the libraries and file complete and loaded onto the CIRCUITPY drive also or the code will not run properly.

Code Behavior

So, now that everything's all set up, it'd probably be a good idea to actually know how to use it. Basically, when the MagTag restarts or resets (from the slide switch, reset button, or through the serial terminal), you've got the option of going into a simple UI that will let you choose a project to load. You can enter this UI by pressing any of the four buttons when the MagTag is reloading and holding it down until the screen shows eight boxes with little pictures inside them. 

Once you're in the UI, use the four buttons to navigate it. Each button has an arrow on it, and pressing that button will move the cursor one square in that direction. Once the cursor (a black outline on the selected picture) is on the project you want, press and hold both the first and last buttons for five seconds. The MagTag can only update the screen once every five seconds, so keep that in mind while navigating the UI.

If you don't press a button when the code is restarting, it will automatically run the last run project. However, due to the constraints of the alarm library used to accomplish this, it only works during a soft reset (i.e. through the REPL or automatically) and not when the RESET button is pressed or the slide switch is turned off and on. If there isn't one, it will choose the first project and run that one.

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

This page (Code the MagTag Project Selector) was last updated on Jun 29, 2022.

Text editor powered by tinymce.