ESP32 TFT display library

[loboris]

TFT library for ESP32

https://github.com/loboris/ESP32_TFT_library


Features

• Full support for ILI9341 & ILI9488 based TFT modules in 4-wire SPI mode. Support for other controllers will be added later
• 18-bit (RGB) color mode used
• SPI displays oriented SPI driver based on spi-master driver. Does not use queues like spi-master to improve speed.
• Combined DMA SPI transfer mode and direct SPI to improve speed
• Grayscale mode can be selected during runtime which converts all colors to gray scale
• SPI speeds up to 40 MHz are tested and works without problems
• Demo application included which demonstrates most of the library features

Graphics drawing functions

• TFT_drawPixel Draw pixel at given x,y coordinates
• TFT_drawLine Draw line between two points
• TFT_drawFastVLine, TFT_drawFastHLine Draw vertical or horizontal line of given lenght
• TFT_drawLineByAngle Draw line on screen from (x,y) point at given angle
• TFT_drawRect, TFT_fillRect Draw rectangle on screen or fill given rectangular screen region with color
• TFT_drawRoundRect, TFT_fillRoundRect Draw rectangle with rounded corners or fill given rectangular screen region with rounded corners
• TFT_drawCircle, TFT_fillCircle Draw or fill circle on screen
• TFT_drawEllipse, TFT_fillEllipse Draw or fill ellipse on screen
• TFT_drawTriangel, TFT_fillTriangle Draw or fill triangle on screen
• TFT_drawArc Draw circle arc on screen, from start angle to end angle, with given thickness. Can be outlined with different color
• TFT_drawPolygon Draw poligon on screen with given number of sides (3~60). Can be outlined with different color and rotated by given angle.

Fonts

• fixed width and proportional fonts are supported; 8 fonts embeded
• unlimited number of fonts from file
• 7-segment vector font with variable width/height is included (only numbers and few characters)
• Proportional fonts can be used in fixed width mode.
• Related functions:
  • TFT_setFont Set current font from one of embeded fonts or font file
  • TFT_getfontsize Returns current font height & width in pixels.
  • TFT_getfontheight Returns current font height in pixels.
  • set_7seg_font_atrib Set atributes for 7 segment vector font
  • getFontCharacters Get all font's characters to buffer

String write function

• TFT_print Write text to display.
• Strings can be printed at any angle. Rotation of the displayed text depends on font_ratate variable (0~360)
• if font_transparent variable is set to 1, no background pixels will be printed
• If the text does not fit the screen/window width it will be clipped ( if text_wrap=0), or continued on next line ( if text_wrap=1)
• Two special characters are allowed in strings: \r (CR, 0x0D), clears the display to EOL, \n (LF, 0x0A), continues to the new line, x=0
• Special values can be entered for X position:
  • CENTER centers the text
  • RIGHT right justifies the text horizontaly
  • LASTX continues from last X position; offset can be used: LASTX+n
• Special values can be entered for Y:
  • CENTER centers the text verticaly
  • BOTTOM bottom justifies the text
  • LASTY continues from last Y position; offset can be used: LASTY+n
• TFT_getStringWidth Returns the string width in pixels based on current font characteristics. Useful for positioning strings on the screen.
• TFT_clearStringRect Fills the rectangle occupied by string with current background color

Images

• TFT_jpg_image Decodes and displays JPG images
• Limits:
  • Baseline only. Progressive and Lossless JPEG format are not supported.
  • Image size: Up to 65520 x 65520 pixels
  • Color space: YCbCr three components only. Gray scale image is not supported.
  • Sampling factor: 4:4:4, 4:2:2 or 4:2:0.
• Can display the image from file or memory buffer
• Image can be scaled by factor 0 ~ 3 (1/1, 1/2, 1/4 or 1/8)
• Image is displayed from X,Y position on screen/window:
  • X: image left position; constants CENTER & RIGHT can be used; negative value is accepted
  • Y: image top position; constants CENTER & BOTTOM can be used; negative value is accepted
• TFT_bmp_image Decodes and displays BMP images
• Only uncompressed RGB 24-bit with no color space information BMP images can be displayed
• Can display the image from file or memory buffer
• Image can be scaled by factor 0 ~ 7; if scale>0, image is scaled by factor 1/(scale+1)
• Image is displayed from X,Y position on screen/window:
  • X: image left position; constants CENTER & RIGHT can be used; negative value is accepted
  • Y: image top position; constants CENTER & BOTTOM can be used; negative value is accepted

Window functions

• Drawing on screen can be limited to rectangular window, smaller than the full display dimensions
• When defined, all graphics, text and image coordinates are translated to window coordinates
• Related functions
  • TFT_setclipwin Sets the window area coordinates
  • TFT_resetclipwin Reset the window to full screen dimensions
  • TFT_saveClipWin Save current window to temporary variable
  • TFT_restoreClipWin Restore current window from temporary variable
  • TFT_fillWindow Fill window area with color

Touch screen

• for now only XPT2046 and compatible controllers are supported
• TFT_read_touch Detect if touched and return X,Y coordinates. Raw touch screen or calibrated values can be returned.
• calibrated coordinates are adjusted for screen orientation.

Read from display memory

• TFT_readPixel Read pixel color value from display GRAM at given x,y coordinates.
• TFT_readData Read color data from rectangular screen area

Other display functions

• TFT_fillScreen Fill the whole screen with color
• TFT_setRotation Set screen rotation; PORTRAIT, PORTRAIT_FLIP, LANDSCAPE and LANDSCAPE_FLIP are supported
• TFT_invertDisplay Set inverted/normal colors
• TFT_compare_colors Compare two color structures
• disp_select() Activate display's CS line
• disp_deselect() Deactivate display's CS line
• find_rd_speed() Find maximum spi clock for successful read from display RAM
• TFT_display_init() Perform display initialization sequence. Sets orientation to landscape; clears the screen. SPI interface must already be setup, tft_disp_type, _width, _height variables must be set.
• HSBtoRGB Converts the components of a color, as specified by the HSB model to an equivalent set of values for the default RGB model.
• compile_font_file Function which compiles font c source file to binary font file which can be used in TFT_setFont() function to select external font. Created file has the same name as source file and extension .fnt

Global wariables

• orientation current screen orientation
• font_rotate current font rotate angle (0~395)
• font_transparent if not 0 draw fonts transparent
• font_forceFixed if not zero force drawing proportional fonts with fixed width
• text_wrap if not 0 wrap long text to the new line, else clip
• _fg current foreground color for fonts
• _bg current background for non transparent fonts
• dispWin current display clip window
• _angleOffset angle offset for arc, polygon and line by angle functions
• image_debug print debug messages during image decode if set to 1
• cfont Currently used font structure
• TFT_X X position of the next character after TFT_print() function
• TFT_Y Y position of the next character after TFT_print() function
• tp_calx touch screen X calibration constant
• tp_caly touch screen Y calibration constant
• gray_scale convert all colors to gray scale if set to 1
• max_rdclock current spi clock for reading from display RAM
• _width screen width (smaller dimension) in pixels
• _height screen height (larger dimension) in pixels
• tft_disp_type current display type (DISP_TYPE_ILI9488 or DISP_TYPE_ILI9341)

Full functions syntax and descriptions can be found in tft.h and tftspi.h files.
Full demo application, well documented, is included, please analyze it to learn how to use the library functions.


Connecting the display

To run the demo, attach ILI9341 or ILI9488 based display module to ESP32. Default pins used are:

• mosi: 23
• miso: 19
• sck: 18
• CS: 5 (display CS)
• DC: 26 (display DC)
• TCS: 25 (touch screen CS)

If you want to use different pins, change them in tftspi.h

if you want to use the touch screen functions, set #define USE_TOUCH 1 in tftspi.h

Using make menuconfig select tick rate 1000 ( → Component config → FreeRTOS → Tick rate (Hz) ) to get more accurate timings


How to build

Configure your esp32 build environment as for other ESP32 projects and esp-idf examples.

Clone the repository

Code: Select all

git clone https://github.com/loboris/ESP32_TFT_library.git

Execute menuconfig and configure your Serial flash config and other settings. Included sdkconfig.defaults sets some defaults to be used.
Navigate to TFT Display DEMO Configuration and set SPIFFS options (or just use defaults, recommended for this demo).
Select if you want to use wifi to get the time from NTP server and set your WiFi SSID and password.

Code: Select all

make menuconfig

Make and flash the example.

Code: Select all

make all && make flash

Prepare SPIFFS image

The demo uses some image and font files and it is necessary to flash the spiffs image

To flash already prepared image (components/spiffs_image/image/spiffs_image.img), execute:

Code: Select all

make copyfs

You can also prepare different SFPIFFS image and flash it to ESP32 if you want to include your own files.
Tested and works under Linux, Windows and Mac OS.

Files to be included on spiffs are in components/spiffs_image/image/ directory. You can add more files or remove the existing files.

When the file system content is prepared, execute:

Code: Select all

make makefs

to create spiffs image in build directory without flashing to ESP32.

Or execute:

Code: Select all

make flashfs

to create spiffs image in build directory and flash it to ESP32

More info about using SPIFFS on ESP32: viewtopic.php?f=18&t=1901&p=8924#p8924

[loboris]

The library is updated:

• SPI driver optimized, DMA functionality improved
• Low lewel display SPI functions optimized for speed
• 16-bit color mode removed
• Improved BMP decoding, up to 2x higher speed
• Fonts drawing speed for non transparent, not rotated fonts improved 2~3 times
• All functions optimized to use DMA transfer where possible
• Some bugs fixed
• Some functions added
• Demo application updated with new and improved examples
• Documents folder added with some documentation

[JanJansen47]

TFT Display type: ER-TFTM035-6
http://www.buydisplay.com/default/lcd-3 ... kout-board


The TFT display works great with your new library. When I tested the XPT2046 touch controller (on-board) I did not see any response.
I followed the trail from TFT_read_touch() up to touch_get_data() but could not find a clue.

Yes I wired / tested the SDO, SDI and SCL from both the TFT panel and the XPT2046 together and used the default CS. The jumpers on the board are in the correct positions.

Any idea?

[loboris]

@JanJansen47

I have the same display, but with capacitive touch panel (I'll add the driver soon), so I can't test it.
I've only tested the touch panel with 2.4" ILI9431 based display from eBay, and it works.

On ER-TFTM035-6 the Touch panel CS pin is on interface pin #30, the controller is XPT2046, so it should work.
Have you enabled the touch fonctions in tftspi.h (#define USE_TOUCH 1) ?

If you make it work, keep in mind that the default calibration constatnts are for 2.4" touch panel, and you probably won't get the right calibrated values. I'll try to add the calibration function soon.

BDW, have you noticed that you can use GPIO to drive this display's backlit (interface pin #29).

[JanJansen47]

HI Loboris,

Yes I'm, controlling the backlight. As there is no drawing of the device I'm assuming ( and measured) the scl, sdi and sdo for TFT and touch are not connected to each other. I used sdo 28 connected with 32, 27 with 34 and 24 with 33.

[JanJansen47]

I measured the signals with a scope and found a strange signal on the SDO from TFT and Touch (same line). I disconnected the SDO connection from the TFT and directly wired it to the Touch.
At least TFT and touch is working for now. ;) But it does not feel okay. So I ask the supplier.
My wiring is available on request.

[flashpackets]

I'm happy to report that this library works great with absolutely no issues in regard to running with Eclipse. Very nice work!! Once I hooked up the D/C line according to the wiring diagram the display, a 1.44 SPI 128x128 worked great.

I can't seem to find the magic switch that inverts the fonts. I observe that there is a change in the left right orientation of the characters using PORTRAIT and PORTRAIT_FLIP, however the characters are always upside down So a "W" looks like an "M" etc.

Oh, what to do? What is the secret switch that puts everything right?

[loboris]

I'm happy to report that this library works great with absolutely no issues in regard to running with Eclipse. Very nice work!! Once I hooked up the D/C line according to the wiring diagram the display, a 1.44 SPI 128x128 worked great.

I can't seem to find the magic switch that inverts the fonts. I observe that there is a change in the left right orientation of the characters using PORTRAIT and PORTRAIT_FLIP, however the characters are always upside down So a "W" looks like an "M" etc.

Oh, what to do? What is the secret switch that puts everything right?

Your display probably has ST7735 controller which has different initialization sequence and orientation commands.
I'll try to add it to the library this week...

[kearins]

I have successfuly tested TFT 1.8" 128x160 ST7735S (black label) with following settings:
#define TFT_INVERT_ROTATION1 1
#define TFT_RGB_BGR 0x00
#define DEFAULT_TFT_DISPLAY_WIDTH 160
#define DEFAULT_TFT_DISPLAY_HEIGHT 128
#define DEFAULT_SPI_CLOCK 32000000
#define DEFAULT_DISP_TYPE DISP_TYPE_ILI9488
At spi clock 40Mhz there are artefacts on the screen, so I've stepped down to 32 Mhz.
But I can't makefs/flashfs

Code: Select all

$make makefs
make: *** no rule to make target 'makefs'

Thanks, loboris, excellent work.

[kearins]

I found why 'make makefs' does not work.
1) These files are absent:

Code: Select all

components\mkspiffs\component.mk
components\spiffs_image\component.mk

2) Lines in components\spiffs_image\Makefile.projbuild

Code: Select all

.PHONY: flashfs
.PHONY: makefs
.PHONY: copyfs

should be changed to one line

Code: Select all

.PHONY: flashfs makefs copyfs

3) Replace the whole directory 'components\mkspiffs\' with one from https://github.com/loboris/ESP32_spiffs_example to get rid of compile errors.