esp-idf-st7789

ST7789 Driver for esp-idf

The demo video by Dmitry Andreev.
https://www.youtube.com/watch?v=aOyaK0pUiPk&t

Software requirements

ESP-IDF V5.0 or later.
ESP-IDF V4.4 release branch reached EOL in July 2024.

Note for ESP32-C6
ESP-IDF V5.1 is required when using ESP32-C6.

Installation

git clone https://github.com/nopnop2002/esp-idf-st7789
cd esp-idf-st7789/
idf.py set-target {esp32/esp32s2/esp32s3/esp32c2/esp32c3/esp32c6}
idf.py menuconfig
idf.py flash

Note for ESP32-S2/ESP32-C2
The tjpgd library is not included in the ESP32-S2/ESP32-C2 ROM.
However, you can use this IDF component registry.
JPEG files can be displayed.

Note for ESP32-C2
ESP32-C2 has less SRAM, so JPEG and PNG may not be displayed on higher resolution TFTs.

E (256560) decode_jpeg: Error allocating memory for line 251
E (260630) pngle_new: Error allocating memory for line 160

BMP file

JPEG file(ESP32/ESP32S2/ESP32C3)

PNG file

QR-CODE

PNG icon

Configuration

Generic ST7789 1.3 Inch

There is 2 kinds of marking.
The pin marking is written as SCL/SDA, so it looks like i2c, but it is SPI.
SCL is SCLK, SDA is MOSI.

Note for display remains black
This module may require a large current to reset.
This may be improved by following the steps below.

Pull up RES with 100 ohms.
Write the firmware.
Press the reset button several times.

Generic ST7789 1.14 Inch

Generic ST7789 1.54 Inch (Non IPS)

Left:1.54inch Right:1.3inch

Generic ST7789 1.9 Inch (Non IPS)

Generic ST7789 2.0 Inch (Non IPS)

Left:2.0inch Right:1.54inch

Generic ST7789 2.4 Inch (Non IPS)

Left:2.4inch Right:2.0inch

Generic ST7789 2.8 Inch (Non IPS)

Left:2.4inch Right:2.8inch

LILYGO TTGO 1.14 Inch ESP32

LILYGO TTGO T8 ESP32-S2

Custom PCB

Click here for more information.

SPI Clock speed

According to the ST7789 datasheet, the minimum SPI clock cycle time is 16ns.
Therefore, the maximum SPI clock frequency is 62.5MHz.
The SPI clock frequency used by this project is 20MHz.
Higher SPI clock frequencies can be specified using spi_clock_speed().
When using higher SPI clock frequencies, you need to be careful about the length of the wire cable.

    //int speed = 40000000; // 40MHz
    int speed = 60000000; // 60MHz
    spi_clock_speed(speed);
    spi_master_init(&dev, CONFIG_MOSI_GPIO, CONFIG_SCLK_GPIO, CONFIG_CS_GPIO, CONFIG_DC_GPIO, CONFIG_RESET_GPIO, CONFIG_BL_GPIO);
    lcdInit(&dev, CONFIG_WIDTH, CONFIG_HEIGHT, CONFIG_OFFSETX, CONFIG_OFFSETY);

Benchmarking using ESP32@240 & 1.3 inch TFT Without Frame Buffer.
Clock up has little effect.

	20MHz	40MHz	60MHz
FillTest	1150	1090	1090
ColorBarTest	50	50	50
ArrowTest	280	250	250
LineTest	2190	2150	2150
CircleTest	1940	1910	1910
RoundRectTest	1980	1940	1940
DirectionTest	450	430	430
HorizontalTest	1070	1040	1040
VerticalTest	1070	1040	1040
FillRectTest	190	150	150
ColorTest	260	220	220
CodeTest	1070	1040	1040
BMPTest	7160	7130	7130
JPEGTest	2550	2530	2530
PNGTest	2850	2830	2830
QRTest	220	170	170

Benchmarking using ESP32@240 & 1.3 inch TFT With Frame Buffer.
The effect of clocking up varies depending on the test case.

	20MHz	40MHz	60MHz
FillTest	1150	1090	1090
ColorBarTest	70	50	50
ArrowTest	60	30	30
LineTest	50	30	30
CircleTest	60	30	30
RoundRectTest	50	30	30
DirectionTest	60	40	40
HorizontalTest	70	50	50
VerticalTest	70	50	50
FillRectTest	60	30	30
ColorTest	60	50	30
CodeTest	100	80	50
BMPTest	2220	2190	2190
JPEGTest	2570	2550	2550
PNGTest	2860	2840	2840
QRTest	190	170	170

SPI BUS selection

The ESP32 series has three SPI BUSs.
SPI1_HOST is used for communication with Flash memory.
You can use SPI2_HOST and SPI3_HOST freely.
When you use SDSPI(SD Card via SPI), SDSPI uses SPI2_HOST BUS.
When using this module at the same time as SDSPI or other SPI device using SPI2_HOST, it needs to be changed to SPI3_HOST.
When you don't use SDSPI, both SPI2_HOST and SPI3_HOST will work.
Previously it was called HSPI_HOST / VSPI_HOST, but now it is called SPI2_HOST / SPI3_HOST.

Using Frame Buffer

When FrameBuffer is enabled, all output will be stored in the internal FrameBuffer and reflected to the device with lcdDrawFinish.
If you don't use FrameBuffer, lcdDrawFinish does nothing.
If your main purpose is to display text, it's well worth using FrameBuffer.
If your main purpose is to display images, there is no value in using FrameBuffer.
Enabling FrameBuffer does not make image display faster.
This is because image analysis takes time.
ESP32-C2 has too small memory to use this function.
Note that using FrameBuffer consumes memory.
Memory allocate errors may occur with TFTs with large resolutions.

ESP32-S2 has less SRAM, but some ESP32-S2 have PSRAM.
If your SoC has PSRAM, you can avoid running out of memory by enabling PSRAM.

Benchmarking using ESP32@240 & 1.3 inch TFT

	Disable Frame Buffer	Enable Frame Buffer
FillTest	1150	1150
ColorBarTest	50	70
ArrowTest	280	60
LineTest	2190	50
CircleTest	1940	60
RoundRectTest	1980	50
DirectionTest	450	60
HorizontalTest	1070	70
VerticalTest	1070	70
FillRectTest	190	60
ColorTest	260	60
CodeTest	1070	70
BMPTest	7160	2220
JPEGTest	2550	2570
PNGTest	2850	2860
QRTest	220	190

JPEG Decoder

The ESP-IDF component includes Tiny JPEG Decompressor.
The document of Tiny JPEG Decompressor is here.
This can reduce the image to 1/2 1/4 1/8.

PNG Decoder

The ESP-IDF component includes part of the miniz library, such as mz_crc32.
But it doesn't support all of the miniz.
The document of miniz library is here.

And I ported the pngle library from here.
This can reduce the image to any size.

Font File

This project uses the following as default fonts:

font/ILGH16XB.FNT // 8x16Dot Gothic
font/ILGH24XB.FNT // 12x24Dot Gothic
font/ILGH32XB.FNT // 16x32Dot Gothic
font/ILMH16XB.FNT // 8x16Dot Mincyo
font/ILMH24XB.FNT // 12x24Dot Mincyo
font/ILMH32XB.FNT // 16x32Dot Mincyo

From 0x00 to 0x7f, the characters image of Alphanumeric are stored.
From 0x80 to 0xff, the characters image of Japanese are stored.
Changing this file will change the font.

You can add your original fonts.
The format of the font file is the FONTX format.
Your font file is put in font directory.
When you build the firmware, the font files are uploaded to the SPIFFS partition.

Please refer this page about FONTX format.

Font File Editor(FONTX Editor)

There is a font file editor.
This can be done on Windows 10.
You can create your own font files.
Developer page is here.

Convert from BDF font to FONTX font

step1)
download Font File Editor(FONTX Editor) from here.

step2)
download BDF font file from Internet.
I downloaded from here.
fontxedit.exe can ONLY import Monospaced bitmap fonts file.
Monospaced bitmap fonts can also be downloaded here.

step3)
import the BDF font file into your fontxedit.exe.
this tool can convert from BDF to FONTX.

step4)
adjust font size.

step5)
check font pattern.
when you have made any changes, press the apply button.

step6)
save as .fnt file from your fontedit.exe.

step7)
upload your font file to $HOME/esp-idf-st7789/fonts directory.

step8)
add font to use

FontxFile fx32L[2];
InitFontx(fx32L,"/spiffs/LATIN32B.FNT",""); // 16x32Dot LATIN

Font file that From 0x80 to 0xff, the characters image of Japanese are stored.

Font file that From 0x80 to 0xff, the characters image of Latin are stored.

u8g2 library contains many BDF fonts.
This is a 24x24 font converted from emoticons21.bdf.

This is a 16x16 font converted from Scroll-o-Sprites.bdf.

Convert from TTF font to FONTX font

step1)
Download WFONTX64.exe from here. Developer page is here.

step2)
Select ttf font.
Please note that if you select a proportional font, some fonts may not convert correctly.
If you select a proportional font, some fonts will need to be modified using fontxedit.exe.
Monospaced fonts can be converted correctly.
You can find Monospaced fonts here.

step3)
Enter Height, Width, FontX2 name.
Specify half of Height for Width.
Specify your favorite font name in the FontX2 name field using up to 8 characters.

step4)
Specify the file name to save.

step5)
Specify the font style as required.

step6)
Press the RUN button to convert TTF fonts to FONTX format.

step7)
upload your font file to $HOME/esp-idf-st7789/fonts directory.

step8)
add font to use

    FontxFile fx16G[2];
    FontxFile fx24G[2];
    FontxFile fx32G[2];
    //InitFontx(fx16G,"/spiffs/ILGH16XB.FNT",""); // 8x16Dot Gothic
    //InitFontx(fx24G,"/spiffs/ILGH24XB.FNT",""); // 12x24Dot Gothic
    //InitFontx(fx32G,"/spiffs/ILGH32XB.FNT",""); // 16x32Dot Gothic
    InitFontx(fx16G,"/spiffs/Gigi16.FNT",""); // 8x16Dot Gigi
    InitFontx(fx24G,"/spiffs/Gigi24.FNT",""); // 12x24Dot Gigi
    InitFontx(fx32G,"/spiffs/Gigi32.FNT",""); // 16x32Dot Gigi

How to add your color

Change here.

#define RED    rgb565(255,   0,   0) // 0xf800
#define GREEN  rgb565(  0, 255,   0) // 0x07e0
#define BLUE   rgb565(  0,   0, 255) // 0x001f
#define BLACK  rgb565(  0,   0,   0) // 0x0000
#define WHITE  rgb565(255, 255, 255) // 0xffff
#define GRAY   rgb565(128, 128, 128) // 0x8410
#define YELLOW rgb565(255, 255,   0) // 0xFFE0
#define CYAN   rgb565(  0, 156, 209) // 0x04FA
#define PURPLE rgb565(128,   0, 128) // 0x8010

How to use this component in your project

Create idf_component.yml in the same directory as main.c.

YourProject --+-- CMakeLists.txt
              +-- main --+-- main.c
                         +-- CMakeLists.txt
                         +-- idf_component.yml

Contents of idf_component.yml.

dependencies:
  nopnop2002/st7789:
    path: components/st7789/
    git: https://github.com/nopnop2002/esp-idf-st7789.git

When you build a projects esp-idf will automaticly fetch repository to managed_components dir and link with your code.

YourProject --+-- CMakeLists.txt
              +-- main --+-- main.c
              |          +-- CMakeLists.txt
              |          +-- idf_component.yml
              +-- managed_components ----- nopnop2002__st7789

External input module

You can use these if you need some input.

MPR121 Capacitive Touch switch
https://github.com/nopnop2002/esp-idf-mpr121
TTP229 Capacitive Touch switch
https://github.com/nopnop2002/esp-idf-ttp229

License

nopnop2002/esp-idf-st7789

ErrorLooks like something went wrong!

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 5

Languages

Error
Looks like something went wrong!

Packages