Digital Sketchpad with an ESP32

Introduction

When ordering my ESP32 freenova kit, I also got this display kit. It seemed cool and at the time I had a bunch of ideas of how to make good use of it. I ran into some issues getting it to work, namely not having a datasheet for the TFT breakout board, but armed with a multimeter, I conquered it.

I am not actually sure what type of display board it is as I just got it off aliexpress. From doing some digging it looks like an LCD screen that uses a ILI9341 as its display controller, and a XPT2046 as its touch controller.

Pin Layouts

When ordering this board, I figured it wouldn’t be to hard to find out the pin connections, but I couldn’t find them online anywhere. I used a multimeter and checked what pins had a resistance between them and the input pin. If it showed a reistance pin, it indicated that it was connected to that GPIO pin.

TFT 2.8 Interface

0.96 OLED

Defining the Board

Using what I discovered above, I defined a handy dandy object that use these pins. Using the LovyanGFX library, I interfaced with the TFT display. There is two parts to the board, the display part and the touch part.

The display part defines its clock pins, and its write speed, this being its refresh rate if I understand it properly. Most of the time you are writing to the display so the read frequency can be set lower. If you want to save the current state of the screen you can read it as well, essentially taking a screenshot.

The touch has its own dedicated set of SCLK, MOSI, MISO, and CS pins, meaning it has its own independent SPI bus. This is good as without this, it would use the same SPI bus as the display. The SPI speed would be limited to the lowest speed. I found a frequency of 1000000 to be suitable. Any higher than this caused glitches with the touch point bouncing around, being more susceptible to noise.

Pin Definitions

Display Pin Definitions

Touch Pin Definitions

LGFX Setup

Taken from my Github, it sets up the display and touch modules with the pins we identified.

1
class LGFX_Config : public lgfx::LGFX_Device {
2
  lgfx::Panel_ILI9341 _panel_instance;
3
  lgfx::Bus_SPI _bus_instance;
4
  lgfx::Light_PWM _light_instance;
5
  lgfx::Touch_XPT2046 _touch_instance;
6

7
public:
8
  LGFX_Config() {
9
    { // 1. DISPLAY BUS
10
      auto cfg = _bus_instance.config();
11
      cfg.spi_host = SPI2_HOST;
12
      cfg.pin_sclk = TFT_SCLK;
13
      cfg.pin_mosi = TFT_MOSI;
14
      cfg.pin_miso = TFT_MISO;
15
      cfg.pin_dc = TFT_DC;
16
      cfg.freq_write = 80000000; // 80MHz
17
      cfg.freq_read = 16000000;
18
      _bus_instance.config(cfg);
19
      _panel_instance.setBus(&_bus_instance);
20
    }
21

22
    { // 2. DISPLAY PANEL
23
      auto cfg = _panel_instance.config();
24
      cfg.pin_cs = TFT_CS;
25
      cfg.pin_rst = TFT_RST;
26
      cfg.memory_width = 240;
27
      cfg.memory_height = 320;
28
      cfg.panel_width = WIDTH;
29
      cfg.panel_height = HEIGHT;
30
      cfg.offset_x = 0;
31
      cfg.offset_y = 0;
32
      cfg.rgb_order = false;
33
      cfg.offset_rotation = 0;
34
      _panel_instance.config(cfg);
35
    }
36

37
    { // 3. TOUCH DEVICE (On SPI3_HOST)
38
      auto cfg = _touch_instance.config();
39

40
      cfg.spi_host = SPI3_HOST;
41
      cfg.bus_shared = false;
42

43
      cfg.pin_sclk = TOUCH_SCLK; // TCLK
44
      cfg.pin_mosi = TOUCH_MOSI; // TDIN
45
      cfg.pin_miso = TOUCH_MISO; // TDO
46
      cfg.pin_cs = TOUCH_CS;     // TCS
47

48
      cfg.freq = 1000000; // 1MHz
49

50
      cfg.x_min = 0;
51
      cfg.x_max = 239;
52
      cfg.y_min = 0;
53
      cfg.y_max = 319;
54

55
      _touch_instance.config(cfg);
56
      _panel_instance.setTouch(&_touch_instance);
57
    }
58

59
    { // 4. BACKLIGHT
60
      auto cfg = _light_instance.config();
61
      cfg.pin_bl = TFT_BL;
62
      cfg.invert = false;
63
      _light_instance.config(cfg);
64
      _panel_instance.setLight(&_light_instance);
65
    }
66
    setPanel(&_panel_instance);
67
  }
68
};

Calibration

The touch will not work out of the box unless it is calibrated beforehand. Below is how to calibrate it. Once you calibrate it, the values are stored in the array.

1
uint16_t call_data[8];
2
lcd.calibrateTouch(cal_data, TFT_WHITE, TFT_BLACK, 30);
3
for (int i = 0; i < 8; i++) {
4
  lcd.println(cal_data[i]);
5
}
6
lcd.setCursor(0, 0);

Using this array, you can precalibrate the touch screen upon startup.

1
uint16_t cal_data[8] = {226, 3811, 288, 193, 3891, 3826, 3900, 182};
2
lcd.setTouchCalibrate(cal_data);

Displaying an Image

Given some image, it has to be converted to a raw image. The Lovyan expects the high order bits to contains the red information. It uses the 565 format, that being 5 bits for red, 6 bits for green as we naturally are more sensitive to green, and the remaining 5 bits for blue.

ffmpeg -i "$1".png -vcodec rawvideo -f rawvideo -pix_fmt rgb565be "$1".raw

This gives us a raw image that we can further processes. We can convert the raw image into a C style header file that describes the image using xxd.

xxd -i "$1".raw "$1".h

This can be then drawn on the screen using a function that the library provides. Xxd provides the header file where the image is represented as uint8_t, the display uses 16 bit colour as we just simply cast it as a uint16_t.

lcd.pushImage(0, 0, WIDTH, HEIGHT, (uint16_t *)image_raw);

LovyanGFX Helpers

There isn’t from what I found a dedicated central documentation for how to use the LovyanGFX library. I compiled some useful functions for when interacting with it. The lcd can be replaced with a sprite object to push/draw on a given sprite.

Basic Geometry

These are the building blocks of any UI. Most commands have a draw version (outline) and a fill version (solid).

Advanced Smooth Shapes

These functions use anti-aliasing to remove jagged edges, making the UI look modern and high-end.

Text and Font Control

LovyanGFX handles text very efficiently, including support for custom fonts and auto-scrolling.

Sprite and Buffer Management

Sprites allow you to draw complex things off-screen and then push them onto the LCD all at once to eliminate flickering.

Display and System Control

Commands for managing the physical behavior of the display panel.

Touch Interaction