TFT_eSPI Graphics Library

Library configuration (font selection, pins, and features) is managed via header files. You can enable or disable specific fonts and features by commenting out lines in the configuration files.

Configuration Methods:

1. Edit the User_Setup.h file directly in the library folder.
2. Select a pre-defined configuration by editing the User_Setup_Select.h file.

To ensure compatibility with bmp2array4bit.py, you must prepare your image in GIMP (or a similar tool) using these specific settings:

1. Remove Alpha Channel: Layer -> Transparency -> Remove Alpha Channel.
2. Set Indexed Mode: Image -> Mode -> Indexed....
3. Palette Selection: Select Generate optimum palette with 16 colors (max).
4. Export Settings: Export as a .bmp file.

CRITICAL: Do NOT enable the following options during export:

• Run-Length Encoded (RLE)
• Compatibility Options: "Do not write color space information"

Note: Other tools may work as long as they avoid run-length encoding and other advanced compression features.

On the ESP8266, you can use SPI overlap mode to allow the TFT screen to share the MOSI, MISO, and SCLK pins with the program FLASH. This frees up GPIO pins for other peripherals.

Constraints:

• Only one SPI device can be connected to the FLASH pins.
• The chip select (CS) for the TFT must be on pin D3 (GPIO0).

The library supports the XPT2046 touch screen controller for SPI-based displays.

Setup Requirements:

• The touch controller must share the SPI bus with the TFT.
• An additional chip select line is required.

Note: This support is subject to future deprecation when a suitable touch screen library becomes available.

TFT_eSPI requires the screen controller, interface pins, and library configuration settings to be defined within the library itself, rather than in your Arduino sketch.

To configure your hardware:

1. Open the User_Setup_Select.h file within the library folder.
2. Select the appropriate setup file for your specific display and processor combination.

PlatformIO Users: You can define these settings on a per-project basis within your platformio.ini file instead of modifying the library files directly.

The library supports smooth, anti-aliased fonts in .vlw format. These fonts support 16-bit Unicode characters (e.g., Greek, Japanese) and UTF-8 strings.

Implementation Options:

1. File System: Upload .vlw files to the processor's FLASH filing system (SPIFFS, LittleFS, or SD card).
2. C Arrays: Convert .vlw files to C arrays (using the Smooth Font -> FLASH_Array examples) and store them directly in FLASH. This is recommended for processors like STM32 that may not support a FLASH-based filing system.

Important Limitations:

• Anti-aliased fonts cannot be scaled using setTextSize(). You must create a separate font file for every size you intend to use.

The library supports common 8-bit parallel "Mcufriend" shields for STM Nucleo (64/144) and ESP32 UNO-style boards, as well as STM32 "Blue/Black Pill" boards.

ESP32 UNO Style Hardware Note: Typical UNO/mcufriend boards map LCD_RD, LCD_CS, and LCD_RST to ESP32 analog pins (35, 34, 36) which are input-only. To fix this, you may need to wire the spare pins as follows:

• IO15 $\rightarrow$ IO35
• IO33 $\rightarrow$ IO34
• IO32 $\rightarrow$ IO36

An example setup file for this configuration can be found in the repository.

Sprites are invisible graphics buffers stored in RAM. You can draw graphics to a Sprite and then plot it onto the screen at any position. This is useful for flicker-free animations or creating frame buffers.

Key Characteristics:

• Bit Depth: Supports 16-bit (default), 8-bit (256 colors), or 1-bit (2 colors) to save RAM.
• RAM Usage:
  • 16-bit: (2 * width * height) bytes.
  • 8-bit: (width * height) bytes.
• ESP32 PSRAM: If your ESP32 has SPIRAM, Sprites will use it, allowing for large full-screen buffers.
• Transparency: Sprites can be plotted to the TFT with one color specified as "transparent".

Refer to the examples/Sprite folder for usage examples.

To prevent your custom configurations from being overwritten when updating the TFT_eSPI library, store your setup files in a separate directory outside the library folder.

Recommended Workflow:

1. Create a folder named TFT_eSPI_Setups in your Arduino library folder.
2. Place your custom .h files there.
3. In the library's User_Setup_Select.h, point to your custom file using a relative path:

#include <../TFT_eSPI_Setups/my_custom_setup.h>

Alternatively, you can create your own my_setup_select.h file and point User_Setup_Select.h to it to manage multiple configurations without touching the library files directly.

The bmp2array4bit.py script converts a BMP file into C or C++ code containing two arrays: one for the image palette and one for the image data itself. This is used for adding images to four-bit sprites in the TFT_eSPI library.

Requirements:

• Python 3.6 or higher.

Usage: Run the script from your terminal using the following syntax: python bmp2array4bit.py [-v] star.bmp [-o myfile.c]

• -v: Verbose mode (optional).
• star.bmp: Your input BMP file.
• -o myfile.c: The name of the output C file.

If you are using an SD card on the same SPI bus as your TFT display, you must explicitly define the SPI pins in your User_setup.h file, even if you are using the default pins for your board.

Required Keys:

• _TFT_MISO_
• _TFT_MOSI_
• _TFT_SCLK_

Failure to declare these pins explicitly may result in the SD card becoming unusable after the display is initialized.