Using TFT_eSPI Library With Visual Studio Code and PlatformIO and an ESP32 Microcontroller

I am using a 3.5" TFT touch screen LCD with an ESP32 development board (NodeMCU-32S). My development environment is Visual Studio Code using PlatformIO extensions and the TFT_eSPI library

Locate the Datasheets and other technical information for your specific module and the embedded LCD screen. In my example, this was a 3.5" ILI9488 screen. At this point you should confirm all required pin connections and power requirements. With larger LCDs you should also confirm that your microcontroller has sufficient power or design an appropriate power supply into your overall circuit. This LCD fit my board's capabilities and it matched the voltage provided by my board (3.3v). A 5v board would need a power converter to avoid burning out the LCD. Pay attention to all electrical requirements before you proceed.

If you can't find a specific datasheet, try to find your product on LCDwiki website - it is an invaluable resource. My specific board is located here: 3.5inch SPI Module ILI9488 SKU:MSP3520 - LCD wiki

You will also need the datasheet for your microcontroller, and specifically the pinouts for your board. These pinouts are likely going to include a diagram that has the board in the middle, with the screened labels on the board, and lines that go outward from there. On those lines you will also see lots of coded bubbles, which will be useful for later when you hook up your panel.

Determine the connectivity strategy for your LCD panel. This will typically be a variant of SPI or I2C. An SPI interface is going to be faster, but will use more pins. An SPI interface needs MOSI, SCK, and optionally a MISO if you are going to read anything from the LCD. It will also need a CS (chip select) pin that will be run LOW when the chip is being addressed and HIGH when it is not. Many LCD panels will have backlighting, so you can control that with another GPIO pin or in my case, I just wired that to VCC. Many LCDs also have a RESET pin that also needs to be wired to a GPIO pin on your controller. This LCD also uses a DC/DS pin to designate whether or not the data going over the wire is an instruction or data. Finally you will need power and ground.

Using your microcontroller pinout diagram, look for labels that designate MOSI, MISO, SCK. Those are going to be supported by hardware SPI which is going to be faster than software SPI. You may have more than one set of SPI pins, so choose the set that works for you and note the pin numbers (using the silkscreen numbers and not the numbers outside of the board). Also look for a few unused GPIO pins that you can use for LED power, CS, DC, and RESET. Note all of those pin numbers for later.

Now wire up the board according to the above located pins, carefully following instructions in the datasheets or manuals for your LCD panel.

I am assuming this isn't your first project and you are already set up with Visual Studio Code and PlatformIO extensions. Most instructions you are going to find on the web are using the Arduino IDE and Uno or Mega boards. I am going to assume you are here because you are interested in a more professional approach using Visual Studio Code and PlatformIO and already know the basics of how projects work and are uploaded to the controller. Once you have the software installed you will want to create a new project (or use an existing one that you are adding the LCD panel for). Using the PlatformIO extension, you can use the library manager and search for the TFT_eSPI library. From there you can add the library to your project. Alternatively you can do this with the PlatformIO Core CLI - both will edit the platformio.ini file and add the library to the list of dependencies. The PlatformIO extension will then work in the background and download the correct version and place it in your project's .pio\libdeps folder.

Once the library is added to your project, locate your main.cpp file now and add the include to your project and compile to ensure that everything is working and you don't have conflicting dependencies in your project. Don't proceed further until you have a clean compile.

#include <TFT_eSPI.h>

The TFT_eSPI library documentation heavily advocates for you to edit the library header files, which I don't recommend. The libdeps files are subject to being overwritten when updated and it is also excluded from source control via .gitignore files. They can be inadvertently deleted if you ever need to initiate a clean action on your project with PlatformIO. I feel it is better for you to place your config directly in your project and do not modify the library files. Ignore all (or most) of the instructions they give you on modifying the header files,but mark their location and be familiar with their contents as you are going to need that information for the next step. Determine which LCD screen your project has and locate the appropriate header files from within the libdeps\[controller]\TFT_eSPI\User_Setups folder. My board is an ILI9488, so the header file I am most interested in is the Setup32_ILI9488.h file. Inspect the file and look for the macros labeled TFT_MOSI, TFT_MISO, and TFT_SCLK. If these numbers match your board, then this file is likely going to be the base for what you want to use. You can use this file by config ID, but for the purpose of showing you how you can configure your own custom project and use your own pins for the other controls, I am going to use a custom definition in the platformio.ini file but using these as a guide.

Open your platformio.ini file in your project. This will look something like this:

[env:nodemcu-32s]
platform = espressif32
board = nodemcu-32s
framework = arduino
monitor_speed = 115200
lib_deps = bodmer/TFT_eSPI@^2.5.23

Add the following lines to the bottom of the file. Substitute the appropriate pin numbers for your specific controller and project requirements. Look at the pinout diagram I included previously in this instructable and see how the numbers map to specific pins.

build_flags =
    -D USER_SETUP_LOADED
    -D ILI9488_DRIVER
    -D TFT_MISO=19
    -D TFT_MOSI=23
    -D TFT_SCLK=18
    -D TFT_CS=15
    -D TFT_DC=2
    -D TFT_RST=4
    -D LOAD_GLCD=1
    -D LOAD_FONT2
    -D LOAD_FONT4
    -D LOAD_FONT6
    -D LOAD_FONT7
    -D LOAD_FONT8
    -D LOAD_GFXFF
    -D SMOOTH_FONT
    -D SPI_FREQUENCY=27000000

Each of these lines is a compiler directive to use these macros when compiling the project. Please note the first one in the list as it is important. This USER_SETUP_LOADED macro is used by the library's header files to ignore loading many of the screen specific header files automatically and to use the values you are providing here. If you neglect to provide this macro, your settings are not going to be effective.

Note that my LCD remained off if I did not include the SMOOTH_FONT macro. I didn't realize this macro was required for proper functioning of this screen. Please review the file that you found in the previous step and include each and every macro that is defined in that file. Omitting a macro might not give you appropriate functionality.

I always start a project with some form of the most basic example, and for output devices this typically is displaying the classical "Hello World!" message. A minimal program like this makes it easy for you to validate that your hardware, connections, settings, and development environment are all working. If this doesn't work, it is easier for you to troubleshoot. So to give you the minimal program with no unnecessary code, consider using the following for your main.cpp file:

#include <Arduino.h>
#include <TFT_eSPI.h> 
TFT_eSPI tft = TFT_eSPI();

void setup() 
{
  tft.init();
  tft.setRotation(1);
  tft.fillScreen(TFT_BLACK);
  tft.setCursor(0,0,4);
  tft.setTextColor(TFT_WHITE);
  tft.println ("Hello World!");
}

void loop() 
{
  // put your main code here, to run repeatedly:
}

That is not a lot of code, and by consequence, not a lot that can go wrong. Your first goal should be to see your screen showing Hello World! for you. If your screen is not doing this, then there is likely something wrong with your wiring, or your pin configuration, or perhaps even a failed LCD panel. If the panel doesn't light up, use your electrical skills with a multimeter to ensure that you have sufficient voltage to power the screen. Ensure that important pins like the DC and RESET pins are also connected. The most important pin will be the LED control - if the LED is not powered you will not see anything on the screen.

This particular library is very well written and it includes a large number of examples that will show many of the capabilities of the library and how you can use each of them. You can browse them easily in Visual Studio Code by looking in the .pio\libdeps\[controller]\TFT_eSPI\examples folder, or by visiting the github site for the library (more on that later). It is remarkable that there are so many example projects that they are even organized into sub folders. Note that these simple examples are written for the Arduino IDE. You can copy/paste most of them intact into your main.cpp file and ignore the fact they are designed for the Arduino IDE - just remember to use the techniques above to configure each of your projects before you deploy and run them.

I would also like to highlight the Test and Diagnostics folder as it includes a few important sketches that can assist you in further diagnosing issues with your display or configuration.

The TFT_eSPI library is a high quality library that has a very active community. It is currently a very active project and the author and others are answering questions regularly in the discussion forums. Please familiarize yourself with the discussions and wikis on the project and go there for support and contributions.

Bodmer / TFT_eSPI Github Project