Connecting 4″ 480×320 ST7796 LCD module to ESP8266

We have ST7796 driven LCD modules. Display has diameter 4″ and resolution 480×320. This module has also resistive touch screen, but in this post we wont cover touch controls, just using LCD.

Our module can be powered with 5V but data lines are not 5V tolerant. Since we will use ESP8266 there is no problem, but if You’d like to connect it to some older Arduino – then logic level converter is a must.

Ok, so connections ar as follow:

ESP8266 Arduino pins	ESP8266 GPIO	LCD module pin
3.3V		LED
D5	14	SCK
D7	13	SDI(MOSI)
D3	0	DC/RS
D4	2	RESET
D2	4	CS
GND	GND	GND
5V		VCC

OK, so we have connected it. Now software part. There are two libraries which can be used. One is Arduino GFX and second is TFT_eSPI. I got both running, but while Arduino GFX was working well I was unable to display image. Displaying text works w/o problems, just image fails despite of different formats tries. Since TFT_eSPI was working OK I have stopped trying GFX display my image.

At the end I’m attaching Platformio project with two targets: one using Arduino GFX and second using TFT_eSPI. You can easily start from there. From main.cpp depending on platformio environment is included one of two files etft.h or libGFX.h.

ST7796 with TFT_eSPI (etft.h)

This library I would probably use in own project – first seems to be working better with pictures, has interesting examples and it’s a bit faster. On ESP32 it promises working with DMA, could be interesting to see what can be done in terms of speed.

Configuring library depends on environment. For Platformio it’s done through variables set in platformio.ini. You need set build flags, first is

build_flags =
    -DUSER_SETUP_LOADED=1

When USER_SETUP_LOADED is set, then library does not include configs, and all needed parameters can be set through next defines. Complete list for connection presented earlier is:

    -DST7796_DRIVER=1
    -DTFT_WIDTH=320
    -DTFT_HEIGHT=480
    -DTFT_MISO=12
    -DTFT_MOSI=D2
    -DTFT_SCLK=14
    -DTFT_CS=4
    -DTFT_DC=0
    -DTFT_RST=2
    -DLOAD_GLCD=1
    -DLOAD_FONT2=1
    -DLOAD_FONT4=1
    -DLOAD_FONT6=1
    -DLOAD_FONT7=1
    -DLOAD_FONT8=1
    -DLOAD_GFXFF=1
    -DSMOOTH_FONT=1
    -DSPI_FREQUENCY=40000000

If your preferred environment is Arduino IDE, then you need to update files in libraries folder. Find TFT_eSPI installation folder and there is a directory UserSetups. For ST7796 closest one is number 28. You just need to comment out #define RPI_DISPLAY_TYPE. Then just include file right after TFT_eSPI include:

#include <TFT_eSPI.h>
#include <User_Setups/Setup28_RPi_ST7796_ESP8266.h>

Remember, that after You update TFT_eSPI library (or IDE will do it on your behalf) changes will be lost. As library autor recommends you can create new folder in Arduino sketches folder and place there copy of setup and include it form sketch like this:

#include "../YOUR_CONFIG_FOLDER/tft_espi_config.h"

So, after You configured library to use proper config You can start working with LCD. In case you can not get display running at all or display is distorted, you can see setupDebug.h file how to display onto Serial current library configuration. Just include file and all testSetup() from config. Then You can verify if correct pins are configured in library.

All operations on LCD are through object, You need to create:

TFT_eSPI tft = TFT_eSPI();

For me LCD init was done as follow:

    tft.init();
    tft.setRotation(1);
    tft.fillScreen(TFT_BLACK);

Have you noticed that standard orientation for LCD is size 320×480 (TFT_WIDTH=320)? Using setRotation you can adjust how all is being displayed. There are 4 rotations, two for vertical and two for horizontal.

For sake of this example I have stored image in flash, as PROGMEM variable. If You want to convert image into variable you may use this file to C array converter online. On attached screenshot You can see what settings was used to get correct image on screen:

Image is being pushed to display by pushImage it can be done in one step.

ST7796 and Arduino GFX library (libGFX.h)

Second target in attached project used Arduino GFX library. This library is a bit slower, but (especially for less advanced users) easier to configure. Using it on ESP8266 we will relay on hardware SPI controller and thus first we create data bus object. Since it uses predefined SPI pins on ESP You need only provide two parameters. These are pins used for Data/Command (DC) and Chip Select (CS). Next using this bus object you create instance of class supporting ST7796 controller:

Arduino_DataBus *bus = new Arduino_HWSPI(D3 /* DC */, D2 /* CS */);
Arduino_GFX *gfx = new Arduino_ST7796(bus, D4 /* RST */);

As I wrote before I was not able to get images on screen, so example just clears LCD and writes classic Hello world sentence. That’s it.

    gfx->begin(40000000);
    gfx->setRotation(1);
    gfx->fillScreen(BLACK);
    gfx->println("Hello World!");

For both libraries example code is attached in archive for download.