Installation: PlatformIO

This guide will setup TFT_eSPI for PlatformIO development platform.

1. Install PlatformIO

If you haven't done it yet go to PlatformIO page and follow the instructions to install it into your favorite IDE.

We will use VSCode here as an example. Install instructions and guides for VSCode can be found here.

2. Create a project

Follow this guide to set up your project. Once you have your project ready go to the file explorer at the left of your screen and open the platformio.ini file. You should see something like this:

3. Add TFT_eSPI to your project

There are different ways to include libraries in PlatformIO, but the simplest way is to add the line lib_deps = TFT_eSPI in the platform.ini file. It should look like this:

PlatformIO will automatically download and install TFT_eSPI in your project the next time you build. Library files will be stored in .pio/libdeps/env_name/TFT_eSPI/ inside the project directory. (Older versions might use TFT_eSPI_ID1559 instead of TFT_eSPI in the path.)

More info on lib_deps here.

4. Configure library

Before using the library we have to select the TFT driver, SPI pins, SPI frequency and other settings to properly control your screen. There are some pre-made setup files for the most common configurations, which can be found in the User_Setups folder.

One cool thing about PlatformIO is that we can modify the library settings without editing any library files. This allows us to create different projects using the same library, but with different settings. Also, we can update libraries to newer versions without losing our settings.

We can achieve this by using PlatformIO's build_flags. Instead of using #define, as you would in regular C/C++ files, use the -D prefix.

First of all, we prevent user settings headers to be loaded by defining USER_SETUP_LOADED. Aways define USER_SETUP_LOADED if using build_flags with the TFT_eSPI library.
Next include the User_SetupXX_XXXX.h file that matches your configuration. Use -include $PROJECT_LIBDEPS_DIR/$PIOENV/TFT_eSPI/User_Setups/SetupXX_XXXX.h. (You might have to use TFT_eSPI_ID1559 instead of TFT_eSPI.)

Your build_flags now looks like this:

build_flags =
  -D USER_SETUP_LOADED=1
  -include $PROJECT_LIBDEPS_DIR/$PIOENV/TFT_eSPI/User_Setups/Setup1_ILI9341.h

Optionally you can create your custom setup by defining the needed settings, here is an example:

  -D ILI9163_DRIVER=1                           ; Select ILI9163 driver
  -D TFT_WIDTH=128                              ; Set TFT size
  -D TFT_HEIGHT=160
  -D TFT_MISO=19                                ; Define SPI pins
  -D TFT_MOSI=23
  -D TFT_SCLK=18
  -D TFT_CS=5
  -D TFT_DC=19                                  ; Data/Comand pin
  -D TFT_RST=-1                                 ; Reset pin
  -D LOAD_GLCD=1                                ; Load Fonts
  -D SPI_FREQUENCY=27000000                     ; Set SPI frequency

All available settings can be found in User_Setup.h file. Replace #define with -D as shown here:
#define TOUCH_CS 21 -> -D TOUCH_CS=21
#define LOAD_GLCD -> -D LOAD_GLCD

The final platformio.ini file may look like this:

Using User_Setups:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps = TFT_eSPI
build_flags =
  ;###############################################################
  ; TFT_eSPI library setting here (no need to edit library files):
  ;###############################################################
  -D USER_SETUP_LOADED=1                        ; Set this settings as valid
  -include $PROJECT_LIBDEPS_DIR/$PIOENV/TFT_eSPI/User_Setups/Setup1_ILI9341.h

Custom setup:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps = TFT_eSPI
build_flags =
  ;###############################################################
  ; TFT_eSPI library setting here (no need to edit library files):
  ;###############################################################
  -D USER_SETUP_LOADED=1                        ; Set this settings as valid
  -D ILI9163_DRIVER=1                           ; Select ILI9163 driver
  -D TFT_WIDTH=128                              ; Set TFT size
  -D TFT_HEIGHT=160
  -D TFT_MISO=19                                ; Define SPI pins
  -D TFT_MOSI=23
  -D TFT_SCLK=18
  -D TFT_CS=5
  -D TFT_DC=19                                  ; Data/Comand pin
  -D TFT_RST=-1                                 ; Reset pin
  -D LOAD_GLCD=1                                ; Load Fonts
  -D SPI_FREQUENCY=27000000                     ; Set SPI frequency

5. Include header

Once you have configured the library for your screen add the line #include <TFT_eSPI.h>at the beginning of your code.

Enjoy! ;)

Home
Getting Started
- Installation
  - Arduino IDE
  - PlatformIO