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

Installing the 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 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 file in a zip file. Extract the contents of the zip file, open the directory MagTag_Project_Selector/ 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 contain the following files and directories:

# 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)
    display.root_group = group

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

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

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.

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 Jul 20, 2024.

This page (Code the MagTag Project Selector) was last updated on Jul 20, 2024.

Text editor powered by tinymce.