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.

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

This page (MagTag Library Overview) was last updated on Mar 08, 2024.

Text editor powered by tinymce.