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

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

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

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.