gc9a01_mpy MicroPython Driver

The driver supports two types of fonts: fixed-size Bitmap fonts and TrueType fonts. Choose between them based on your rendering needs and memory constraints.

To use the Waveshare ESP32-S3-LCD-1.28 display, use the pre-defined configuration files located in tft_configs/ESP32-S3-LCD-1.28/.

Hardware Details:

• Device: Waveshare ESP32-S3-LCD-1.28
• Required Firmware: ESP32_GENERIC/firmware_16MiB.bin

Configuration Files:

• tft_config.py: Contains the display driver initialization parameters (pins, SPI settings, etc.).
• tft_buttons.py: Contains the button mapping/configuration for this specific board.

Use the text_font_converter.py utility (found in the utils directory) to convert PC BIOS bitmap fonts from the romfont repository into Python font modules.

Options:

• -i, --input-directory: The directory containing the source .bin files.
• -o, --output-directory: The directory where the converted Python font files will be written.
• -f, --first-char: Limit the character set by specifying the first character.
• -l, --last-char: Limit the character set by specifying the last character.

text_font_converter.py -i font-bin -o fonts -f 32 -l 127

Touch button configurations for the RP2040-Touch-LCD-1.28 are defined in tft_configs/RP2040-Touch-LCD-1.28/tft_buttons.py. Use this file to define the touch areas and interaction logic for this specific display.

# Refer to tft_configs/RP2040-Touch-LCD-1.28/tft_buttons.py for implementation

Once you have generated a .py bitmap module, you should cross-compile it to a .mpy file for efficient use on the microcontroller, then upload it to the board using mpremote.

Follow these steps:

1. Cross-compile the module using mpy-cross.
2. Upload the resulting .mpy file to the board's root directory using mpremote cp.

# cross compile the python module
mpy-cross cat_bitmap.py

# upload the compiled module to the board
mpremote cp cat_bitmap.mpy :

The library supports bit mapped fonts for use with the Text method. These fonts are categorized into 128-character and 256-character sets.

Frozen Fonts (Included in firmware): These fonts are pre-compiled and available directly from ROM, requiring no extra file management on your filesystem:

• vga1_8x8.py
• vga1_16x16.py
• vga1_16x32.py
• vga1_bold_16x16.py
• vga1_bold_16x32.py

Non-Frozen Fonts (External files): These fonts are not included in the firmware and must be provided on your filesystem:

• vga2_8x8.py
• vga2_8x16.py
• vga2_16x16.py
• vga2_16x32.py
• vga2_bold_16x16.py
• vga2_bold_16x32.py

The repository provides pre-compiled .bin firmware files for various ESP32-based boards. When selecting a firmware, ensure you match your specific board model and memory configuration (e.g., Flash size like 4MiB, 8MiB, etc., or whether your board uses SPIRAM or is a UNICORE variant).

Supported ESP32 board families include:

• ARDUINO_NANO_ESP32
• ESP32_GENERIC (supports various Flash sizes: 4MiB, 8MiB, 16MiB, 32MiB; and variants: SPIRAM, UNICORE)
• ESP32_GENERIC_C3
• ESP32_GENERIC_S2
• ESP32_GENERIC_S3 (supports SPIRAM_OCT variants)
• LILYGO_TTGO_LORA32
• LOLIN_C3_MINI, LOLIN_S2_MINI, LOLIN_S2_PICO
• M5STACK_ATOM
• OLIMEX_ESP32_POE
• SIL_WESP32
• UM_FEATHERS series (FEATHERS2, FEATHERS2NEO, FEATHERS3, NANOS3, PROS3, TINYPICO, TINYS2, TINYS3, TINYWATCHS3)

To use a generic display with a Raspberry Pi Pico using the RP2 configuration, connect the pins according to the following mapping:

Fonts are stored as Python modules and imported using standard import statements. To reduce memory consumption on MicroPython devices:

1. Pre-compile: Pre-compile the font Python modules into .mpy files.
2. Freeze: For maximum savings, convert font files to frozen bytecode and compile them directly into the MicroPython firmware.

The tiny_toasters.py example requires the following modules to be present in your environment:

• gc9a01
• tft_config
• tiny_toasters

The write_font_converter.py utility converts characters from a TrueType font (.ttf) into a Python module containing bitmap data. This generated module can then be used with the bitmap or write methods in drivers like st7789 and ili9342.

To use the generated module, import it into your project and pass it to the tft.write() method.

# Example: Convert Chango-Regular.ttf to a python bitmap module 
# with approximately 32 pixel high characters for the range 0x20-0x7f
./write_font_converter.py Chango-Regular.ttf 32 -c 0x20-0x7f > chango_32.py

Create a GC9A01 instance by providing the SPI bus and display dimensions. You must also provide the dc (data/command) pin. Other pins like reset, cs, and backlight are optional. You can also specify rotation (0-7) and buffer_size to manage memory usage.

Memory Management Note: If you specify buffer_size, it must be large enough to hold the largest bitmap, font character, or JPG used (calculated as Rows x Columns x 2 bytes). If not specified, memory is allocated and freed dynamically, which may cause heap fragmentation; enabling garbage collection (GC) is recommended in this case.

# Example initialization
display = GC9A01(spi, width=240, height=240, dc=pin_dc, reset=pin_reset, cs=pin_cs)
display.init()