Interfacing Arduino with ST7789 TFT Display – Graphics Test Example

This Arduino tutorial shows how to interface the UNO board with ST7789 TFT display.
The ST7789 TFT module contains a display controller with the same name: ST7789. It’s a color display that uses SPI interface protocol and requires 3, 4 or 5 control pins, it’s low cost and easy to use. This display is an IPS display, it comes in different sizes (1.3″, 1.54″ …) but all of them should have the same resolution of 240×240 pixel, this means it has 57600 pixels. This module works with 3.3V only and it doesn’t support 5V (not 5V tolerant).

TFT: Thin-Film Transistor.
SPI: Serial Peripheral Interface.
IPS: In-Plane Switching.

The following image shows a ST7789 display module provided by Adafruit Industries:

Adafruit ST7789 TFT display module
Adafruit ST7789 TFT display module

Another version of the ST7789 display module is shown below. This one has no CS (chip select) pin, its internally attached to GND:

ST7789 TFT display without CS pin
ST7789 TFT display without CS pin

Project Hardware Required:

  • Arduino UNO board
  • ST7789 TFT display module (1.3″, 1.54″ …)
  • 4 x 3.3k ohm resistor (+1 if the display module has CS pin)
  • 4 x 2.2k ohm resistor (+1 if the display module has CS pin)
  • Breadboard
  • Jumper wires
Arduino uno with ST7789 IPS TFT display
Arduino uno with ST7789 IPS TFT display

Interfacing Arduino UNO with ST7789 TFT circuit:
Project circuit schematic diagram is shown below.

The ST7789 display module shown in project circuit diagram has 7 pins: (from right to left): GND (ground), VCC, SCL (serial clock), SDA (serial data), RES (reset), DC (or D/C: data/command) and BLK (back light).
Connecting the BLK pin is optional. The back light turns off when the BLK pin connected to the ground (GND).

Arduino ST7789 TFT display circuit
Arduino ST7789 TFT display circuit

As mentioned above, the ST7789 TFT display controller works with 3.3V only (power supply and control lines). The display module is supplied with 3.3V (between VCC and GND) which comes from the Arduino board.

All Arduino UNO board output pins are 5V, connecting a 5V pin to the ST7789 TFT display may damage its controller.
To connect the Arduino to the display module, I used voltage divider for each line which means there are 4 voltage dividers. Each voltage divider consists of 2.2k and 3.3k resistors, this drops the 5V into 3V which is sufficient.

If the display module has a CS pin (Chip Select) then it should be connected to Arduino digital pin 10 through another voltage divider.

So, the ST7789 TFT display is connected to the Arduino board as follows (each one through voltage divider):
RST pin is connected to Arduino digital pin 8,
DC pin is connected to Arduino digital pin 9,
SDA pin is connected to Arduino digital pin 11,
SCL pin is connected to Arduino digital pin 13.

Other pins are connected as follows:
VCC pin is connected to Arduino 3V3 pin,
GND pin is connected to Arduino GND pin,
BL (LED) pin is connected to Arduino 3V3 pin (optional).

Interfacing Arduino UNO with ST7789 TFT code:
The following Arduino code requires two libraries from Adafruit Industries:
The first library is a driver for the ST7789 TFT display which can be installed from Arduino IDE library manager (Sketch —> Include Library —> Manage Libraries …, in the search box write “st7789” and install the one from Adafruit).

The second library is Adafruit graphics library which can be installed also from Arduino IDE library manager.

Both libraries can be installed manually, first download them from the following 2 links:
Adafruit ST7789 TFT library    —->  direct link
Adafruit graphics library        —->  direct link

After the download, go to Arduino IDE —> Sketch —> Include Library —> Add .ZIP Library … and browse for the .zip file (previously downloaded).
The same thing for the other library file.

Hints:
The 2 library files are included in the main code as shown below.
Including Arduino SPI library is optional!

The ST7789 TFT module pins (CS, RST and DC) connections are defined as shown below:

The other display pins (SDA and SCL) are connected to Arduino hardware SPI pins (digital pin 11 and digital pin 13).

The Adafruit ST7789 library is initialized with this line:

And the TFT display is initialized using the following command:

The display may not work if it has a CS pin, try with SPI_MODE0 which is the default mode of the library or just use: tft.init(240, 240);

Rest of code is described through comments.

Full Arduino code:

The video below shows my breadboard test circuit:

34 thoughts on “Interfacing Arduino with ST7789 TFT Display – Graphics Test Example”

  1. HELP

    C:\Users\sefao\AppData\Local\Temp\.arduinoIDE-unsaved202325-17488-1g2uwtf.gqif\sketch_mar5b\sketch_mar5b.ino:16:1: error: ‘tft’ does not name a type
    tft.init(240, 240, SPI_MODE3); // Init ST7789 display 240×240 pixel
    ^~~
    C:\Users\sefao\AppData\Local\Temp\.arduinoIDE-unsaved202325-17488-1g2uwtf.gqif\sketch_mar5b\sketch_mar5b.ino:58:17: error: redefinition of ‘Adafruit_ST7789 tft’
    Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_RST);
    ^~~
    C:\Users\sefao\AppData\Local\Temp\.arduinoIDE-unsaved202325-17488-1g2uwtf.gqif\sketch_mar5b\sketch_mar5b.ino:13:17: note: ‘Adafruit_ST7789 tft’ previously declared here
    Adafruit_ST7789 tft = Adafruit_ST7789(TFT_CS, TFT_DC, TFT_RST);
    ^~~
    C:\Users\sefao\AppData\Local\Temp\.arduinoIDE-unsaved202325-17488-1g2uwtf.gqif\sketch_mar5b\sketch_mar5b.ino: In function ‘void mediabuttons()’:
    C:\Users\sefao\AppData\Local\Temp\.arduinoIDE-unsaved202325-17488-1g2uwtf.gqif\sketch_mar5b\sketch_mar5b.ino:314:12: error: expected ‘}’ at end of input
    delay(50);
    ^

    exit status 1

    Compilation error: ‘tft’ does not name a type

    WHAT CAN I DO FOR THAT?????

  2. Hello, help me pls.

    Why is the voltage divider necessary for the control pins? (SCL, SDA, RST, DC)
    In the videos that I was watching they do not connect any type of resistance, they do it directly to the arduino UNO.

    However, I am having problems with my display. the model is zjy-ips130-v2.0

    I use the code and everything loads fine, but I see that the display comes out very dark and each pixel seems to have an error, it’s twinkling…
    but when I press the Reset button on the arduino, or reload the program, in those 1-2 seconds the screen shows correctly what it should show initially, is it a problem of voltage to the pins then?

    1. Simple Projects

      As described above, the display works with 3.3V only and the Arduino outputs are 5V, therefore we need to decrease the Arduino 5V into 3.3V and for this reason we used the voltage divider resistors.
      In the video the voltage divider resistors are already used and they are soldered in the DIY PCB (may be not shown clearly). If you’ve an Arduino UNO or similar board (any 5V board) then you must use the voltage divider resistors!

  3. Hi! I’m having some trouble while uploading the code to my Arduino Uno.

    Arduino:1.8.11 Hourly Build 2019/12/30 10:12 (Mac OS X), Tarjeta:”Arduino Uno”

    In file included from /Users/lesu/Documents/Arduino/libraries/Adafruit_ST7735_and_ST7789_Library-1.5.13/Adafruit_ST7789.h:4:0,
    from /Users/lesu/Documents/Arduino/Display_ST7789/Display_ST7789.ino:2:
    /Users/lesu/Documents/Arduino/libraries/Adafruit_ST7735_and_ST7789_Library-1.5.13/Adafruit_ST77xx.h:31:10: fatal error: Adafruit_SPITFT.h: No such file or directory
    #include
    ^~~~~~~~~~~~~~~~~~~
    compilation terminated.
    exit status 1

    Do you know what this means? I’ve tried deleting the libraries and installing them but that doesn’t seem to solve my problem.

    Also, I’d like to ask is there any change if instead of using resistors as suggested I use a level converter por the digital inputs?
    https://es.aliexpress.com/wholesale?catId=0&initiative_id=&origin=y&SearchText=arduino+level+converter

    Thanks for your help!!

    1. Hi again, finally I could solve it by my own. I’ll leave what I did in case someone else has the same problem.

      Basically when I downloaded the libraries I chose the option “Download all Adafruit libraries”. Apparently one of the other libraries was causing trouble. To solve it I deleted the libraries following the steps described in this page https://forum.arduino.cc/index.php?topic=295275.0

      Once I did that, I installed only the libraries that are recommended in this tutorial and the compiling was perfect.

      Finally, I used a level converter that let me decrease the voltage without using resistors!

    1. Use voltage divider formula and you’ll get 3 Volts (not 2 Volts):
      Vout (goes to ST7789 TFT) = 5V (from Arduino output pin) x 3.3k/(3.3k + 2.2k) = 5 x 3.3/5.5 = 3 volts.

    2. Some microcontrollers output high 3.3 instead of 5. This voltage divider gives 2,2 if so and yes probably be too low to work. Set a pin high and check without voltage divider. If voltage >3 and <3.3 you will not need to use a voltage divider. It might not be a bad idea to just remove the 3.3K resistor and let the 2.2K resistor cut down the current.

  4. That’s what i finaly thought, you just confirm to me i had did a terrible newbie mistake ;-( After following all your instruction screen was working fine for months.. But backlight was too strong for me during night, so i wanted to try connect BLK to GROUND as you suggere…. But i had your setup with BLK connect to vcc 3.3v, what make me confused and did not think about switching with ground (maybe should be good to precise for others newbees like me).. So i thought maybe there is some protection inside arduino or some funcion i ignore.. But no !! you confirm to me i did a short circuit ;-)). I burn the TFT, and after check i burned some pins of arduino too, and my relay module ;-((

    The good news of this story is i had learned of my mistake and never do it again 😉 and in 1 month i receive the new screen for my clock alarm v2 😉

    So thank you.. It’s not easy to find information about thoses screen and BLK funccion.. Can we use a potentiometer to ajust luminosity ? (The strange things with my short circuit story is that TFT funccion display burnout but no the led, i still have light).
    I saw a man using tft reset pin : pinmode(reset,output);
    analogWrite(reset,true), delay(200);analogwrite(reset,false) for software simulate of BLK, i try it but it only switch off the display, some light was still there. So i wanted to try something with analogwrite to send 3,3v or 0v (i did not found any information about that)..
    Do you know what the reset is use for ? Just reset display i suppose…

    So thanks again, you are the only one to have such a good and almost full explanation with how to use thoses screen..

    Nicolas from france !

  5. After long time this working for me, i wanted to use BLK, so i connect it to Ground… and my screen is dead now (but not sure it’s the cause).. but now something make me confuse, you connect BLK to GND, so it means connect GND direct with 3.3v on arduino (BLK is connected to 3.3v), how can’t it damage it ?

    1. The BLK pin is just for the back light LED. If it is connected to VCC (+3.3V) or left unconnected the backlight will be ON and if it is connected to GND the backlight will be OFF. You cannot connect it to VCC and GND at the same time because you will do a short circuit and even your Arduino board may be damaged!
      Connecting the display to 5V may damage it (power supply or data lines), that’s why the voltage dividers are used!
      Also reversing the polarity of the 3.3V power supply may damage it.

    1. Bhaaskar Rajarajan

      For colour issue in china display you need to change spi mode in two places

      Adafruit_ST77xx.h

      //spiMode = SPI_MODE0; ///< Certain display needs MODE3 instead
      spiMode = SPI_MODE3; ///< Certain display needs MODE3 instead

      Adafruit_ST7789.h

      void init(uint16_t width, uint16_t height, uint8_t spiMode = SPI_MODE3);

      i faced colour issue, that display purchased in aliexpress

      after long studies i done above modification

      now works

      Just tested today (24/12/2019)

      1. Instead of this modification you may just set SPI mode in the main code, for example:
        tft.init(240, 240, SPI_MODE3);
        Can you give us a picture of your display (or Aliexpress link)?

          1. Bhaaskar Rajarajan

            Hi friends

            i am unlucky to use this display, i think so.

            the same program i used and removed all content like draw lines, circles, like all by one by one the display works in all stage. finally when removing testroundrectangle(); function the display gone half.

            if i am using this in the program display works good

            so i included the function to execute first, like when power on test round rectangle will come then my project content will comes net. like power up screen

            then i decided to copy the program from following link

            http://simple-circuit.com/tft-st7789-arduino-dht11-sensor/

            directly i uploaded but the display direction is not good

            same parameters used in the program like spimode 3 setrotation 2 etc but different result

            kindly suggest me some idea still my project is in first phase

          2. This code _as it is_ should work perfectly and without any problem!
            Try with the following:
            Update Adafruit ST7735/ST7789 library (current version 1.5.9),
            Update Adafruit graphics library (current version 1.7.3),
            You can update both libraries using Arduino IDE library manager (Tools —> Manage Libraries…).
            And try using the latest version of Arduino IDE (current version 1.8.10).

          3. Bhaaskar Rajarajan

            Thanks friend,

            i am new to Arduino and really happy you all reply immediately.

            really works after update. its miracle

            one program working on old file another working in new one. now i tested both program after update working fine

  6. Hello, i tested it with Arduino Micro Pro. As is described, it was not working. After change Res to pin 9, DC to pin 8, BLK to pin 10 is now working nice. Thank for inspiration.

    1. I cannot connect mine to the arduino as it has come with a white plug with 8 wires , i cant find a pinout drawing to let me connect

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Scroll to Top