← Back to ESP32 Build Finder

Build a capacitive touch control panel

A small touchscreen that controls your smart home: tap buttons to toggle lights and fans, drag a slider to dim, and see the room temperature. Runs on one inexpensive 2.8-inch ESP32 board with ESPHome and LVGL.

Control panel Lamp Fan Lamp brightness Panel temp: 21.5 C 2.8-inchST7789 screen240 x 320 pixels Capacitivetouch (CST816)tap and drag Illustration. Layout and connector positions vary by board revision.
What you will build: a Home Assistant control panel with two toggle buttons, a brightness slider and a live temperature reading.
1Set up toolsESPHome + secrets 2Flash a testscreen + touch work? 3Build the UIbuttons + slider 4Add a sensoroptional BME280 DoneMount ituse it daily
The build in four stages. Testing the screen and touch before designing the interface saves a lot of confusion.

Parts you need

Every item has a buy link, whether or not you own it already. If you marked something as owned on the Build Finder, it is labelled so here.

Some links are affiliate links, so I may earn a commission at no extra cost to you. As an Amazon Associate I earn from qualifying purchases. Commissions never affect which projects appear. Details. The buy buttons open a store search; check that the product matches the board name before you order.

Buying the right board. Several look-alike 2.8-inch boards exist. This guide is for the JC2432W328C with an ST7789 screen and capacitive touch. The cheaper "Cheap Yellow Display" (ESP32-2432S028) uses resistive touch and a different touch chip, so the touch settings in this guide will not work on it.

Know your board

Almost every pin on this board is already wired to something. That is good, because it means the screen, touch, storage and light sensor need no wiring, but it also means you have only two free pins for your own parts.

ESP32 WROOM-32 module dual core, Wi-Fi + BLE Display: ST7789V, 240x320 HSPI bus: CLK 14, MOSI 13, MISO 12 CS 15, DC 2 Backlight (PWM): GPIO 27 Touch: CST816 capacitive I2C bus: SDA 33, SCL 32 Reset: GPIO 25 microSD slot VSPI bus: CLK 18, MOSI 23 MISO 19, CS 5 Light sensor (LDR) GPIO 34 (analog, input only) Speaker output GPIO 26 RGB LED (active low) Red 4, Green 16, Blue 17 Expansion: CON2 / CON3 GPIO 21 and GPIO 22 are free plus 3V3 and GND Your only free pins. Use them for one I2C sensor, such as a BME280.
What the board connects to internally. GPIO numbers, not the silkscreen labels. Your only free pins are GPIO 21 and 22 on the expansion connectors.

Pins differ between sources. The pin numbers above come from the ESPHome device page for this board, which includes a complete configuration that runs. One other community document lists different display pins for what looks like another revision. If your screen stays blank with this guide's configuration, do not assume your board is faulty: check the printing on the back of your board and the seller's documentation, and use the test in step 2 to find out which pins your revision uses.

1Set up your tools

  1. Get ESPHome running. The easiest way is the ESPHome Device Builder add-on in Home Assistant (Settings, Add-ons). You can also install ESPHome on your own computer with pip install esphome. Use a current release: the display driver used below (mipi_spi) is recent, and older releases will not know it.
  2. Add your secrets. In the ESPHome builder, open Secrets and add these four lines with your own values. Keep this file private.
    wifi_ssid: "YourWiFiName"
    wifi_password: "YourWiFiPassword"
    api_key: "paste a generated 32-byte base64 key here"
    ota_password: "choose-a-password"
    You can generate the API key in the builder when you create a new device, or at esphome.io/components/api.
  3. Plug the board into your computer with the USB-C data cable. If no serial port appears, your board may use a CH340 or CP210x USB chip and need its driver installed.

2Flash a test and check the hardware

Before designing anything, make sure the screen and touch respond. This test shows a colour test card, turns the backlight on and prints every touch position to the log. It is based on the configuration published for this board on the ESPHome device page.

  1. In ESPHome, click New device, name it touch-panel, skip the wizard, then replace the file contents with this:
    esphome:
      name: touch-panel
    
    esp32:
      board: esp32dev
      framework:
        type: esp-idf
    
    logger:
    
    # Backlight on GPIO27
    output:
      - platform: ledc
        pin: GPIO27
        id: backlight_pwm
    
    light:
      - platform: monochromatic
        output: backlight_pwm
        name: "Display Backlight"
        id: backlight
        restore_mode: ALWAYS_ON
    
    # Display on the HSPI pins
    spi:
      - id: spi_display
        clk_pin: GPIO14
        mosi_pin: GPIO13
        miso_pin: GPIO12
    
    display:
      - platform: mipi_spi
        model: ST7789V
        id: my_display
        spi_id: spi_display
        cs_pin: GPIO15
        dc_pin: GPIO2
        data_rate: 40MHz
        rotation: 90
        show_test_card: true
    
    # Touch on its own I2C bus
    i2c:
      id: i2c_touch
      sda: GPIO33
      scl: GPIO32
    
    touchscreen:
      - platform: cst816
        id: my_touchscreen
        i2c_id: i2c_touch
        reset_pin: GPIO25
        transform:
          swap_xy: true
          mirror_y: true
          mirror_x: false
        on_touch:
          - lambda: |-
              ESP_LOGI("touch", "x=%d, y=%d", touch.x, touch.y);
  2. Click Install, then Plug into this computer (Chrome or Edge), and pick the board's serial port. The first flash must be over USB. If it fails to connect, hold the BOOT button while the upload starts.
  3. Check the result. You should see a colour test card in landscape, and the log should print x=..., y=... as you touch the screen.
If you seeTry
Blank screen, backlight offThe backlight is GPIO27 on this guide's pin set. Confirm in the log that the light turned on.
Backlight on, no pictureYour revision may use different display pins. See the warning above.
Wrong colours (inverted)Add invert_colors: true under the display.
Touch is mirrored or sidewaysChange the transform options: toggle swap_xy, mirror_x and mirror_y until the coordinates match your finger.
No touch messages at allCheck the touch I2C pins (33 and 32) and the reset pin (25).

3Build the control panel

Now replace the test with the real interface. ESPHome uses LVGL, a graphics library, to draw buttons and sliders and to connect them to Home Assistant. The layout below uses a 320 x 240 landscape screen.

Control panel Lamp Fan Lamp brightness Panel temp: -- 0,0320 x 240 title: align TOP_MID, y 8 btn_lampx 16, y 50136 x 64 label: y 128 sld_brightx 16, y 156 lbl_temp: y 196 btn_fan: x 168, y 50
Layout used in the configuration below. Coordinates are in pixels on the 320 x 240 landscape screen.
  1. Replace the file contents with the full configuration. Change the two Home Assistant entity names (light.living_room, switch.desk_fan) to ones from your own Home Assistant.
    substitutions:
      device_name: touch-panel
    
    esphome:
      name: ${device_name}
    
    esp32:
      board: esp32dev
      framework:
        type: esp-idf
    
    logger:
    
    api:
      encryption:
        key: !secret api_key
    
    ota:
      - platform: esphome
        password: !secret ota_password
    
    wifi:
      ssid: !secret wifi_ssid
      password: !secret wifi_password
    
    output:
      - platform: ledc
        pin: GPIO27
        id: backlight_pwm
    
    light:
      - platform: monochromatic
        output: backlight_pwm
        name: "Panel Backlight"
        id: backlight
        restore_mode: ALWAYS_ON
    
    spi:
      - id: spi_display
        clk_pin: GPIO14
        mosi_pin: GPIO13
        miso_pin: GPIO12
    
    display:
      - platform: mipi_spi
        model: ST7789V
        id: my_display
        spi_id: spi_display
        cs_pin: GPIO15
        dc_pin: GPIO2
        data_rate: 40MHz
        rotation: 90
        auto_clear_enabled: false   # required when LVGL draws the screen
    
    i2c:
      - id: i2c_touch
        sda: GPIO33
        scl: GPIO32
    
    touchscreen:
      - platform: cst816
        id: my_touchscreen
        i2c_id: i2c_touch
        reset_pin: GPIO25
        transform:
          swap_xy: true
          mirror_y: true
          mirror_x: false
    
    # Built-in light sensor
    sensor:
      - platform: adc
        pin: GPIO34
        name: "Panel Ambient Light"
        update_interval: 60s
        attenuation: auto
    
    lvgl:
      buffer_size: 25%
      pages:
        - id: main_page
          widgets:
            - label:
                text: "Control panel"
                align: TOP_MID
                y: 8
                text_font: montserrat_20
    
            - button:
                id: btn_lamp
                x: 16
                y: 50
                width: 136
                height: 64
                checkable: true
                on_click:
                  - homeassistant.action:
                      action: light.toggle
                      data:
                        entity_id: light.living_room
                widgets:
                  - label:
                      text: "Lamp"
                      align: CENTER
    
            - button:
                id: btn_fan
                x: 168
                y: 50
                width: 136
                height: 64
                checkable: true
                on_click:
                  - homeassistant.action:
                      action: switch.toggle
                      data:
                        entity_id: switch.desk_fan
                widgets:
                  - label:
                      text: "Fan"
                      align: CENTER
    
            - label:
                text: "Lamp brightness"
                x: 16
                y: 128
    
            - slider:
                id: sld_bright
                x: 16
                y: 156
                width: 288
                min_value: 1
                max_value: 100
                value: 50
                on_release:
                  - homeassistant.action:
                      action: light.turn_on
                      data:
                        entity_id: light.living_room
                      data_template:
                        brightness_pct: "{{ pct }}"
                      variables:
                        pct: 'return (int) x;'
    
            - label:
                id: lbl_temp
                text: "Panel temp: --"
                x: 16
                y: 196
  2. Click Install. This time you can use Wirelessly once the panel is on your Wi-Fi, or USB again the first time. The panel should show the buttons and slider.
  3. Add it to Home Assistant. Home Assistant should discover the new device. Accept it and paste the API key when asked. Tap Lamp on the panel and the light should toggle.

Notes on this configuration. ESPHome renamed homeassistant.service to homeassistant.action; the old name still works. LVGL uses the single display and touchscreen automatically. The button's checked colour only shows the panel's own state; it does not read the light's real state. To show the real state, import it with a binary_sensor of platform homeassistant and update the button from its on_state.

Ideas to extend it

4Optional: add a temperature sensor

The two expansion connectors expose GPIO 21 and GPIO 22, which suit a BME280. The touch chip already uses its own I2C bus on pins 33 and 32, so you add a second bus on 21 and 22.

Check the voltage before you connect. Measure the VCC pin on the connector with a multimeter. Most BME280 modules need 3.3V. Do not connect 5V to a 3.3V-only module, and never connect 5V signals to the ESP32's pins.

Board: CON2 BME280 module GNDGPIO22 (SCL)GPIO21 (SDA)VCC (3.3V) VCCGNDSCLSDA Ground (black), clock SCL (yellow), data SDA (blue), power (red)
Wiring the optional BME280. The connector order is taken from the board's published pinout (GND, GPIO22, GPIO21, VCC); read the labels on your own board before plugging in.
  1. Power the board off. Connect the four wires as shown. Pigtail cables are usually colour-coded, but match pin names, not colours.
  2. In the configuration from step 3, replace the i2c: section with two buses, and add the sensor below.
    i2c:
      - id: i2c_touch
        sda: GPIO33
        scl: GPIO32
      - id: i2c_ext
        sda: GPIO21
        scl: GPIO22
    
    sensor:
      - platform: bme280_i2c
        i2c_id: i2c_ext
        address: 0x76
        temperature:
          name: "Panel Temperature"
          on_value:
            then:
              - lvgl.label.update:
                  id: lbl_temp
                  text: !lambda 'return str_sprintf("Panel temp: %.1f C", x);'
        humidity:
          name: "Panel Humidity"
        pressure:
          name: "Panel Pressure"
    Merge the sensor: entries with the existing sensor: section (the ambient light sensor) so there is only one sensor: heading. The touchscreen already points at i2c_touch, so it keeps working.
  3. Install again. The temperature appears on the panel and in Home Assistant. If the log says the sensor was not found, try address 0x77.

Troubleshooting

ProblemWhat to try
Upload fails or the board is not foundUse a data cable, try another USB port, hold BOOT while uploading, and install the CH340 or CP210x driver if no serial port appears.
"Unknown platform mipi_spi" when compilingYour ESPHome is too old. Update ESPHome.
Screen draws but flickers or tearsLower data_rate to 20MHz.
Image is the wrong way upChange rotation to 270 and flip the touch transform options to match.
Buttons respond to the wrong spotRe-do the touch transform options from the test in step 2.
Panel works but Home Assistant does nothingCheck the entity names in the buttons, and that the device is adopted in Home Assistant with the right API key. Allow it to perform actions in the device settings.
Panel restarts or Wi-Fi is flakyUse a stable 5V supply of at least 1A.

Alternative to ESPHome. You can also write your own program with the Arduino IDE and LVGL. The setup (a display driver for the ST7789 and a driver for the CST816 touch chip, plus the pins above) is more work, and boards of this family often need vendor-supplied driver files. A good general introduction to LVGL on a 2.8-inch ESP32 display is the Random Nerd Tutorials LVGL guide, though it targets the resistive-touch ILI9341 version of the board, so the display and touch parts will differ.

Sources and credits

This guide was written from the sources above and has not been built end to end on every board revision. Check pins against your own board, and treat voltages and wiring as your own responsibility. Not affiliated with the board makers or with ESPHome.

← Back to the build finder