So you may have heard of the Adafruit MagTag and you want to get started with building a project using CircuitPython. As the name implies, the MagTag was designed to be a low-powered "tag" that you could attach to your refrigerator with magnetic feet. The MagTag library makes it really easy to get started with creating a new project, using this board, but it also supports a variety of other hardware pieces to make creating projects to display on the ePaper display very easy.

This library is built on top of the PortalBase library, which in turn is built on top of displayio which is included as part of CircuitPython. It also makes use of the ESP32-S2 wifi module, along with some lower-level dependencies, to communicate with server over the internet.

One of the latest features of CircuitPython, which is made easy with this library, is the ability to put the MagTag into deep sleep, which is a very low power mode. We will go over that plus more in this guide.

Parts

The MagTag library was built upon the MatrixPortal library, but was designed around the ePaper display, low power usage, and the new ESP32-S2. While it started as a standalone library, it was designed with the intention of splitting the library up into a base library and the main library which piggyback's on top of the base library. The base library was named PortalBase which is split up into 3 components. The main base, the GraphicsBase, and the NetworkBase. In the diagram, you can see these components represented in blue.

FakeRequests became its own library, so that is now part of the Lower Level Dependencies in the hierarchy diagram.

Here is the way it is logically laid out with dependencies. The MagTag library is comprised of the top layer, the Peripherals, Network, and Graphics layers, and the WiFi layer in the diagram.

There are three main branches of dependencies related to Network Functionality, Graphics functionality, and Peripherals. The MagTag library ties them both together and allows easier coding, but at the cost of more memory usage and less control. We'll go through each of the classes starting from the bottom and working our way up the diagram starting with the Network branch.

Network Branch

The network branch contains all of the functionality related to connecting to the internet and retrieving data. You will want to use this branch if your project need to retrieve any data that is not stored on the device itself.

WiFi Module

The WiFi module is responsible for initializing the hardware libraries and controlling the status NeoPixel colors. The main purpose of this library is to abstract away from the specific WiFi implementation so that PortalBase can be used both with boards with an external WiFi controller and boards with a built-in controller. This layer really wasn't intended to be used directly, but you would want to use this library if you only wanted to handle the automatic initialization of hardware and connection to WiFi and didn't need any other functionality.

Network Module

The network module has many convenience functions for making network calls. It handles a lot of things from automatically establishing the connection to getting the time from the internet, to getting data at certain URLs. This is one of the largest of the modules as there is a lot of functionality packed into this. This is built on top of NetworkBase and initializes the WiFi module and anything else specific to the MagTag device.

Graphics Branch

This branch is a lot lighter than the Network Branch because so much of the functionality is built into CircuitPython and displayio.

Graphics Module

Most of the functionality is part of GraphicsBase. This module contains some convenience functions such as setting the background to a color or image and displaying a QR code. The portion of the Graphics that is part of the MagTag library includes some graphics functionality specific to the eInk display. 

Peripherals Branch

This branch is kind of a catch-all of specific board hardware. For the MagTag library, this includes the onboard NeoPixels, buttons, and audio. This library automatically initializes the hardware to make it easier to use it in your scripts. For audio, it will enable and disable the speaker automatically when you play tones. We decided not to automatically disable the NeoPixels so that you could have all the functionality of the NeoPixel library and be able to set the colors differently or even have some of them off.

MagTag Module

The MagTag module is top level module and will handle initializing everything below it. Using this module is very similar to using the MatrixPortal library. The main differences are the peripherals library is new and the display should be refreshed as needed.

Another new feature is the use of the low power modes. By placing the board into deep sleep, the script will exit and a timer will be set so that it restarts the script when it wakes up. For light sleep, it uses a bit more power, but it will resume in the middle of the script. This allows the board to go a long time between charges.

Choosing your layers is one of the more important parts of creating a project since it's easy to accidentally choose layers that end up duplicating some of the functions. This guide is intended to help clarify your understanding of the layout so you can make the best choices for your needs.

The PyPortal library, which is what inspired this library was written as a single layer which had the advantage of making it really simple to use for a certain type of project and it worked well for the PyPortal because the hardware setup varies very little between the different models. For the MagTag Library, like the similar Matrix Portal library, we decided to break everything up into layers.

Mixing and Matching Layers

Which of the layers you choose to use for your project depends on the amount of customization and memory management you would like in your project. The higher level up you go in the library layer hierarchy, the more automatic functions you will have available to you, but it also takes away your ability to customize things and uses more memory.

In general, at a minimum, you will likely want at least the Graphics layers and optionally either the Network or Peripheral layers. However, by using the top level layer, you will have access to everything.

Graphics Layers

You can use the graphics layer if you wanted to have some convenient graphics functions, such as easily drawing a background or displaying a QR code.

Network Layers

On the network functionality side of things, if you just wanted to initialize the network, you could use the WiFi layer, but if you wanted more of the network functions as well, you would use the network layer.

Peripherals Layer

To use the peripheral functionality, if you just wanted to initialize the buttons, NeoPixels, and audio, then you could use the Peripherals layer.

Top Layer

If you wanted everything along with some great functionality that ties both legs of the hierarchy together or you were porting a project from the PyPortal library, then you would want the very top layer, which is the MagTag layer. This layer was intended to be similar to the PyPortal's single library or the MatrixPortal's top layer, but with some notable differences, which we'll cover in this guide.

Remember that if you go with this layer, you should not need to also import any of the lower layers.

Importing your layers

Top Layer

To import the top level layer only, you would simply just import it like this:

from adafruit_magtag.magtag import MagTag

1

from adafruit_magtag.magtag import MagTag

If you would like access to the Network and Graphics layers, they are available as objects named network and graphics. For instance, if you instantiated the top layer as magtag, then you would access the Network layer with magtag.network, the Graphics layer with magtag.graphics, and the Peripherals layer with magtag.peripherals.

magtag = MagTag()
network = magtag.network
graphics = magtag.graphics
peripherals = magtag.peripherals

1
2
3
4

magtag = MagTag()
network = magtag.network
graphics = magtag.graphics
peripherals = magtag.peripherals

Sub-Layers

To only import sub-layers such as the Graphics, Network, and Peripherals layers, you would import it like this:

from adafruit_magtag.graphics import Graphics
from adafruit_magtag.network import Network
from adafruit_magtag.peripherals import Peripherals

1
2
3

from adafruit_magtag.graphics import Graphics
from adafruit_magtag.network import Network
from adafruit_magtag.peripherals import Peripherals

After they're imported, you would just instantiate each of the classes separately.

Here is the code from one of the examples that are included with the library. To run the examples, simply rename them as code.py and place them in the root of your CIRCUITPY drive.

Simple Test

This example uses of the top level MagTag layer and makes use of the graphics and peripherals. The code starts out with a couple imports.

import time
from adafruit_magtag.magtag import MagTag

1
2

import time
from adafruit_magtag.magtag import MagTag

After that, the MagTag library is initialized with no parameters. A NeoPixel could have been supplied for status, but then there would be one less NeoPixel available for programmatic use.

magtag = MagTag()

1

magtag = MagTag()

Next a text label is created with a scale of 3, with the left edge 50 pixels in and centered vertically and it's text is set to Hello World.

magtag.add_text(
    text_position=(
        50,
        (magtag.graphics.display.height // 2) - 1,
    ),
    text_scale=3,
)

magtag.set_text("Hello World")

1
2
3
4
5
6
7
8
9

magtag.add_text(
    text_position=(
        50,
        (magtag.graphics.display.height // 2) - 1,
    ),
    text_scale=3,
)

magtag.set_text("Hello World")

The button colors and tones are set here and are easy to change.

button_colors = ((255, 0, 0), (255, 150, 0), (0, 255, 255), (180, 0, 255))
button_tones = (1047, 1318, 1568, 2093)

1
2

button_colors = ((255, 0, 0), (255, 150, 0), (0, 255, 255), (180, 0, 255))
button_tones = (1047, 1318, 1568, 2093)

Finally this leads to the main loop. Inside the main loop it will check if each of the buttons has been pressed. If it has, it will print a message about which button, light up the corresponding NeoPixel and then break, which causes it to skip the code inside the else portion of the for loop. After that it will sleep for 0.01 seconds and then repeat.

while True:
    for i, b in enumerate(magtag.peripherals.buttons):
        if not b.value:
            print("Button %c pressed" % chr((ord("A") + i)))
            magtag.peripherals.neopixel_disable = False
            magtag.peripherals.neopixels.fill(button_colors[i])
            magtag.peripherals.play_tone(button_tones[i], 0.25)
            break
    else:
        magtag.peripherals.neopixel_disable = True
    time.sleep(0.01)

1
2
3
4
5
6
7
8
9
10
11

while True:
    for i, b in enumerate(magtag.peripherals.buttons):
        if not b.value:
            print("Button %c pressed" % chr((ord("A") + i)))
            magtag.peripherals.neopixel_disable = False
            magtag.peripherals.neopixels.fill(button_colors[i])
            magtag.peripherals.play_tone(button_tones[i], 0.25)
            break
    else:
        magtag.peripherals.neopixel_disable = True
    time.sleep(0.01)

After running the code, when you press the buttons, the NeoPixels should light up and each play a different tone.

Full Example Code

# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
import time

from adafruit_magtag.magtag import MagTag

magtag = MagTag()

magtag.add_text(
    text_position=(
        50,
        (magtag.graphics.display.height // 2) - 1,
    ),
    text_scale=3,
)

magtag.set_text("Hello World")

button_colors = ((255, 0, 0), (255, 150, 0), (0, 255, 255), (180, 0, 255))
button_tones = (1047, 1318, 1568, 2093)

while True:
    for i, b in enumerate(magtag.peripherals.buttons):
        if not b.value:
            print(f"Button {chr(ord('A') + i)} pressed")
            magtag.peripherals.neopixel_disable = False
            magtag.peripherals.neopixels.fill(button_colors[i])
            magtag.peripherals.play_tone(button_tones[i], 0.25)
            break
    else:
        magtag.peripherals.neopixel_disable = True
    time.sleep(0.01)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
import time

from adafruit_magtag.magtag import MagTag

magtag = MagTag()

magtag.add_text(
    text_position=(
        50,
        (magtag.graphics.display.height // 2) - 1,
    ),
    text_scale=3,
)

magtag.set_text("Hello World")

button_colors = ((255, 0, 0), (255, 150, 0), (0, 255, 255), (180, 0, 255))
button_tones = (1047, 1318, 1568, 2093)

while True:
    for i, b in enumerate(magtag.peripherals.buttons):
        if not b.value:
            print(f"Button {chr(ord('A') + i)} pressed")
            magtag.peripherals.neopixel_disable = False
            magtag.peripherals.neopixels.fill(button_colors[i])
            magtag.peripherals.play_tone(button_tones[i], 0.25)
            break
    else:
        magtag.peripherals.neopixel_disable = True
    time.sleep(0.01)

Quotes Example

This example is a barebones stripped down version of the MagTag Showerthoughts and Quotes example that just gets the value, displays it, and then makes use of the deep sleep feature. This example also uses the MagTag top layer, but makes use of the graphics and network, but not the peripherals.

The code starts out with a couple imports:

import os
from adafruit_magtag.magtag import MagTag

1
2

import os
from adafruit_magtag.magtag import MagTag

Then it defines where to grab the value from and the path to find the result in the JSON response.

# 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"]

1
2
3
4

# 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"]

Next the MagTag library is initialized at the top level. The Data URL, Data Location within the returned JSON, and Default Background are set here. The json_path has a tuple of 2 values because we are fetching 2 pieces of data.

magtag = MagTag(
    url=DATA_SOURCE,
    json_path=(QUOTE_LOCATION, AUTHOR_LOCATION),
    default_bg=0x000000,
)

1
2
3
4
5

magtag = MagTag(
    url=DATA_SOURCE,
    json_path=(QUOTE_LOCATION, AUTHOR_LOCATION),
    default_bg=0x000000,
)

Next we define a couple of text transform function. A text transform works by modifying a single parameter and returning the new value.

def add_quote_marks(quote_text):
    return f'"{quote_text}"'


def add_hyphen(author_name):
    return f"- {author_name}"

1
2
3
4
5
6

def add_quote_marks(quote_text):
    return f'"{quote_text}"'


def add_hyphen(author_name):
    return f"- {author_name}"

Next we add a couple of text fields. The order they are added should match the order of the items in the json_path parameter we used when initializing the MagTag library.

magtag.add_text(
    text_position=(
        (magtag.graphics.display.width // 2) - 1,
        (magtag.graphics.display.height // 2) - 20,
    ),
    text_color=0xFFFFFF,
    text_wrap=44,
    text_maxlen=180,
    line_spacing=1.0,
    text_transform=add_quote_marks,
    text_anchor_point=(0.5, 0.5),
)

magtag.add_text(
    text_position=(
        (magtag.graphics.display.width // 2) - 120,
        (magtag.graphics.display.height // 2) + 34,
    ),
    text_color=0xFFFFFF,
    text_wrap=0,
    text_maxlen=30,
    text_transform=add_hyphen,
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

magtag.add_text(
    text_position=(
        (magtag.graphics.display.width // 2) - 1,
        (magtag.graphics.display.height // 2) - 20,
    ),
    text_color=0xFFFFFF,
    text_wrap=44,
    text_maxlen=180,
    line_spacing=1.0,
    text_transform=add_quote_marks,
    text_anchor_point=(0.5, 0.5),
)

magtag.add_text(
    text_position=(
        (magtag.graphics.display.width // 2) - 120,
        (magtag.graphics.display.height // 2) + 34,
    ),
    text_color=0xFFFFFF,
    text_wrap=0,
    text_maxlen=30,
    text_transform=add_hyphen,
)

Next we fetch the data and the text fields are automatically filled in. That is why the order they are added must match the order of the data locations.

try:
    value = magtag.fetch()
    print("Response is", value)
except (ValueError, RuntimeError) as e:
    print("Some error occured, retrying! -", e)

1
2
3
4
5

try:
    value = magtag.fetch()
    print("Response is", value)
except (ValueError, RuntimeError) as e:
    print("Some error occured, retrying! -", e)

Finally, the MagTag is put into deep sleep for 60 seconds. When it wakes up, the script starts from the beginning.

magtag.exit_and_deep_sleep(60)

1

magtag.exit_and_deep_sleep(60)

After running the code, it should connect to your WiFi and download and display a quote.

Full Example Code

# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
import os

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

# the current working directory (where this file is)
try:
    cwd = os.path.dirname(os.path.realpath(__file__))
except AttributeError:
    cwd = ("/" + __file__).rsplit("/", 1)[0]

magtag = MagTag(
    url=DATA_SOURCE,
    json_path=(QUOTE_LOCATION, AUTHOR_LOCATION),
    default_bg=0x000000,
)


def add_quote_marks(quote_text):
    return f'"{quote_text}"'


def add_hyphen(author_name):
    return f"- {author_name}"


magtag.add_text(
    text_position=(
        (magtag.graphics.display.width // 2) - 1,
        (magtag.graphics.display.height // 2) - 20,
    ),
    text_color=0xFFFFFF,
    text_wrap=44,
    text_maxlen=180,
    line_spacing=1.0,
    text_transform=add_quote_marks,
    text_anchor_point=(0.5, 0.5),
)

magtag.add_text(
    text_position=(
        (magtag.graphics.display.width // 2) - 120,
        (magtag.graphics.display.height // 2) + 34,
    ),
    text_color=0xFFFFFF,
    text_wrap=0,
    text_maxlen=30,
    text_transform=add_hyphen,
)

try:
    value = magtag.fetch()
    print("Response is", value)
except (ValueError, RuntimeError) as e:
    print("Some error occured, retrying! -", e)
magtag.exit_and_deep_sleep(60)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
#
# SPDX-License-Identifier: Unlicense
import os

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

# the current working directory (where this file is)
try:
    cwd = os.path.dirname(os.path.realpath(__file__))
except AttributeError:
    cwd = ("/" + __file__).rsplit("/", 1)[0]

magtag = MagTag(
    url=DATA_SOURCE,
    json_path=(QUOTE_LOCATION, AUTHOR_LOCATION),
    default_bg=0x000000,
)


def add_quote_marks(quote_text):
    return f'"{quote_text}"'


def add_hyphen(author_name):
    return f"- {author_name}"


magtag.add_text(
    text_position=(
        (magtag.graphics.display.width // 2) - 1,
        (magtag.graphics.display.height // 2) - 20,
    ),
    text_color=0xFFFFFF,
    text_wrap=44,
    text_maxlen=180,
    line_spacing=1.0,
    text_transform=add_quote_marks,
    text_anchor_point=(0.5, 0.5),
)

magtag.add_text(
    text_position=(
        (magtag.graphics.display.width // 2) - 120,
        (magtag.graphics.display.height // 2) + 34,
    ),
    text_color=0xFFFFFF,
    text_wrap=0,
    text_maxlen=30,
    text_transform=add_hyphen,
)

try:
    value = magtag.fetch()
    print("Response is", value)
except (ValueError, RuntimeError) as e:
    print("Some error occured, retrying! -", e)
magtag.exit_and_deep_sleep(60)