Interface TFT ST7789 Display with ESP32

In this tutorial you will learn how to interface a 1.3″ 240×240 TFT display module with a ST7789 display driver with an ESP32 (WEMOS Lolin32 lite).

The instructions and code will work with some minor changes for other ESP32’s and TFT’s as well, as long as the display uses the ST7789 display driver.

Required Parts

You will need an ESP32 and an 1.3 inch TFT display with a resolution of 240×240 pixels and an ST7789 display driver IC. Some cables and a breadboard might come in handy as well.

Makerguides.com is a participant in the Amazon Services LLC Associates Program, an affiliate advertising program designed to provide a means for sites to earn advertising fees by advertising and linking to products on Amazon.com. As an Amazon Associate we earn from qualifying purchases.

1.3″ TFT ST7789 Display Module

The 1.3″ TFT Display Module we are going to use here has as a resolution of 240×240 pixels with 65K RGB colors. The picture below shows the front and back of the display module:

The module uses the ST7789 driver chip and is controlled via a SPI-4wire interface. The operating voltage is 3.3V and the display draws around 30mA max. Note that there are many different versions of this kind of TFT display.

Some TFT display modules have a logic level converter that allows you to connect the display module to an Arduino UNO that operates on 5V. This one here does not, which means you cannot directly connect it to an Arduino! We use therefore use an ESP32 that operates with CMOS 3.3V logic.

If you want to use an Arduino you need to convert the logic levels. There are various ways to do this (voltage divider, optocoupler, level-shifting IC) but the easiest is to get a level shifting module.

Finally, there are similar displays that use the ST7735S driver IC instead of the ST7789. The configuration in this tutorial is for displays with the ST7789 driver IC and will not work for others.

Connecting 1.8″ TFT ST7735 Display with ESP32

Connecting the TFT Display to the ESP32 is simple but the labelling of the pins on the display is a bit confusing. It shows SDA and SCL pins but since it has an SPI interface, these pins should be labelled MOSI and SCLK.

The following wiring diagram shows you how to connect the 1.3″ TFT ST7789 Display Module to an WEMOS Lolin32 lite:

And here are the required connections again as a table. Note that this display module has no chip select (CS) and therefore no pin is needed for it.

Display	ESP32
RST	16
DC	17
SDA / MOSI	23
SCL / SCLK	18
BKL/BL	22
GND	GND
VCC	3.3V

Make sure to connect VCC of the display to 3.3V! Also you should use the hardware SPI pins for MOSI and SCLK. Depending on the microcontroller the hardware SPI pins will differ. You can find them by selecting your board in the Arduino IDE and then running the code below.

void setup() {
  Serial.begin(115200);
  Serial.print("MOSI: ");
  Serial.println(SDA / MOSI);
  Serial.print("MISO: ");
  Serial.println(MISO);
  Serial.print("SCL / SCLK: ");
  Serial.println(SCK);
  Serial.print("CS / SS: ");
  Serial.println(SS);  
}

void loop() { }

It prints out the pins you need for hardware SPI – specifically MOSI and SCLK. The remaining pins you can select freely and MISO is not used.

Code for TFT ST7735 Display with TFT_eSPI Library

In the this section, I show you how to use the TFT_eSPI library to control the display. To install this library open the Library Manager, search for “TFT_eSPI” and press “INSTALL”. After installation it should look like this:

Next we need to create the correct project folder structure. Open your Arduino IDE and create a project “tft_test” and save it (Save As …). This will create a folder “tft_test” with the file “tft_test.ino” in it. In this folder create another file named “tft_setup.h“. Your project folder should look like this

If you want to learn more about this setup and other options to configure a TFT display for the TFT_eSPI library have a look at the How to configure TFT_eSPI Library for TFT display tutorial.

After the project folder with the two files is created, copy the following configuration code for the TFT display into the tft_setup.h file:

// 1.3" TFT Display (GMT130 V.10), 
// no CS pin
// 240x240, ST7789
// tft_setup.h
#define ST7789_DRIVER

#define TFT_WIDTH  240
#define TFT_HEIGHT 240

#define TFT_RGB_ORDER TFT_BGR

#define TFT_CS    -1   
#define TFT_RST   16  
#define TFT_DC    17  
#define TFT_MOSI  23  // SDA // HW MOSI
#define TFT_SCLK  18  // SCL // HW SCL
#define TFT_MISO  19  // not used
#define TFT_BL    22  // LED back-light
#define TFT_BACKLIGHT_ON HIGH


#define LOAD_GLCD   
#define LOAD_FONT2  
#define LOAD_FONT4  
#define LOAD_FONT6  
#define LOAD_FONT7  
#define LOAD_FONT8  
#define LOAD_GFXFF
#define SMOOTH_FONT 

#define SPI_FREQUENCY  27000000
#define SPI_READ_FREQUENCY  20000000
#define SPI_TOUCH_FREQUENCY  2500000

and the code for the sketch goes into the tft_test.ino file:

// tft_test.ino
#include "tft_setup.h"
#include"TFT_eSPI.h"

TFT_eSPI tft = TFT_eSPI();

const int cw = tft.width()/2;
const int ch = tft.height()/2;
const int s = min(cw/4,ch/4);

void setup(void) {  
  tft.init();
  tft.fillScreen(TFT_BLACK);  
  tft.setRotation(1);

  tft.setTextFont(1);
  tft.setTextSize(2);
  tft.setTextColor(TFT_WHITE, TFT_BLACK);
  tft.setTextDatum(CC_DATUM);
  tft.drawString("Makerguides", ch, cw+s);

  tft.fillCircle(ch, cw/2+s/2, s/2, TFT_RED);
  tft.fillRect(1.5*ch-s, cw/2, s, s, TFT_GREEN);
  tft.fillTriangle(ch/2, cw/2, ch/2+s, cw/2, ch/2, cw/2+s, TFT_BLUE);
}

void loop() { }

Note that tft_setup.h is included at the top of the program. The code itself is easy to understand. We create a TFT_eSPI object and constants for the center (cw, ch) and the size s of the objects to draw.

In the setup function we initialize the TFT screen, fill the screen with black and rotate it to portrait mode.

Next, we set the font, its size, color, and alignment, and write the text “Makerguides” to the screen. In the next three lines we draw the red circle, green square, and the blue triangle. The output on your TFT screen should look similar to this:

If not, then something is wrong with the settings in tft_test.ino or the with wiring of the TFT display. Have a look at the How to configure TFT_eSPI Library for TFT display tutorial to see what other setting are available and what you could try to solve the problem.

Conclusions

In this tutorial you learned how to interface a TFT display module with a ST7789 display driver with an ESP32.

I used the TFT_eSPI Library to control the display. I also tried the Adafruit-ST7735 Library but couldn’t get it to work. Others have reported the same problem and were successful with the ST7789_AVR library instead. However, the ST7789_AVR library works only with AVR boards but not with an ESP32, for instance.

If you have difficulties with TFT_eSPI the library, our How to configure TFT_eSPI Library for TFT display might help.

If you have any comments, feel free to leave them in the comment section.

Happy Tinkering ; )