# Simplifying Qualia CircuitPython Projects
## Overview
The Qualia ESP32-S3 board is capable of driving RGB 666 dot clock displays, but the code to initialize them can be a bit long and most people don't want the first 50 to 100 lines of their code dedicated to just initializing the display. You can find more information about their usage in the [Adafruit Qualia ESP32-S3 for RGB-666 Displays guide](https://learn.adafruit.com/adafruit-qualia-esp32-s3-for-rgb666-displays).
The Qualia helper library removes a lot of the overhead work of getting the display up and running allowing you to concentrate on your project code instead of trying out a myriad of drivers, initialization codes, and timings just to get the display to show something.
It works by initializing the display as well as the appropriate touch driver if there is one for the display. The Qualia helper library is also built on top of the PortalBase library, which gives it many of the functions available to boards such as the PyPortal and MatrixPortal.
This guide will go over using the library as well as covering the examples included with the library.
## Parts
### Adafruit Qualia ESP32-S3 for TTL RGB-666 Displays
[Adafruit Qualia ESP32-S3 for TTL RGB-666 Displays](https://www.adafruit.com/product/5800)
There's a few things everyone loves: ice cream, kittens, and honkin' large TFT screens. We're no strangers to small TFT's - [from our itsy 1.14" color display](https://www.adafruit.com/search?q=1.14+tft) that graces many-a-TFT-Feather to
In Stock
[Buy Now](https://www.adafruit.com/product/5800)
[Related Guides to the Product](https://learn.adafruit.com/products/5800/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
Also compatible displays, under Featured Products or as listed under Qualia.
# Simplifying Qualia CircuitPython Projects
## Create Your settings.toml File
CircuitPython works with WiFi-capable boards to enable you to make projects that have network connectivity. This means working with various passwords and API keys. As of [CircuitPython 8](https://circuitpython.org/downloads), there is support for a **settings.toml** file. This is a file that is stored on your **CIRCUITPY** drive, that contains all of your secret network information, such as your SSID, SSID password and any API keys for IoT services. It is designed to separate your sensitive information from your **code.py** file so you are able to share your code without sharing your credentials.
CircuitPython previously used a **secrets.py** file for this purpose. The **settings.toml** file is quite similar.
Warning: Your **settings.toml** file should be stored in the main directory of your **CIRCUITPY** drive. It should not be in a folder.
## CircuitPython **settings.toml** File
This section will provide a couple of examples of what your **settings.toml** file should look like, specifically for CircuitPython WiFi projects in general.
The most minimal **settings.toml** file must contain your WiFi SSID and password, as that is the minimum required to connect to WiFi. Copy this example, paste it into your **settings.toml** , and update:
- `your_wifi_ssid`
- `your_wifi_password`
```auto
CIRCUITPY_WIFI_SSID = "your_wifi_ssid"
CIRCUITPY_WIFI_PASSWORD = "your_wifi_password"
```
Many CircuitPython network-connected projects on the Adafruit Learn System involve using Adafruit IO. For these projects, you must _also_ include your Adafruit IO username and key. Copy the following example, paste it into your settings.toml file, and update:
- `your_wifi_ssid`
- `your_wifi_password`
- `your_aio_username`
- `your_aio_key`
```auto
CIRCUITPY_WIFI_SSID = "your_wifi_ssid"
CIRCUITPY_WIFI_PASSWORD = "your_wifi_password"
ADAFRUIT_AIO_USERNAME = "your_aio_username"
ADAFRUIT_AIO_KEY = "your_aio_key"
```
Some projects use different variable names for the entries in the **settings.toml** file. For example, a project might use `ADAFRUIT_AIO_ID` in the place of `ADAFRUIT_AIO_USERNAME`. **If you run into connectivity issues, one of the first things to check is that the names in the settings.toml file match the names in the code.**
Warning: Not every project uses the same variable name for each entry in the **settings.toml** file! Always verify it matches the code.
## **settings.toml** File Tips
Here is an example **settings.toml** file.
```auto
# Comments are supported
CIRCUITPY_WIFI_SSID = "guest wifi"
CIRCUITPY_WIFI_PASSWORD = "guessable"
CIRCUITPY_WEB_API_PORT = 80
CIRCUITPY_WEB_API_PASSWORD = "passw0rd"
test_variable = "this is a test"
thumbs_up = "\U0001f44d"
```
In a **settings.toml** file, it's important to keep these factors in mind:
- Strings are wrapped in double quotes; ex: `"your-string-here"`
- Integers are _ **not** _ quoted and may be written in decimal with optional sign (`+1`, `-1`, `1000`) or hexadecimal (`0xabcd`).
- Floats (decimal numbers), octal (`0o567`) and binary (`0b11011`) are not supported.
- Use `\u` escapes for weird characters, `\x` and `\ooo` escapes are not available in **.toml** files
- Example: `\U0001f44d` for 👍 (thumbs up emoji) and `\u20ac` for € (EUR sign)
- Unicode emoji, and non-ASCII characters, stand for themselves as long as you're careful to save in "UTF-8 without BOM" format
When your **settings.toml ** file is ready, you can save it in your text editor with the **.toml** extension.
## Accessing Your **settings.toml** Information in **code.py**
In your **code.py** file, you'll need to `import` the `os` library to access the **settings.toml** file. Your settings are accessed with the `os.getenv()` function. You'll pass your settings entry to the function to import it into the **code.py** file.
```python
import os
print(os.getenv("test_variable"))
```
In the upcoming CircuitPython WiFi examples, you'll see how the **settings.toml ** file is used for connecting to your SSID and accessing your API keys.
# Simplifying Qualia CircuitPython Projects
## Usage
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
```python
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:
```python
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.
```python
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:
```python
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.
```python
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.
# Simplifying Qualia CircuitPython Projects
## Code Examples
Here is the code from one of the examples that are included with the library. To run the examples, simply rename them as **code.py** and place them in the root of your **CIRCUITPY** drive.
## Simple Test
This example was written to use the square 3.4" display, but should be able to work with any of the displays. It uses the top level **Qualia** layer and makes use of the graphics and network. It connects to your WiFi, downloads some test data and displays the data in the REPL.
https://github.com/adafruit/Adafruit_CircuitPython_Qualia/blob/main/examples/qualia_simpletest.py
## Quotes Example
The quotes example is more like how the PyPortal works in that a data source is defined, two text fields are created, and the quote and author data are displayed. This example was also written for the square 3.4" display, but could be modified to run on other displays by adjusting the text field settings such as `text_wrap`.
https://github.com/adafruit/Adafruit_CircuitPython_Qualia/blob/main/examples/qualia_quotes.py
## QR Code Example
The QR Code Generation example generates a QR code and displays it in the center of the display. This example was written for the round 2.1" display, but could easily be adapted for the other displays.
https://github.com/adafruit/Adafruit_CircuitPython_Qualia/blob/main/examples/qualia_qrcode_generation.py
## Paint Example
This last example is the most complex one and will run on any of the displays with a touchscreen. This was adapted from [an example included in the FocalTouch library](https://github.com/adafruit/Adafruit_CircuitPython_FocalTouch/blob/main/examples/focaltouch_paint_rgb666.py) and ends up being around 30 lines less, but supporting many more displays. This example only uses the Graphics layer and shows how to make use of the touch screen.
https://github.com/adafruit/Adafruit_CircuitPython_Qualia/blob/main/examples/qualia_paint.py
# Simplifying Qualia CircuitPython Projects
## Qualia Library Documentation
# Simplifying Qualia CircuitPython Projects
## PortalBase Library Documentation
## Featured Products
### Adafruit Qualia ESP32-S3 for TTL RGB-666 Displays
[Adafruit Qualia ESP32-S3 for TTL RGB-666 Displays](https://www.adafruit.com/product/5800)
There's a few things everyone loves: ice cream, kittens, and honkin' large TFT screens. We're no strangers to small TFT's - [from our itsy 1.14" color display](https://www.adafruit.com/search?q=1.14+tft) that graces many-a-TFT-Feather to
In Stock
[Buy Now](https://www.adafruit.com/product/5800)
[Related Guides to the Product](https://learn.adafruit.com/products/5800/guides)
### Round RGB 666 TTL TFT Display - 2.1" 480x480 - Capacitive Touch
[Round RGB 666 TTL TFT Display - 2.1" 480x480 - Capacitive Touch](https://www.adafruit.com/product/5792)
This is a screen for advanced hackers who like the look of a nice, round TFT screen with tons of pixels. The 2.1" diagonal sized display has 480x480 16-bit full-color pixels and is an **IPS** display, so the color looks great up to 80 degrees off-axis in any...
In Stock
[Buy Now](https://www.adafruit.com/product/5792)
[Related Guides to the Product](https://learn.adafruit.com/products/5792/guides)
### Round RGB TTL TFT Display - 2.1" 480x480 - No Touchscreen
[Round RGB TTL TFT Display - 2.1" 480x480 - No Touchscreen](https://www.adafruit.com/product/5806)
This is a screen for advanced hackers who like the look of a nice, round TFT screen with tons of pixels. The 2.1" diagonal-sized display has 480x480 16-bit full-color pixels and is an **IPS** display, so the color looks great up to 80 degrees off-axis in any...
In Stock
[Buy Now](https://www.adafruit.com/product/5806)
[Related Guides to the Product](https://learn.adafruit.com/products/5806/guides)
### Round RGB TTL TFT Display - 4" 720x720 - No Touchscreen
[Round RGB TTL TFT Display - 4" 720x720 - No Touchscreen](https://www.adafruit.com/product/5793)
This is a screen for advanced hackers who like the look of a nice, round TFT screen with tons of pixels. This massive 4" diagonal-sized display has 720x720 16-bit full-color pixels and is an **IPS** display, so the color looks great up to 80 degrees off-axis in...
In Stock
[Buy Now](https://www.adafruit.com/product/5793)
[Related Guides to the Product](https://learn.adafruit.com/products/5793/guides)
### Square RGB 666 TTL TFT Display - 3.4" 480x480 with Touchscreen
[Square RGB 666 TTL TFT Display - 3.4" 480x480 with Touchscreen](https://www.adafruit.com/product/5808)
This is a screen for advanced hackers who like the look of a square TFT screen with tons of pixels. The 3.4" square display has 480x48018-bit full-color pixels and is an **IPS** display, so the color looks great up to 80 degrees off-axis in any...
In Stock
[Buy Now](https://www.adafruit.com/product/5808)
[Related Guides to the Product](https://learn.adafruit.com/products/5808/guides)
### Square RGB TTL TFT Display - 3.4" 480x480 No Touchscreen
[Square RGB TTL TFT Display - 3.4" 480x480 No Touchscreen](https://www.adafruit.com/product/5825)
This is a screen for advanced hackers who like the look of a square TFT screen with tons of pixels. The 3.4" square display has 480x48016-bit full-color pixels and is an **IPS** display, so the color looks great up to 80 degrees off-axis in any...
In Stock
[Buy Now](https://www.adafruit.com/product/5825)
[Related Guides to the Product](https://learn.adafruit.com/products/5825/guides)
### Square RGB TTL TFT Display - 4" 720x720 - with Capacitive Touch
[Square RGB TTL TFT Display - 4" 720x720 - with Capacitive Touch](https://www.adafruit.com/product/5794)
This is a screen for advanced hackers who like the look of a big rectangular TFT screen with tons of pixels and a capacitive touchscreen overlay. The 4" display has 720x720 16-bit full-color pixels and is an **IPS** display, so the color looks great up to 80...
In Stock
[Buy Now](https://www.adafruit.com/product/5794)
[Related Guides to the Product](https://learn.adafruit.com/products/5794/guides)
### Square RGB 666 TTL TFT Display - 4" 720x720 - No Touchscreen
[Square RGB 666 TTL TFT Display - 4" 720x720 - No Touchscreen](https://www.adafruit.com/product/5795)
This is a screen for advanced hackers who like the look of a big rectangular TFT screen with tons of pixels. The 4" display has 720x720 16-bit full-color pixels and is an **IPS** display, so the color looks great up to 80 degrees off-axis in any...
In Stock
[Buy Now](https://www.adafruit.com/product/5795)
[Related Guides to the Product](https://learn.adafruit.com/products/5795/guides)
## Related Guides
- [Adafruit Qualia ESP32-S3 for RGB-666 Displays](https://learn.adafruit.com/adafruit-qualia-esp32-s3-for-rgb666-displays.md)
- [Qualia S3 Compass](https://learn.adafruit.com/qualia-s3-compass.md)
- [Qualia S3 iOS Photo Display with itsaSNAP](https://learn.adafruit.com/qualia-s3-ios-photo-display-with-itsasnap.md)
- [Qualia 3D Printed Cases](https://learn.adafruit.com/qualia-3d-printed-cases.md)
- [Qualia S3 Sushi Conveyor Belt](https://learn.adafruit.com/qualia-s3-sushi-conveyor-belt.md)
- [CircuitPython Day 2024 Countdown Clock](https://learn.adafruit.com/circuitpython-day-2024-countdown-clock.md)
- [Qualia S3 Fireplace](https://learn.adafruit.com/qualia-s3-fireplace.md)
- [Theme Park Wait Time Display](https://learn.adafruit.com/park-wait-time.md)
- [Video Playing 2.1" Round Ornament TFT](https://learn.adafruit.com/2-1-round-ornament-tft.md)
- [Qualia S3 Space Clock](https://learn.adafruit.com/qualia-s3-space-clock.md)
- [1D Chomper Tabletop Arcade Game](https://learn.adafruit.com/1d-chomper-tabletop-arcade-game.md)
- [Adafruit QMC5883P - Triple Axis Magnetometer](https://learn.adafruit.com/adafruit-qmc5883p-triple-axis-magnetometer.md)
- [Soundbox RP2040](https://learn.adafruit.com/soundbox-rp2040.md)
- [CircuitPython NeoPixel Library Using SPI](https://learn.adafruit.com/circuitpython-neopixels-using-spi.md)
- [CircuitPython 101: State Machines, Two Ways](https://learn.adafruit.com/circuitpython-101-state-machines.md)