TFT_eSPI library documentation

[SALLDHMF]

Hello! In my current project, I use ESP32 and display with ILI9341. I would like to use your library, but - as a beginner - I have a lot of trouble with that. Is there somewhere documentation that describes the operation of all library functions? Eg: tft.drawString (.....) has four parameters, but what? What is the text datum? ...
Of course, I will laboriously find explanations in the examples. But if there is documentation, it will be easier and faster.

Tomasz

[Bodmer]

Writing support documentation has been on my "To Do" list for a long time. It would take many hours to do this and at the moment I am busy with paid work. I can help with more specific questions that have short answers!

[SALLDHMF]

I understand you. Years ago, I wrote a lot of code. These were Pascal and assembler times :-). I quickly learned to comment very accurately at the time of writing. I know that in the future I won't have time for this.

Yes. I have a specific problem, although I don't know if it will be a "short answer" ;-)

With the help of your library, I can use several types of fonts. I can't handle them. The examples show the use of different types, but never all at once. Sometimes the files needed to use them are in the sample script folders. I can't handle setting up my own script with Local custom fonts, Free Fonts, TrueType fonts....

There are also many ways to use them:

tft.setTextSize (1);
tft.setTextColor (TFT_GREEN, TFT_BLACK);
tft.setFreeFont (MYFONT32)

tft.drawString ("rpm", 5, 20, 2);
tft.drawString (TEST_TEXT, 160, 140, GFXFF);
tft.print ("AAAA");

It's probably not all font functions. Which fonts does it apply to?

I would be grateful if you could help me learn how to use fonts.

[Bodmer]

I have sympathy for you as there are so many options.

The library is based on an old (2015) version of the Adafruit_ILI9341 + GFX library. At he time the library only had a very simple small 7x5 bitmap font which was not nice when scaled up and used on TFTs, so I created a new font format and published the library for the humble UNO here. This introduced the concept of numbered fonts. The original Adafruit bitmap being Font 1. The ones I added were Fonts 2, 4, 6, 7 and 8. Each one having increasing size and font 7 being a 7 segment font. To use say font 4 you then just use:
tft.setFont(4); // The 4 is the font
tft.drawString ("Testing 1234", xpos, ypos);

An alternative to these two lines is:
tft.drawString ("Testing 1234", xpos, ypos, 4); // The 4 is the font

The "TFT_Rainbow_one_lib" example would be a good one to look at.

Adafruit finally decided to add a new font format that I call Free Fonts. To retain compatibility with the Adafruit library I added these. To use these fonts you need to use for example:

tft.setFreeFont (MYFONT32); // Select the free font
tft.drawString ("Testing 1234", xpos, ypos); // The font number is missing here to use the Free Font

Unfortunately the Free Fonts do not render well in small sizes as they tend to have jagged edges due to stray pixels on curves (usually 8's look terrible). Since the ESP8266 and ESP32 have SPIFFS I had a light bulb moment and realised that anti-aliased fonts could be accommodated. To use these you have to load the font first as shown in Font Demo 1,2,3,4. For example:

tft.loadFont(AA_FONT_SMALL); // Must load the font first
tft.drawString ("Testing 1234", xpos, ypos);

After you have unloaded the font the previous bitmap font methods can be used:
tft.unloadFont();

I know this can be confusing but this is down to the way the library has evolved. The drawString(...) and font formatting (tft.setDatum(...) etc) will work with any of the fonts.

The Adafruit font rendering is a little crude, you have to use tft.setCursor(x,y) then tft.print(...). I wanted to be able to set the text datum, so for example text could easily be drawn in the middle of a box. So I introduced the drawString() function and the setDatum() function. Because short numbers and strings do not fully over-write larger one drawn on screen previously I added the setTextPadding(pixel_width) function. To use this you must define both foreground text colours and background ones.

I will try to create an example this weekwnd that supports all the fonts but I cannot guarantee I will find the time so it is worth experimenting. If you tell me exactly what you wish to display and which font you want to use then I can give you some guidance.

[SALLDHMF]

I am very, very grateful to you for these clarifications. It's worth putting them on Git for others.

[tablatronix]

Ditto, I am trying to figure out exactly how the text datum and drawstring functions work, but I am still not understanding it. The example could be made a little clearer for now as an alternative.

There just seems to be too many conditionals. If smooth font , padding, etc.

"Normally strings are printed relative to the top left corner but this can be
changed with the setTextDatum() function. "

Top left corner of what? Doesn't the adafruit library use bottom left corner for glyph fonts?

Also what is drawRightString, drawCenterString ?
Deprecated, but still in the string align examples..

I tried enabling PADDING_DEBUG, but still not seeing any change or borders.. , or any difference using different textDatums..

I guess I will play with the string align example, but it needs some comments or serial prints I think.

[tablatronix]

Ok I think I get it now. I think it is a just a confusing example.
The font is too big, the 88,69 is confusing, the duplicated deprecated functions are unnecessary, the dot is the origin of the text draw box, aka the drawstring posx/posy origins, the text datum is the transform for the direction aka align.

Why not add a method to pass in the alignment to the function also, instead of a global toggle?

I will rewrite this to be a little cleared and PR it.

[Bodmer]

I think the "Free_Font_Demo" example will help you. This part of the sketch shows the datum marker on the screen and the text.

[tablatronix]

I will check that one out.

This was also confusing in the stringalign sketch, invisible stuff

  tft.setTextColor(TFT_BLACK);
  tft.drawString("X",160,180,2);

[tablatronix]

oh that is perfect, much better example of textDatum
Thanks!

[khanguslee]

Just wanted to add that your library is very useful! However, the documentation of the library is quite hard for a beginner. Would you take PRs on simple documentation even if it was not the complete set of methods that your library provides?

[Bodmer]

Thanks. I have created a separate empty repository for the time being so you can push PR's there.

[markandkymward]

I have and ESP32-32 WROVER with 4MB PSRAM. I'm making use of SPRITES but am finding that I am running out of memory. Your documentation mentioned that PSRAM is the answer. Any hints on how to configure PlatformIO so that I can use the PSRAM and get bigger sprites? Might be a good addition to future documentation.

[Bodmer]

The Arduno IDE has a menu option to enable PSRAM. Once enabled the Sprites are automatically put in PSRAM. I do not use PlatformIO, but I assume there would be a way to enable it.

[markandkymward]

I saw that the Arduino IDE allowed the option but I did not see any changes when I turned it on. So I moved over to PIO. If the PSRAM is automatic, I must have other problems. Does deletesprite

[markandkymward]

Deallocate memory from the heap?

[markandkymward]

Looking at createSprite.cpp, I see treatment for PSRAM configuration and the use of ps_calloc. Should the deleteSprite do the reverse?

[Bodmer]

As far as I am aware "free" works for PSRAM.
A quick Google found this article which indicates PSRAM has to be enabled manually in PlatformIO.

[markandkymward]

I think this is where I'm having a problem. I can't figure out what exactly goes into the platfomio.ini file. Thanks for the quick replies.

[Bodmer]

I meant to add a link to the article here. Worth a read as it shows how to see the PSRAM size etc and wwhat to add to the plaatformio.ini file.

[markandkymward]

Thanks much. I've managed to get the PSRAM activated (actually per that very same article). Confirmed with ESP. getFreePsram(). The problem I now have is a core 1 panic.

Guru Meditation Error: Core 1 panic'ed (LoadProhibited). Exception was unhandled.

Thanks for the replies - I know this is a problem tracking, not support assistance.

[markandkymward]

So I've managed to get the PSRAM recognized, problem is I now get a consistent core panic (below). Any ideas what is causing this? (notice the createSprite call.

platformio.ini file:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps =
bodmer/TFT_eSPI@^2.3.51
mikalhart/TinyGPSPlus@^1.0.2
robtillaart/RunningAverage@^0.3.1
bodmer/JPEGDecoder@^1.8.1
board_build.flash_mode = dio
board_build.f_flash = 80000000L
board_build.f_cpu = 240000000L
monitor_speed=9600
monitor_filters=esp32_exception_decoder
build_flags = -DBOARD_HAS_PSRAM
-mfix-esp32-psram-cache-issue

SPRAM2: 4294967041
Guru Meditation Error: Core 1 panic'ed (LoadProhibited). Exception was unhandled.
Core 1 register dump:
PC : 0x4008ebaf PS : 0x00060d30 A0 : 0x8008f1bd A1 : 0x3ffcbf10
A2 : 0x3f800000 A3 : 0x00009610 A4 : 0x00000000 A5 : 0x3ffcc7a0
A6 : 0x3ffcc6b1 A7 : 0x3ffcc7a1 A8 : 0x00000000 A9 : 0xffffffff
A10 : 0x3f800010 A11 : 0x3ffc1c58 A12 : 0x3f800014 A13 : 0x00000000
A14 : 0xffffffff A15 : 0x00000000 SAR : 0x00000010 EXCCAUSE: 0x0000001c
EXCVADDR: 0xffffffff LBEG : 0x400014fd LEND : 0x4000150d LCOUNT : 0xffffffff

Backtrace: 0x4008ebaf:0x3ffcbf10 0x4008f1ba:0x3ffcbf30 0x40087e18:0x3ffcbf50 0x400880bb:0x3ffcbf70 0x40081edb:0x3ffcbf90 0x400d8547:0x3ffcbfb0 0x400d8601:0x3ffcbfd0 0x400d353f:0x3ffcbff0 0x400d4071:0x3ffcc040 0x400e6309:0x3ffcc0c0 0x4008bca1:0x3ffcc0e0
#0 0x4008ebaf:0x3ffcbf10 in is_free at /home/runner/work/esp32-arduino-lib-builder/esp32-arduino-lib-builder/esp-idf/components/heap/multi_heap.c:380
(inlined by) multi_heap_malloc_impl at /home/runner/work/esp32-arduino-lib-builder/esp32-arduino-lib-builder/esp-idf/components/heap/multi_heap.c:432
#1 0x4008f1ba:0x3ffcbf30 in multi_heap_malloc at /home/runner/work/esp32-arduino-lib-builder/esp32-arduino-lib-builder/esp-idf/components/heap/multi_heap_poisoning.c:315
#2 0x40087e18:0x3ffcbf50 in heap_caps_malloc at /home/runner/work/esp32-arduino-lib-builder/esp32-arduino-lib-builder/esp-idf/components/heap/heap_caps.c:131
#3 0x400880bb:0x3ffcbf70 in heap_caps_calloc at /home/runner/work/esp32-arduino-lib-builder/esp32-arduino-lib-builder/esp-idf/components/heap/heap_caps.c:131
#4 0x40081edb:0x3ffcbf90 in ps_calloc at C:\Users\marka.platformio\packages\framework-arduinoespressif32\cores\esp32/esp32-hal-psram.c:66
#5 0x400d8547:0x3ffcbfb0 in TFT_eSprite::callocSprite(short, short, unsigned char) at .pio\libdeps\esp32dev\TFT_eSPI\Extensions/Smooth_font.cpp:519
#6 0x400d8601:0x3ffcbfd0 in TFT_eSprite::createSprite(short, short, unsigned char) at .pio\libdeps\esp32dev\TFT_eSPI\Extensions/Smooth_font.cpp:519
#7 0x400d353f:0x3ffcbff0 in showInfoLcd() at C:/Users/marka/Documents/PlatformIO/Projects/201205-191710-esp32dev/src/DataLogger.ino:1652
#8 0x400d4071:0x3ffcc040 in loop() at C:/Users/marka/Documents/PlatformIO/Projects/201205-191710-esp32dev/src/DataLogger.ino:1652
#9 0x400e6309:0x3ffcc0c0 in loopTask(void*) at C:\Users\marka.platformio\packages\framework-arduinoespressif32\cores\esp32/main.cpp:19
#10 0x4008bca1:0x3ffcc0e0 in vPortTaskWrapper at /home/runner/work/esp32-arduino-lib-builder/esp32-arduino-lib-builder/esp-idf/components/freertos/port.c:355 (discriminator 1)

[Bodmer]

I am unable to decipher the possible cause from the debug output. Can you provide a complete example sketch that demonstrates the problem and will run on a minimal ESP32 plus display setup.

[SuilverSurfer06]

Hello Bodmer,
I'm using your wouderfull TFT_eSPI library, it's very quick and easy to use ..Thanks !
I'm actually using an ESP32 + TFT 1.8 ST7735s and all your exemples are working fine.
I have a question about your exemple TFT_Flash_jpg.

For testing and learning purpose, I would like to replace one of your images.
I prepared an image 160x128 on jpg. I used "LCD_Image converter" to convertit, and replace one of your image sample.
I set type color / Color R5G6B5 / Block Size 8 bits / all other by default -> show Preview / copy paste the code in jpeg4.h + compile

When the ESP32 start there is nothing displayed; 'black screen - black scren' and reboot.

**ets Jun 8 2016 00:22:57

rst:0xc (SW_CPU_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:1
load:0x3fff0018,len:4
load:0x3fff001c,len:1044
load:0x40078000,len:10124
load:0x40080400,len:5856
entry 0x400806a8

JPEG image info

Width :0
Height :0
Components :0
MCU / row :0
MCU / col :0
Scan type :0
MCU width :0
MCU height :0

Guru Meditation Error: Core 1 panic'ed (IntegerDivideByZero). Exception was unhandled.
Core 1 register dump:
PC : 0x400d0eff PS : 0x00060530 A0 : 0x800d10f3 A1 : 0x3ffb1f10
A2 : 0x3ffc0930 A3 : 0x00000000 A4 : 0x00000000 A5 : 0x000000a0
A6 : 0x00000000 A7 : 0x00000000 A8 : 0x800d10d8 A9 : 0x3ffb1f30
A10 : 0x00000011 A11 : 0x3f400140 A12 : 0x0000000a A13 : 0x00000013
A14 : 0x7f000000 A15 : 0x3f40a290 SAR : 0x00000008 EXCCAUSE: 0x00000006
EXCVADDR: 0x00000000 LBEG : 0x400014fd LEND : 0x4000150d LCOUNT : 0xffffffff

ELF file SHA256: 0000000000000000

Backtrace: 0x400d0eff:0x3ffb1f10 0x400d10f0:0x3ffb1f70 0x400d1121:0x3ffb1f90 0x400d7951:0x3ffb1fb0 0x400861e5:0x3ffb1fd0

Rebooting...**

It seems that I missed somting ! :-)

Can you tell me how did you do to obtein the code to push on your exemple ( Exemple the monkey ) ?

Many thanks for your help,

[SuilverSurfer06]

Ok foud solution encode on 'RAW' C ;-) site found here :https://lvgl.io/tools/imageconverter

[TangerineDreamer]

Hello everybody,
I would like to draw a primitive with a thickness option like that:
drawRect(uint32_t 32 X0, uint32_t Y0, uint32_t W, uint32_t H, uint32_t COLOUR, uint32_t THICKNESS);
of course i know it doesn't exist,but all the solution i found is to fill a rectangle with a colour and fill again
with another colour to let a marge as a thickness,no other way to do it?
Maybe i post for a request?

[Bodmer]

There is a way to do that if you define a viewport first. See examle here:
https://github.com/Bodmer/TFT_eSPI/blob/master/examples/Generic/Viewport_Demo/Viewport_commands.ino

[ParameswaranAP]

Hi, I just using the TFT_eSPI library for displaying images that are loaded in 16bit hex format and using tft.pushImage function for displaying a loaded images in ST7735 Driver Display. I need to know how to change the image's color in case it change from white to green without changing the original data in array. Is there any function for changing the colour of image?

[ghost]

I am having so confusions with the pins and its interface with ESP32.

[StrandedAlien]

I strongly recommend to do a google search and read some articles about SPI bus usage. There is no standard to name the SPI relevant pins in a consistent manner. That causes a lot of confusion for new SPI users. As their is still no golden solution after all this years (who the heck started this crap?) you will have to remember the names in use to be able to "translate" the SPI pins. The easiest is to use HW SPI. Check pin definition of used library and compare with ESP32 pinout. Learn from googled sources that the ESP32 has two separate SPI interfaces, often labeled as VSPI and HSPI and why it is better not to mix them up. I found I2C in the beginning easier to use, but once you understood it does make not much difference anymore. And SPI is faster :-)

[StrandedAlien]

Hello! In my current project, I use ESP32 and display with ILI9341. I would like to use your library, but - as a beginner - I have a lot of trouble with that. Is there somewhere documentation that describes the operation of all library functions? Eg: tft.drawString (.....) has four parameters, but what? What is the text datum? ... Of course, I will laboriously find explanations in the examples. But if there is documentation, it will be easier and faster.

Tomasz

Would be nice if somebody finds the time and will to help Mr. Bodmer. Gifted programmers prefer IMHO creative tasks and writing documentation seems to be less so. I am sure we can get help from him once we found a start. However there is a existing and tested workaround for this problem if you happen to be a LINUX user: Use grep. Like so:

Go to the (library) folder where you want to search. Open terminal. Type, for example ,grep -nri "drawstring" and then enter. This will give you (for TFT_eSPI) an output also containing

TFT_eSPI.h:641: drawString(const char *string, int32_t x, int32_t y, uint8_t font), // Draw string using specified font number
TFT_eSPI.h:642: drawString(const char *string, int32_t x, int32_t y), // Draw string using current font

from which you learn that the first parameter is the string you want to draw. 2nd and 3rd are xy coordinates and forth is the font. Headerfiles and Grep together gives documentation! On a legacy OS you might want to try this link: https://gnuwin32.sourceforge.net/packages/grep.htm

[buzlachok]

Hello. Tell me how can I change the font?
I'm interested in segment, number 7
I wanted 1 to be displayed on the left side, and not on the right as it is now.

[Marcussacapuces91]

Hello and welcome, everyone!
I'm excited to announce that I have just launched the "ReadTheDocs" site for our project, which you can find at https://doc-tft-espi.readthedocs.io/. With such a large amount of work to be done, any help or contributions are greatly appreciated.
Additionally, for those who are interested in contributing, there is a corresponding GitHub page where you can fork the project and send pull requests: https://github.com/Marcussacapuces91/doc-TFT_eSPI.
Thank you in advance for your support!

Marc