ESP32 UNO - TFT LCD Touch Screen Display

Components You Need

Or you can buy the following kits:

Overview of the TFT LCD Touch Display Shield

By the end of this part, you know what the shield contains and which version you own.

The shield was made in two versions. Compare them here.

Header pins taken by the shield

Each Uno header pin has a GPIO number on the ESP32 Uno. The shield uses most of them.

Good to know: the ESP32 Uno pins work at 3.3V logic and are not 5V tolerant. The touch panel is read with the 12-bit ADC (0–4095) of the board, but the touch library expects 10-bit numbers (0–1023). The touch sketches below set this for you with analogReadResolution(10).

ESP32 Uno Pinout

Match each Uno header label to its GPIO number in this picture before you plug in the shield. Your sketch uses the GPIO numbers.

How to Connect

Goal: the shield sits on the board and no wire is needed. Set it on the ESP32 Uno with the microSD slot above the USB port side, and push down softly. No jumper wires and no soldering.

This image is created using Fritzing. Click to enlarge image

Sketch 1: Text, Integer and Float Numbers

This first sketch is a quick screen test. It switches to landscape, fills the screen with white and prints a temperature and a humidity value in magenta with one decimal place. The display object gets the ESP32 Uno touch pins: TFT_display(27, 4, 35, 14).

The screen shows two lines of text and numbers.

Upload and Test

1. First time with this board? Set it up with ESP32 Uno - Getting Started before you continue.
2. Seat the shield on the ESP32 Uno like the picture above.
3. Plug in the USB Type-C cable between the ESP32 Uno and your computer.
4. Select the board in Arduino IDE: pick ESP32 Dev Module and the COM port of the board (CH340).
5. Click the Libraries icon in the left toolbar of Arduino IDE.
6. Type “DIYables TFT Touch Shield” in the search box and look for the library of the same name by DIYables.
7. Install it with the Install button. Pick the latest version.

• Search for DIYables TFT Touch Shield created by DIYables.io and click the Install button.

1. Say yes to the dependencies: click Install All in the prompt. The Adafruit GFX Library comes with it.
2. Paste the sketch above into a new Arduino IDE window.
3. Upload it with the Upload button. If the upload does not start, hold the BOOT button while the IDE says "Connecting...".
4. Pro tip: a white or noisy screen almost always means the wrong driver class. Check the chip name on your shield and switch between RM68140 and HX8357D.

The text appears in the built-in font. It is readable but blocky. The next sketch shows how to use a nicer font.

Sketch 2: Custom Fonts

The Adafruit GFX Library, installed as a dependency, ships with many fonts. You switch to one with two extra lines.

Step 1 — Pick a font

Open the folder of the Adafruit GFX Library and look in its Fonts folder. Take one you like, such as FreeSansBold12pt7b.h.

Step 2 — Include it

Add this line at the top of your code:

Step 3 — Select it

Call this line inside setup():

This full sketch prints the same two values with the bold sans font.

Good to know: some custom fonts have no special characters such as the degree sign (°). The default font has it.

Sketch 3: Draw Shapes

Shapes are the base of gauges, icons and buttons. The sketch paints outline and solid versions of circles, triangles, rectangles, rounded rectangles and diamonds, each in its own color. It uses landscape mode (480x320) and redraws the picture every 10 seconds.

Upload and Test

1. Paste the sketch above into a new Arduino IDE window.
2. Upload it to the ESP32 Uno with the Upload button.
3. Pro tip: the fillDiamond() helper joins two triangles. Reuse the trick to build other solid shapes.

Circles, triangles, rectangles, rounded rectangles and diamonds now fill the screen.

Sketch 4: Show Images

You can keep a picture in two places.

The shield already has a microSD socket, so no extra adapter is needed. Both methods follow.

Bitmap Arrays in the Code

This sketch puts the DIYables logo in the center of the screen. Every two seconds the loop inverts the colors.

Step 1 — Create bitmap.h

In Arduino IDE, add a tab with the New Tab entry of the small menu under the Serial Monitor icon, or hit Ctrl+Shift+N.

Step 2 — Name the file

Enter the name bitmap.h, then press OK.

Step 3 — Paste the picture data

Paste the data below into bitmap.h. The array is the DIYables logo.

Step 4 — Upload

Click Upload to send the sketch to the ESP32 Uno. The DIYables logo appears on the screen.

Pro tip: when you edit only the .h file, add a space to the .ino file too. The Arduino IDE then notices the change and compiles again.

Show your own picture

1. Prepare a JPEG or PNG image.
2. Open the Image to Bitmap Converter and upload it.
3. Set the width so the image is smaller than the screen.
4. Using a PNG with see-through parts? Pick a fill color, because the conversion drops transparency.
5. Click Convert and wait.
6. Copy the new bitmap array into bitmap.h.

1. Edit img_width and img_height in the .ino file so they equal the scaled picture size.
2. Upload the sketch again.

Pictures from a MicroSD Card

The microSD socket of the shield uses D10 (GPIO5) for chip select and D11 (GPIO23), D12 (GPIO19), D13 (GPIO18) for SPI. These are the default SPI pins of the ESP32 Uno, so SD.begin(5) needs no extra wire. On this board, file names must begin with a slash, so the sketch opens "/diyables.bmp".

Good to know: D10 (GPIO5) is a boot strapping pin. If the board does not boot with the shield and a card inserted, remove the shield for the upload.

Step 1 — Get the picture

Download diyables.bmp and copy it to the microSD card.

Step 2 — Insert the card

Push the card into the SD socket of the TFT display.

Step 3 — Upload the sketch

Keep the Serial Monitor open at 9600 baud. It reports if the card or the file is missing.

The logo is read from the card and drawn on the screen.

Show another picture from the card

1. Prepare a JPG or PNG image.
2. Use the Image to Bitmap Converter: click Convert, then Save as Bitmap to download the file.
3. Use a file name of 8 characters or fewer, without the extension.
4. Copy the file to the card and put the card back in the socket.
5. Change the name in the sketch and keep the leading slash, for example "/logo.bmp".
6. Upload again.

You can change the code to draw several pictures at once.

Sketch 5: Read the Touch Point

Every touch project starts with knowing where the finger is. This sketch sends the X and Y of each touch to the Serial Monitor and marks the spot on the screen with a red dot.

Touch works with the default calibration numbers. If the dot is not under your finger, run the calibration sketch and use your own values.

Why does setup() have two ADC lines?

The touch sketches start with two extra lines. analogReadResolution(10) makes the ESP32 Uno ADC report 0–1023 instead of its default 0–4095, because the touch library and the default calibration numbers (136, 907, 942, 139) use the 10-bit range.

analogSetAttenuation(ADC_11db) opens the analog input window from 0V up to roughly 3.3V. With a narrower window, readings hit the maximum early and touch points land in the wrong place.

Upload and Test

1. Paste the sketch above into a new Arduino IDE window.
2. Upload it with the Upload button.
3. Open the Serial Monitor and choose 9600 baud.
4. Touch the screen in several places.
5. Read the coordinates printed in the Serial Monitor.
6. Pro tip: press with a stylus or a fingernail. A resistive panel needs a bit of force.

Sketch 6: Draw with a Pen

Make the display work like a sketch pad. Each touch point gets a red dot, and a moving pen leaves a trail of dots.

Touch works with the default calibration numbers. If the line is not under the pen, run the calibration sketch.

Upload and Test

1. Paste the sketch above into a new Arduino IDE window.
2. Upload it with the Upload button.
3. Drag your finger or pen over the screen to draw.
4. Take the pen off the glass to stop.
5. Pro tip: raise PEN_RADIUS for a thick marker, lower it for a thin pen.

Sketch 7: Touch Button

Touch buttons replace physical switches. The sketch paints a red "PRESS" box. While you touch it, the box goes gray and reads "PRESSED". After you let go, it returns to red. A short debounce delay stops flicker.

Touch works with the default calibration numbers. If the button reacts in the wrong place, run the calibration sketch.

Upload and Test

1. Paste the sketch above into a new Arduino IDE window.
2. Upload it with the Upload button.
3. Open the Serial Monitor (9600 baud) if you want to log each press and release.
4. Tap the red box and see the color flip.
5. Pro tip: to move or resize the button, change the four BUTTON_ values at the top.

The button looks like this.

Touch Calibration Sketch

The sketches above use default calibration numbers and often work right away. Is the touch point off? Calibrate one time.

The touch layer is never glued exactly on the pixels, so raw readings differ a little from one display to the next. The calibration sketch reads your own panel and converts its raw numbers into screen positions.

Step 1 — Upload the calibration sketch

Step 2 — Open the Serial Monitor

Press Ctrl+Shift+M and choose 9600 baud.

Step 3 — Touch the four corners

A blinking red dot shows in each corner, numbered 1 to 4:

• 1: top-left
• 2: top-right
• 3: bottom-right
• 4: bottom-left

Press and hold each dot with some force until the Serial Monitor prints "Captured!". Let go, then do the next corner.

Step 4 — Copy the result

After corner 4, the Serial Monitor prints four numbers and a ready line such as TFT_display.setTouchCalibration(131, 910, 944, 141);. Paste the numbers into the LEFT_X, RIGHT_X, TOP_Y and BOT_Y defines, or put the line in setup() before you call any touch function.

Calibrate once per display. Do it again only if you change the hardware.

Video Tutorial

See the ESP32 Uno build in action in the video below.

ESP32 Uno vs UNO R4 for This Project

Moving this display from the UNO R4 to the ESP32 Uno changes the touch pin numbers and a few lines of setup code.

The shield fits the Uno headers on both boards, so the stacking is the same. Pin numbers in the code are GPIOs on the ESP32 Uno. Remember that A2, A3 and A4 are input-only pins on this board.

Go Wireless: A Phone Screen Next to the TFT

Goal: send the text from your phone to the touch display.

The ESP32 Uno has WiFi and Bluetooth, so the shield does not have to show fixed text only. Type a message in a web page or in a Bluetooth app, and let the sketch print it on the screen with TFT_display.print(). You can also send the touch coordinates to a phone to check them while you test.

Good to know: the analog touch readings use A1 (GPIO4), which is an ADC2 pin. ADC2 cannot be read while WiFi is on, so a WiFi version of the touch sketches needs another way to read touch, for example with Bluetooth only.

Try These Next

• Save the calibration values in your sketch and test touch in all four rotations.
• Draw a slider with fillRect() and move it with getTouch().
• Build a two-button menu: one button changes the screen color, the other shows a picture from the microSD card.
• Make a tiny paint tool with color boxes at the top of the screen.

Troubleshooting

FAQ

Does the 3.5-inch TFT touch shield fit the ESP32 Uno?

Yes, the shield has the Uno shape and plugs into the headers. Install the DIYables_TFT_Touch_Shield library v2.0.0 or newer and create the display object with the ESP32 Uno touch pins. Check the library notes for ESP32 Uno support.

What do the numbers 27, 4, 35, 14 mean in the display object?

They list the touch lines as GPIOs, in the order XP, YP, XM, YM: D6 is GPIO27, A1 is GPIO4, A2 is GPIO35 and D7 is GPIO14. The library falls back to Uno header numbers when you pass nothing, so on this board you hand it the GPIOs yourself.

What do analogReadResolution(10) and analogSetAttenuation(ADC_11db) do in the touch sketches?

The ESP32 Uno ADC gives 0–4095 by default, but the touch library and its default calibration numbers use 0–1023. analogReadResolution(10) fixes the range. analogSetAttenuation(ADC_11db) widens the input window to roughly 0–3.3V, which lets the whole touch signal be read. Those lines are extra work that only the ESP32 Uno needs.

Which pins are left for my own parts while the shield is mounted?

Pin A5 (GPIO39) stays unused by the shield, but it can only read, not write. The SDA (GPIO21) and SCL (GPIO22) header pins are free for I2C modules, because I2C is not on A4/A5 on this board. D10 to D13 become free too when you leave the microSD card out.

My project needs extra pins beyond the Uno headers. Where do I find them?

The shield takes almost every header pin, so the extra holes are useful. The ESP32 Uno has GPIO32 and GPIO33 (I/O, PWM, analog on ADC1, so they also work while WiFi is on) and GPIO15 (I/O, PWM, analog on ADC2) near the power header. Solder pin headers to use them and write the GPIO number in code. For an analog sensor, pick GPIO32 or GPIO33. Two warnings: GPIO15 and GPIO0 (the IO0 pin at the unused Uno NC position) are boot strapping pins, and a wrong connection can stop the board from booting or uploading code, so use GPIO32/33 first. Never use the six holes under the digital header (SD0–SD3, CMD, CLK = GPIO6–GPIO11), because they are wired to the flash chip and using them crashes the board.

Why are A2, A3 and A4 a problem for this shield?

On the ESP32 Uno, A2 (GPIO35), A3 (GPIO34) and A4 (GPIO36) are input-only pins. The shield uses them for command/data, chip select and reset, which are outputs. The wiring is fixed by the shield, so use a library version that handles this on the ESP32 Uno.

Can the ESP32 Uno boot with the shield plugged in?

Usually yes, but D8 (GPIO12), A0 (GPIO2) and D10 (GPIO5) are boot strapping pins and the shield is connected to them. If the upload or the boot fails, take the shield off, upload, and put it back.

How do I use an HX8357D shield instead of an RM68140 one?

Change the class name from DIYables_TFT_RM68140_Shield to DIYables_TFT_HX8357D_Shield. The functions are the same, so the rest of the sketch stays as it is.

Do I need to calibrate the touch screen?

Not always. The default numbers (136, 907, 942, 139) work on many panels. Run the calibration sketch when the touch point is not under your finger.

Can I use any microSD card?

Use a FAT32 card. Name the picture with fewer than 9 characters, start the name with a slash, and save it as a 24-bit BMP.

Can I show the touch position on a web page with the ESP32 Uno?

Yes, the ESP32 Uno has WiFi and Bluetooth. Send the X and Y values to a web page or phone app with the DIYables web apps, but remember that the touch panel is read on A1 (GPIO4), an ADC2 pin, which cannot be read while WiFi is on. Bluetooth does not have this limit.

Learn More

• ESP32 UNO - LCD I2C
• ESP32 UNO - LCD 20x4
• ESP32 UNO - LCD Keypad Shield
• ESP32 UNO - OLED 128x64
• ESP32 UNO - OLED 128x32
• ESP32 UNO - SSD1309 OLED Display
• ESP32 UNO - Round Circular TFT LCD Display
• ESP32 UNO - TFT LCD Touch Display SPI
• ESP32 UNO - Smart Weather Station
• ESP32 UNO - Ultrasonic Sensor - LCD
• ESP32 UNO - Ultrasonic Sensor - OLED
• ESP32 UNO - LED Matrix
• ESP32 UNO - Keypad - LCD
• ESP32 UNO - Temperature Sensor - LCD
• ESP32 UNO - Temperature Sensor - OLED
• ESP32 UNO - DHT11 Temperature Humidity Sensor - OLED
• ESP32 UNO - DHT11 - LCD
• ESP32 UNO - DHT22 Temperature Humidity Sensor - OLED
• ESP32 UNO - DHT22 - LCD