Hardware Setup and Wiring
First, wire the display to your microcontroller. For SPI-based modules, you need 7 pins: MOSI, MISO, SCK, CS, DC (or RS), RST, and backlight control (LED). The ILI9341 datasheet specifies that the SPI clock frequency can go up to 10 MHz for standard operation, but many libraries default to 4 MHz for stability. Use a logic level shifter if your MCU runs at 5V, because the display’s logic pins are not 5V tolerant—applying 5V to the CS or DC pin can damage the driver IC. Power the display with 3.3V at 80-120 mA (backlight off) or up to 250 mA with full brightness. For parallel 8-bit interface (common on modules with the 8080 interface), you need 11 pins: 8 data lines, RD, WR, and DC. That wiring is more complex but offers faster pixel writes, useful for video or fast scrolling text.
For the backlight, connect the LED pin through a 100-ohm resistor to 3.3V. Some modules have a built-in transistor, so you can PWM the backlight pin directly from the MCU. Measure the backlight current with a multimeter: at 3.3V, it should draw about 20-30 mA. If you see more than 50 mA, you might have a short or the wrong resistor value. The reset pin is critical: after power-up, hold it low for at least 10 ms, then pull high. Many libraries handle this automatically, but if you see garbled text or a white screen, check that the reset pin is connected and not floating.
Software Libraries and Initialization
The most popular library for these displays is the Adafruit_ILI9341 library, built on top of Adafruit_GFX. It supports 8-bit and 16-bit fonts, with built-in bitmap fonts from 5x7 to 10x14 pixels. For a 240x320 display, the 5x7 font gives you 48 characters per line (240/5) and 45 lines (320/7) if you use no spacing—but that’s too cramped. In practice, with 1 pixel spacing between characters and 2 pixel line spacing, you get about 40 characters per line and 35 lines. That’s enough for a simple UI or sensor readouts.
For Chinese or other Unicode characters, you need a library like U8g2 or TFT_eSPI (by Bodmer). TFT_eSPI is optimized for ESP32 and supports TrueType fonts converted to C arrays, with anti-aliasing and variable font sizes. It uses the SPI DMA feature on ESP32 to push pixels without CPU overhead, achieving 30-40 FPS for text updates. The library also includes a font compression option: for a 16x16 Chinese character, the raw bitmap is 512 bytes, but with run-length encoding, it shrinks to about 80-120 bytes. That matters if you store 1000 characters in flash memory—you save 400 KB.
Initialization sequence for the ILI9341 involves sending 10-15 commands: software reset (0x01), sleep out (0x11), display on (0x29), and memory access control (0x36) to set orientation. The exact sequence is in the datasheet, but libraries abstract it. If you use a non-standard module, you might need to adjust the column and page address commands (0x2A and 0x2B) because some clone modules have swapped RGB or BGR order. Test with a solid color: if red appears as blue, swap the color order in the library’s configuration.
Font Rendering Techniques
Text rendering on a TFT is fundamentally a bitmap blitting operation. The MCU reads the font glyph bitmap from flash or SD card, then writes each pixel to the frame buffer. For a 16-bit color display, each pixel is two bytes (RGB565 format: 5 bits red, 6 bits green, 5 bits blue). Writing a single character at (x, y) involves setting a window (via the CASET and PASET commands) and then sending 2*width*height bytes. For a 10x14 character, that’s 280 bytes per character. At 4 MHz SPI, that takes about 0.07 ms per character, so a full screen of 35 lines * 40 chars = 1400 characters would take 98 ms—about 10 FPS for a full screen refresh. That’s acceptable for static text but not for scrolling.
To speed up, use frame buffer double buffering. Allocate a 320*240*2 = 153,600 byte buffer in SRAM (if your MCU has it, like on ESP32 with 520 KB). Render all text into the buffer, then flush the buffer to the display via SPI in one burst. This reduces the number of window commands and improves throughput. On an ESP32 at 80 MHz SPI, you can flush the entire buffer in about 20 ms, giving 50 FPS for full-screen updates. But note: the ILI9341’s maximum SPI speed is 10 MHz, so the real limit is about 15 FPS for a full buffer flush.
For variable-width fonts, you need a font engine that calculates kerning and advance widths. The TFT_eSPI library includes a TrueType font renderer that uses a lookup table for glyph positions. Each glyph is stored as a compressed bitmap with a 2-byte header (width, height, x offset, y offset). The renderer draws the glyph pixel by pixel, skipping transparent pixels (alpha 0). For a 24-point font, a single character might be 30x30 pixels, and rendering it takes about 1 ms on a 240 MHz ESP32. That’s fine for labels but too slow for paragraph text.
Performance Benchmarks and Trade-offs
| MCU | SPI Speed (MHz) | Font Size | Characters per Screen | Full Screen Refresh (ms) | FPS |
|---|---|---|---|---|---|
| Arduino Uno (16 MHz) | 4 | 5x7 | 1400 | 350 | 2.8 |
| ESP32 (240 MHz) | 10 | 5x7 | 1400 | 98 | 10.2 |
| ESP32 with DMA | 10 | 5x7 | 1400 | 20 | 50 |
| STM32F103 (72 MHz) | 9 | 8x13 | 720 | 80 | 12.5 |
The table shows that MCU choice matters a lot. An Arduino Uno is barely usable for static text—scrolling or animation would be jerky. An ESP32 with DMA is the sweet spot. But if you need smooth scrolling, like a terminal output, you’re better off using hardware scrolling features of the ILI9341. The display supports vertical scrolling by setting the vertical scrolling definition (0x33) and vertical scrolling start address (0x37). You can shift the entire display content by a few lines without rewriting the frame buffer. This uses the display’s internal RAM, so it’s almost instant. For a 320-pixel tall display, you can scroll 1 line at a time with zero CPU overhead.
Another approach is partial update. Only redraw the changed area of the screen. For a text terminal, you only need to update the last line when a new character is added. Set the window to the bottom line (y from 310 to 319) and write only 240*10*2 = 4800 bytes. That takes about 2.4 ms at 10 MHz SPI. Combined with a circular buffer for the terminal content, you can achieve 100+ line updates per second.
Common Pitfalls and Debugging
If text appears as random pixels or missing characters, check the SPI mode. The ILI9341 expects SPI mode 0 (CPOL=0, CPHA=0). If your library defaults to mode 3, the display will not respond correctly. Also verify the chip select polarity: CS must be active low. Some clone modules have inverted CS logic, so you might need to set the CS pin to active high in the library. Measure the voltage on the DC pin: during data transmission, it should be high (3.3V) for data bytes and low (0V) for command bytes. If it’s always high, the display will interpret commands as data, causing a white screen.
Another issue is font data corruption due to insufficient flash memory. On an Arduino Uno with 32 KB flash, storing a 16x16 Chinese font set (about 3000 characters) would need 96 KB—impossible. Use a microSD card module connected via SPI to store fonts. The SD library can read font files in binary format, and the TFT library can render directly from the SD card. But reading from SD adds latency: a 512-byte block read takes about 2 ms. For a full screen of text, that could add 100 ms. Preload frequently used characters into RAM.
Finally, power supply noise can cause text flicker. The backlight draws pulsed current, and if your power supply is weak, the display’s internal voltage regulator (3.3V from 5V input) might drop below 3.0V, causing the driver IC to reset. Add a 10 µF and 0.1 µF capacitor between VCC and GND near the display connector. Also, keep the SPI wires shorter than 20 cm to avoid signal reflections. For longer runs, use shielded cables or reduce the SPI clock to 2 MHz.
Advanced Text Effects
You can implement anti-aliased text by using a 4-bit grayscale font (16 levels) and mapping each level to a blended color. For example, a pixel that is 50% covered by the character gets a color halfway between the background and foreground. This requires a font format that stores coverage values, like the FreeType library’s rendered output. On an ESP32, you can use the Adafruit_GFX_Library with a custom font that includes anti-aliasing. The performance hit is about 2x slower per character because you need to read and blend each pixel. But for large titles, it looks much better.
For rotated text (e.g., vertical labels), you can either pre-render the text into a bitmap at the desired angle, or use the display’s rotation command (0x36) to change the scan direction. The ILI9341 supports 0, 90, 180, and 270 degree rotations by setting the MADCTL register bits. But this rotates the entire display, not individual text. For a single rotated label, you need to compute the pixel positions manually using sine/cosine tables. That’s CPU-intensive: rotating a 100-character string by 45 degrees would take about 50 ms on an ESP32. Use lookup tables for common angles.
Another trick is scrolling text marquee. Use the vertical scroll feature to shift the display content left or right by changing the column address offset. The ILI9341 doesn’t support horizontal scrolling natively, but you can simulate it by using a larger virtual screen (e.g., 480 pixels wide) and only displaying a 240-pixel window. Move the window left/right by adjusting the CASET register. This requires a frame buffer that is 480 pixels wide, doubling the memory requirement. On an ESP32 with 520 KB SRAM, you can allocate a 480x320x2 = 307,200 byte buffer, which leaves about 200 KB for other tasks.
For real-time data display (like a clock or sensor graph), use the SPI transaction feature on ESP32 to avoid interrupts corrupting the SPI transfer. The library should disable interrupts during the pixel write burst. If you see glitches in the text, enable SPI transactions in the library configuration. Also, set the backlight brightness via PWM: a 1 kHz PWM on the LED pin works well. At 100% duty cycle, the backlight draws about 80 mA; at 50%, it draws 40 mA. Use a MOSFET to drive the backlight if your MCU pin can’t source enough current.
To get started with a reliable module, look for a 2.4 inch 240x320 tft display that includes the ILI9341 driver and a 4-wire SPI interface. Check the pinout: it should have 8 pins (VCC, GND, CS, RESET, DC, MOSI, SCK, LED). Some modules have a microSD card slot on the back, which uses separate SPI pins (CS_SD, MOSI_SD, MISO_SD, SCK_SD). That’s useful for storing fonts or images. Test the module with the provided example code before building your project. If you get a white screen, try lowering the SPI speed to 1 MHz and verify all connections with a multimeter.