Choosing your layers is an important part of creating a project with regards to the Portal-style libraries 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. As more boards were written in the this style of library, a base library called PortalBase was created to make it easier to maintain multiple libraries. The libraries were originally broken up into layers to allow for loading only the parts that were needed for a project with the advantage of saving memory when there wasn't much to spare.

For the Qualia ESP32-S3, there is plenty of PSRAM available, so you could just load the topmost layer. However, with continuing the tradition of layers and the fact that some of the huge displays can take up a good chunk of the RAM, not loading more than needed is still a good approach.

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. If you plan on using the peripherals specific to the board such as the buttons, you will want the peripherals layer as well.

Graphics Layers

For the Qualia library having multiple possible displays, a slightly different approach was taken with writing Graphics layers. There is a folder of displays that contain both the DotClockDisplay base class and the display-specific classes.

There is also a Displays class, which can be found alongside the Graphics class that was written for the purpose of finding all of the display-specific classes and loading the filename as an attribute in all uppercase. This class has only static functions because it is meant to be used without instantiating it first.

This makes it easy to add new displays to the library since everything is just kept in one place.

Network Layers

On the network functionality side of things, you will want to include the Network layer, which includes some convenient functions such as fetch for data and wget for downloading files. With plenty of RAM, the Qualia should be able to handle most downloads.

Peripherals Layer

To use the peripheral functionality, if you just wanted to initialize the buttons or control the display's backlight, then you would want to use the Peripherals layer. Compared to some of the other Portal-style boards, the Qualia ESP32-S3 has very few peripherals.

Top Layer

If you wanted everything along with some great functionality that ties all the legs of the hierarchy together then you would want the very top layer, which is the Qualia layer. This layer is the all-inclusive layer. To access the lower layers, you can use the following attributes:

• peripherals - The Peripherals Layer
• graphics - The Graphics Layer
• network - The Network Layer
• display - The FrameBufferDisplay layer
• graphics.dotclockdisplay - The DotClockDisplay layer

Remember that if you go with this layer, you should not import any of the lower layers with the exception of the Displays layer.

Importing your layers

Displays Layer

This layer is special since it will automatically enumerate the displays upon import and you will need it in order to instantiate the Top or Graphics layers

from adafruit_qualia.graphics import Displays

from adafruit_qualia.graphics import Displays

To refer to a specific display, you would refer to it starting with Displays.  followed by the filename in all capital letters without the .py at the end. For example:

• Displays.ROUND21 - Round 2.1" Display
• Displays.SQUARE34- Square 3.4" Display
• Displays.BAR320X820 - 320x820 Bar Display

These are only a few of the supported displays. Check the displays folder for a complete list of available displays. It doesn't matter whether your display has touch or not as it will attempt to initialize the appropriate touch driver, but if the chip isn't found, it will still load.

Alternatively, you could just use a string with the filename in all lowercase without the .py extension. For example "round21".

Top Layer

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

from adafruit_qualia import Qualia

from adafruit_qualia import Qualia

If you would like access to the lower layers, you can directly access them as attributes. For instance, if you instantiated the top layer as qualia, then you could access the layers.

qualia = Qualia(DISPLAY)
network = qualia.network
graphics = qualia.graphics
peripherals = qualia.peripherals

qualia = Qualia(DISPLAY)
network = qualia.network
graphics = qualia.graphics
peripherals = qualia.peripherals

Replace with DISPLAY with the display you have connected such as Displays.ROUND21. See the Displays Layer for more information.

If you would prefer, you don't even need to assign them to variable and can just directly access the attributes when needed.

Sub-Layers

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

from adafruit_qualia.graphics import Graphics
from adafruit_qualia.network import Network

from adafruit_qualia.graphics import Graphics
from adafruit_qualia.network import Network

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

graphics = Graphics(DISPLAY)
network = Network()

graphics = Graphics(DISPLAY)
network = Network()

Replace with DISPLAY with the display you have connected such as Displays.ROUND21. See the Displays Layer for more information.