TFT Guides: Setting Up SPI TFT Screens on Raspberry Pi

SPI TFT screens might not always be the first choice for Raspberry Pi displays due to perceived speed limitations and GPIO pin usage. However, they offer significant advantages, particularly for projects prioritizing compactness and cost-effectiveness. Available readily online at affordable prices (around $6-$15) and in various sizes (2.2″, 2.4″, 2.8″, and larger), these screens can be trimmed down for even smaller footprints. While requiring a few extra wires and some software adjustments, setting them up is straightforward. This guide provides a comprehensive walkthrough to get your SPI TFT screen working flawlessly with your Raspberry Pi.

Let’s begin by connecting the display to your Raspberry Pi. Ensure your Raspberry Pi is powered off before making any connections.

Wiring the SPI TFT Screen to Raspberry Pi

Establish the connections as detailed below. It’s crucial to double-check each connection to avoid any issues during setup.

Raspberry Pi SPI TFT Wiring Diagram

Visual representation of the wiring connections between the SPI TFT screen and the Raspberry Pi GPIO pins, highlighting each pin’s function and corresponding connection point.

Software Configuration for SPI TFT Display

With the hardware wired, it’s time to configure your Raspberry Pi’s software. This guide assumes you are starting with a fresh installation of Raspberry Pi OS or RetroPie, which is common for projects using small screens.

1. Initial Raspberry Pi Configuration:

   Boot your Raspberry Pi with a keyboard and a standard display connected (HDMI). Once booted, open a terminal. For RetroPie, exit Emulation Station to access the terminal.

   Type the following command to access the Raspberry Pi configuration menu:

   sudo raspi-config

   Navigate to “Advanced Options” and ensure the following settings are configured:

   • Overscan: Disable overscan to ensure the display area is correctly sized.
   • SPI: Enable SPI interface, which is necessary for communication with the TFT screen.

   Use the arrow keys to navigate, select “Finish,” and reboot your Raspberry Pi when prompted.

2. Loading the TFT Screen Module:

   After rebooting, access the terminal again. We need to load the kernel module for our specific TFT screen. For many common SPI TFT screens using the ILI9341 driver chip, use the following command:

   sudo modprobe fbtft_device custom name=fb_ili9341 gpios=reset:25,dc:24,led:18 speed=16000000 bgr=1

   Let’s break down this command:

   • sudo modprobe fbtft_device: Loads the fbtft_device kernel module, which is a generic framebuffer driver for TFT screens.
   • custom name=fb_ili9341: Specifies the driver for the ILI9341 chip. If your screen uses a different driver, you’ll need to find the appropriate module name.
   • gpios=reset:25,dc:24,led:18: Defines the GPIO pins used for reset (25), data/command (24), and backlight LED (18). Adjust these if you used different GPIO pins during wiring.
   • speed=16000000: Sets the SPI communication speed to 16MHz. This is a common and generally reliable speed.
   • bgr=1: Specifies the color order as Blue-Green-Red. This is often necessary for correct color display on ILI9341 screens.

   Upon running this command, your TFT screen’s backlight should turn on – a positive indication that the module is loading correctly and the screen is receiving power.

3. Redirecting Console to TFT Screen:

   To display the Raspberry Pi console on your new TFT screen, use the con2fbmap command:

   con2fbmap 1 1

   This command redirects the console output (virtual terminal 1) to framebuffer 1, which is now associated with your TFT screen. You should now see the console text appear on the small TFT display!

   Image showing the Raspberry Pi terminal console displayed on a small SPI TFT screen, confirming successful initial setup and display functionality.

   To switch the console back to your primary display (e.g., HDMI), you can use:

   con2fbmap 1 0

Making the TFT Screen Persistent Across Reboots

Typing the modprobe command every time you reboot is inconvenient. Let’s configure the Raspberry Pi to automatically load the TFT screen module at startup.

1. Loading Module at Startup:

   Edit the /etc/modules file to instruct the Raspberry Pi to load the necessary modules during boot. Open the file using the nano text editor:

   sudo nano /etc/modules

   Add the following two lines at the end of the file, below any existing content:

   spi-bcm2835
   fbtft_device

   • spi-bcm2835: Ensures the SPI interface is initialized and ready.
   • fbtft_device: Loads the TFT framebuffer driver.

   Press Ctrl+O to save (and Enter to confirm the filename) and Ctrl+X to exit nano.

2. Specifying TFT Module Options:

   We need to permanently apply the module options (driver name, GPIOs, speed, etc.). Create or edit the /etc/modprobe.d/fbtft.conf file:

   sudo nano /etc/modprobe.d/fbtft.conf

   If the file is empty (which is likely), add the following line:

   options fbtft_device name=fb_ili9341 gpios=reset:25,dc:24,led:18 speed=16000000 bgr=1 rotate=90 custom=1

   • rotate=90: Rotates the display by 90 degrees. Adjust this value (0, 90, 180, 270) as needed for your screen orientation.
   • custom=1: This parameter might be specific to certain screen types or configurations; consult your screen’s documentation if needed. If unsure, try without it initially.

   Save and exit nano (Ctrl+O, Enter, Ctrl+X).

   Reboot your Raspberry Pi (e.g., sudo reboot or sudo init 6). With these configurations, your TFT screen should now initialize and light up automatically during the boot process. If it doesn’t, double-check your file edits for typos and use dmesg in the terminal to check for any kernel errors related to module loading.

   Test again with con2fbmap 1 1 to confirm the console is still redirected to the TFT screen after automatic loading.

Mirroring Graphics to the TFT Screen with fbcp

While the console is functional, graphical applications and Emulation Station in RetroPie require frame buffer copying to display correctly on the SPI TFT screen, as these screens lack dedicated graphics acceleration. fbcp (framebuffer copy) is a utility that efficiently copies the main framebuffer to the TFT framebuffer.

1. Installing fbcp:

   Open a terminal and execute the following commands to install fbcp:

   sudo apt-get update
   sudo apt-get install cmake git
   git clone https://github.com/tasanakorn/rpi-fbcp
   cd rpi-fbcp/
   mkdir build
   cd build/
   cmake ..
   make
   sudo install fbcp /usr/local/bin/fbcp

   These commands perform the following:

   • sudo apt-get update && sudo apt-get install cmake git: Updates package lists and installs cmake (build tool) and git (version control system).
   • git clone https://github.com/tasanakorn/rpi-fbcp: Downloads the fbcp source code from GitHub.
   • cd rpi-fbcp/ && mkdir build && cd build/: Navigates to the downloaded directory and creates a build directory.
   • cmake ..: Configures the build process using CMake.
   • make: Compiles the fbcp program.
   • sudo install fbcp /usr/local/bin/fbcp: Installs the compiled fbcp executable to /usr/local/bin/, making it accessible system-wide.

2. Testing fbcp:

   To test if fbcp is working, simply run:

   fbcp

   If successful, the contents of your main display should now be mirrored onto your SPI TFT screen! You should see your desktop environment or Emulation Station interface on the small screen.

   Image showing the Raspberry Pi desktop environment mirrored onto the SPI TFT screen, demonstrating successful framebuffer copying using fbcp.

3. Autostarting fbcp at Boot:

   To automatically start fbcp on every boot, we need to add it to the /etc/rc.local file. This file is executed during the boot process.

   sudo nano /etc/rc.local

   In the rc.local file, you’ll find some existing lines. Add the following line before the exit 0 line:

   fbcp &

   The ampersand & is crucial; it runs fbcp in the background, allowing the boot process to continue. Your /etc/rc.local file should look similar to this (the IP address lines might vary):

   _IP=$(hostname -I) || true
   if [ "$_IP" ]; then
     printf "My IP address is %sn" "$_IP"
   fi
   fbcp &
   exit 0

   Save and exit nano. Reboot your Raspberry Pi one last time. Now, your TFT screen should initialize, display the boot messages, and then automatically show the graphical interface thanks to fbcp starting in the background.

Congratulations! You have successfully set up your SPI TFT screen on your Raspberry Pi. This setup opens up possibilities for various projects, from compact handheld consoles to informative status displays. Explore further customizations and enjoy your new Raspberry Pi display!