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

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, the Graphics layer with, and the Peripherals layer with magtag.peripherals.

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


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

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

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

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

This page (Choosing Your Layers) was last updated on Dec 14, 2020.

Text editor powered by tinymce.