ILI9341 + ESP32 (Parallel)

ILI9341 pin to pin ESP32

Today I’ve received two ILI9341 TFT screens that I ordered some weeks ago. These screens are in fact a shield designed for Arduino Uno but they work nicely when connected to other developer boards and the price is amazingly cheap: just US$4.

ILI9341 Front
ILI9341 Front
ILI9341 Back
ILI9341 Back

In this case, we will connect the screen to an ESP32 Dev Board.

The pins are configured in a slightly different way than other examples you could find in the web: I’ve tried to minimize mistakes because we will use 13 pins so I thought the best way would be to use as much as possible consecutive pins.

ILI9341 pin to pin ESP32
ILI9341 pin to pin ESP32


ILI9341 to ESP32
ILI9341 to ESP32

You can also connect the ILI9341 using only 4 IO pins (not this model), but the refresh/painting speed is not comparable.

The library we will use is TFT_eSPI library by Bodmer and our only purpose by the moment will be executing an example demo script successfully.

During testing, you can connect TFT 3V3 pin directly to ESP32 3V3 pin, but do it only during a short period of time because the current drawn by the screen LEDs is 134mA and you will notice how the LEDs and the Development Board voltage limiter will become hot.

A 22Ω resistor (not 220) between the two 3V3 pins it’s enough to reduce the current to 23mA and though the screen is not the brightest one in the world I think it is enough for testing purposes.

Once you have finished the connection of the pins as described in the diagram above, you can install the TFT_eSPI library if you don’t have it already installed.

Open Arduino IDE, go to Library Manager and in the search box type TFT_eSPI. In the results list, look for the next and install it.

TFT_eSPI Bodmer Library for Arduino
TFT_eSPI Bodmer Library for Arduino

Now you have the library installed you have to configure the IO pins where we have connected our screen. Other libraries use the definition of constants at the top of each sketch to do this, but TFT_eSPI uses a common file to define the configuration.

Find in your Arduino installation the file called User_Setup.h

It should be located in a path equivalent to this:

[Arduino Folder]/libraries/TFT_eSPI/User_Setup.h

Now, copy the file for backup purposes and edit the original to place inside it this following content (replacing all the previous content):

// See SetupX_Template.h for all options available

#define ESP32_PARALLEL

#define ILI9341_DRIVER

// ESP32 pins used for the parallel interface TFT
#define TFT_CS   27  // Chip select control pin
#define TFT_DC   14  // Data Command control pin - must use a pin in the range 0-31
#define TFT_RST  26  // Reset pin

#define TFT_WR   12  // Write strobe control pin - must use a pin in the range 0-31
#define TFT_RD   13

#define TFT_D0   16  // Must use pins in the range 0-31 for the data bus
#define TFT_D1   4  // so a single register write sets/clears all bits
#define TFT_D2   23
#define TFT_D3   22
#define TFT_D4   21
#define TFT_D5   19
#define TFT_D6   18
#define TFT_D7   17

#define LOAD_GLCD   // Font 1. Original Adafruit 8 pixel font needs ~1820 bytes in FLASH
#define LOAD_FONT2  // Font 2. Small 16 pixel high font, needs ~3534 bytes in FLASH, 96 characters
#define LOAD_FONT4  // Font 4. Medium 26 pixel high font, needs ~5848 bytes in FLASH, 96 characters
#define LOAD_FONT6  // Font 6. Large 48 pixel font, needs ~2666 bytes in FLASH, only characters 1234567890:-.apm
#define LOAD_FONT7  // Font 7. 7 segment 48 pixel font, needs ~2438 bytes in FLASH, only characters 1234567890:.
#define LOAD_FONT8  // Font 8. Large 75 pixel font needs ~3256 bytes in FLASH, only characters 1234567890:-.
#define LOAD_GFXFF  // FreeFonts. Include access to the 48 Adafruit_GFX free fonts FF1 to FF48 and custom fonts


Save the file and go back to Arduino IDE.

Open the example sketch UTFT_demo (it is under File / Examples / TFT_eSPI /  320 x 240 / UTFT_demo)

At this point, you can compile and upload the sketch to your ESP32. If everything went ok you should see some graphics, backgrounds and texts appearing in your TFT screen. Otherwise please review carefully the IO pins configuration (hard and soft).

If it works, probably you’ll see the results like in a mirror. To solve this, go to the sketch and edit the line that sets the screen orientation. This is done in the setup function.

void setup()
// Setup the LCD
  //myGLCD.setRotation(1); //Comment out this one and insert the one below

The result now should look like this

49 thoughts on “ILI9341 + ESP32 (Parallel)”

  1. Thank you very much for this precise and detailed procedure Alberto!
    You’ve totally unblocked me and I’ll finally be able to move forward!
    The display refresh is super fast. It’s great!
    Merci infiniment 😉

  2. It doesn’t work in my TFT board. The screen only shows a lot of pixels of different colors, i don’t know if i made a mistake in the PINOUT configuration.. Can you help me?

    1. Sorry, I wrote the post one year ago (1 year and 3 days ago) and honestly I don’t remember the details.
      Is the TFT the same model?
      Have you reviewed the pins?
      The pins connection is quite straight the way I did it… so if its not a pinout issue you should review software configuration…

      1. I made a mistake in the PINOUT connections… I’m sorry, but now my TOUCH isn’t working. Apparealy, I need to configure the Touch_CS port in the User_Setup, but i can make it work.

        Thank you anyways

  3. Thank you very much, it is working. Do you know the way for to increase the bright? Thank you in advance.

    1. You can connect the backlight led to 3.3 or 5 V pin with it’s appropriate resistor.

      1. Sorry for the questions but I’m new in this topics, which one is the backlight led? I’m very grateful for your help. I was searching info but for this model I couldn’t find nothing about the backlight led.

        1. Don’t worry. Try this:

          Instead of connecting to 3V3, use 5V. To do that:
          1.- Remove completely (from both sides) the wire that connects 3V3 pin in ESP32 to 3V3 pin in TFT (it is the red one in the schematic)
          2.- Connect the previous wire to the opposite pin in ESP32 named Vin (which actually is 5V) to the 5V pin in TFT (the one next to 3V3)

          ILI9341 5V

          It should look brighter now…

          1. Amazing man!!! Thank you for your help and for to be patient. I’m exited!!!

            Saludos from México!!!

  4. Hi Alberto, here with a new doubt, I need to use the ports Rx2 and Tx2 of the ESP32 for communication with Arduino Uno via serial, I tried with Rx0 and Tx0 but that not work, I think that ports are reserved for other function, I don’t understand completly the function for each one pin, then of that I tried change the wire connection for LCD_D0 with GPIO25 and LCD_D7 with GPIO15, but that didn’t work, I modified the file User_Setup.h with that changes, could you say me if is possible to release the ports RX2 and Tx2 ?
    I was reading about this inconvinience, but I can’t implement a satisfactory solution yet.

    Thank you in advance.

        1. You shouldn’t have any problem when changing the pins. Could you please try with pins D25 and D5….
          Are you sure the modified file has been used for compilation?
          And one more question, when you say it didn’t work, what was the issue? I mean, blank screen, unreadable content, ….

  5. Thank you for your tutorial.

    Just to inform you:

    A fatal error occurred: Timed out waiting for packet content
    A fatal error occurred: Timed out waiting for packet content

    I’ve got this error trying to use with my esp32 devkit and the tft ili9341

    1. Hi Junix,

      your problem should be related to MCU programming. Based on my experience, try these to solve your problem:
      – Check if you are able to upload a simple sketch to your MCU. Try with blink.ino one. The reason is that there are some boards that need your help (manually push switches during uploading)
      – If the one above is not your issue, review the pinout. Probably you are using a pin needed for serial programming and that is a problem.
      If you review all the steps and the pin wiring is the correct one… it should work.
      Good luck, I know those moments when it seems it will never work…. but it always does it if you persevere. 🙂

    2. I received the same error. I simply powered-down the display while downloading the ESP32. It could be a power quality issue if you’re running on USB power.

  6. Hi, i am always getting white screen, have checked HW connections they are ok and configuration file is ok too. Have checked LCD with ardunio it is ok

  7. Hi,
    First of all, thank you so much for providing this thread of help.
    I have tried this connection by using ILI9486 instead of ILI9341. Made the changes in header file also. But it’s not working. Always showing the white screen only.

    1. Thanks for commenting Abhishek.

      I am afraid I cannot help you because I’ve never tried the display you mentioned in your comment. Hopefully someone else could help you….

    2. I think there has something wrong on your work… I using ILI9486 also and it works for me. I just simply made a changes in User_Setup.h:
      #define ILI9431_DRIVER
      #define ILI9486_DRIVER

  8. Hey, thank you very much for this article! I finally got it to work 🙂
    It didn’t work immediately, because there was this part written in Setup1_ILI9341.h:

    //For Esp82x
    #define TFT_CS PIN_D8 // Chip select control pin D8
    #define TFT_DC PIN_D3 // Data Command control pin
    #define TFT_RST PIN_D4 // Reset pin (could connect to NodeMCU RST, see next line)
    #define TFT_RST -1 // Set TFT_RST to -1 if the display RESET is connected to NodeMCU RST or 3.3V

    which overwrote my settings. So I commented it out and it worked fine 🙂

    But my question would be: Have you ever tryed to use the sd card as well? I am insecure, wether the SPI bus is already used or not.

    1. Thanks a lot for commenting Potato. 🙂

      I’ve never tried the SD card functionality 🙁

  9. thanks for that tutorial its really useful for my project
    Can I use 6 bit only (D0 to D5) for parallel interface ??

  10. Thank you Alberto for the very straigth forward tutorial.
    It is working fine with my ILI9486 display and I just needed to change one line of your User_Setup.h example to:

    #define ILI9486_DRIVER

    Now I will move on to make the touch screen part to work.

    Greetings from Portugal!

  11. Muito obrigado Jose Santos (I once knew one “Jose Santos” at Portugal (Aveiro) 🙂 )

  12. Hello Alberto,
    I’m trying to connect on NodeMCU ESP8266 12F.
    Connecting TFT to 3.3v on ESP8266 TFT stays black.
    So wiring tft and ESP to external power 5v but TFT stays white.

    In User_Setup.h there are these lines
    #define TFT_PARALLEL_8_BIT –> change to ESP32_PARALLEL ?

    #define TFT_CS PIN_D8
    #define TFT_DC PIN_D3
    #define TFT_RST PIN_D4
    change to
    #define TFT_CS 15
    #define TFT_DC 0
    #define TFT_RST 2 ?

    1. Hello Hady,

      I’m sorry but I am not currently working on these projects because of my job and lack of time… maybe someone else could answer your question.


  13. Hola Alberto muchas gracias por su tutorial, después de tanto trabajarle logré con sus aportes hacer que una pantalla 3.5″TFT LCD Shield con el controlador ILI 9486 funcionara con la ESP32, Muchas gracias ahora es trabajarle al Touch pero si alguien ya lo logró por favor orientanos y si lo logro haré lo mismo.
    Muchas gracias.

  14. TFT ILI 9431 works well both display and touch.
    BUT touch orientation for X-axis and Y-axis is flipped. Opposite with display orientation.
    Default orientatiion both display and touch is vertical.

    1. Display default orientation vertical (X.Y = 0.0) is top left corner
      Touch default orientation vertical (X.Y = 0.0) is bottom right corner

Leave a Reply

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