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 MatrixPortal with having a variety of different panel sizes and other possible configurations, it made more sense 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, you will likely want at least one of the Graphics layers and optionally one of the Network layers.

Graphics Layers

For instance, if you wanted to only have the RGB Matrix automatically initialize, you could just use the matrix layer of the library. If you wanted additional graphics functions too such as easily drawing a background, you could use the graphics layer instead.

Network Layers

On the network functionality side of things, if you just wanted to initialize then you could use the WiFi layer, but if you wanted a lot of the network functions as well, you would use the network 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 matrixportal layer. This layer was intended to be similar to the PyPortal's single library, 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_matrixportal.matrixportal import MatrixPortal

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 matrixportal, then you would access the Network layer with and the Graphics layer with

matrixportal = MatrixPortal()
network =
graphics =


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

from import Graphics
from import Network

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

This guide was first published on Oct 20, 2020. It was last updated on Jun 25, 2024.

This page (Choosing Your Layers) was last updated on Mar 08, 2024.

Text editor powered by tinymce.