instructables

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

by shan-mcarthur

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

Using TFT_eSPI Library With Visual Studio Code and PlatformIO and an ESP32 Microcontroller: Page 1
Step 1: Locate Datasheets

Locate the Datasheets and other technical information for your speci c module and the embedded LCD screen. In my
Using TFT_eSPI Library With Visual Studio Code and PlatformIO and an ESP32 Microcontroller: Page 2
example, this was a 3.5" ILI9488 screen. At this point you should con rm all required pin connections and power
requirements. With larger LCDs you should also con rm that your microcontroller has su cient power or design an
appropriate power supply into your overall circuit. This LCD t 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 nd a speci c datasheet, try to nd your product on LCDwiki website - it is an invaluable resource. My speci c
board is located here: 3.5inch SPI Module ILI9488 SKU:MSP3520 - LCD wiki
You will also need the datasheet for your microcontroller, and speci cally 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.

Step 2: Determine Wiring Strategy and Connect 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

Using TFT_eSPI Library With Visual Studio Code and PlatformIO and an ESP32 Microcontroller: Page 3
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.

Step 3: Create a Platform IO Project

I am assuming this isn't your rst project and you are already set up with Visual Studio Code and PlatformIO extensions.
Most instructions you are going to nd 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 le 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 le now and add the include to your project and compile
to ensure that everything is working and you don't have con icting dependencies in your project. Don't proceed further
until you have a clean compile.
#include <TFT_eSPI.h>

Step 4: Configuring the TFT_eSPI Library for Your LCD Panel

The TFT_eSPI library documentation heavily advocates for you to edit the library header les, which I don't recommend.
The libdeps les are subject to being overwritten when updated and it is also excluded from source control via .gitignore
les. 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 con g directly in your project and do not modify the library les. Ignore all (or most) of the
instructions they give you on modifying the header les,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 les from within the libdeps\[controller]\TFT_eSPI\User_Setups folder. My board is an ILI9488, so the
header le I am most interested in is the Setup32_ILI9488.h le. Inspect the le and look for the macros labeled
TFT_MOSI, TFT_MISO, and TFT_SCLK. If these numbers match your board, then this le is likely going to be the base for
what you want to use. You can use this le by con g ID, but for the purpose of showing you how you can con gure your
own custom project and use your own pins for the other controls, I am going to use a custom de nition in the
platformio.ini le but using these as a guide.
Open your platformio.ini le 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

Using TFT_eSPI Library With Visual Studio Code and PlatformIO and an ESP32 Microcontroller: Page 4
Add the following lines to the bottom of the le. Substitute the appropriate pin numbers for your speci c controller and
project requirements. Look at the pinout diagram I included previously in this instructable and see how the numbers
map to speci c 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 rst one in the
list as it is important. This USER_SETUP_LOADED macro is used by the library's header les to ignore loading many of the
screen speci c header les automatically and to use the values you are providing here. If you neglect to provide this
macro, your settings are not going to be e ective.
Note that my LCD remained o 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 le that you found in the previous step and include each and every
macro that is de ned in that le. Omitting a macro might not give you appropriate functionality.

Step 5: Code Your Project

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 le:
#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:
}

Using TFT_eSPI Library With Visual Studio Code and PlatformIO and an ESP32 Microcontroller: Page 5
That is not a lot of code, and by consequence, not a lot that can go wrong. Your rst 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 con guration, 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 su cient 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.

Step 6: Review the Other Included Examples

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
le and ignore the fact they are designed for the Arduino IDE - just remember to use the techniques above to con gure
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 con guration.

Step 7: Engage With the Github Community

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

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