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.
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
- 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. - Add your secrets. In the ESPHome builder, open Secrets and add these four lines with your own values. Keep this file private.
You can generate the API key in the builder when you create a new device, or at esphome.io/components/api.wifi_ssid: "YourWiFiName" wifi_password: "YourWiFiPassword" api_key: "paste a generated 32-byte base64 key here" ota_password: "choose-a-password" - 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.
- 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); - 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.
- 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 see | Try |
|---|---|
| Blank screen, backlight off | The backlight is GPIO27 on this guide's pin set. Confirm in the log that the light turned on. |
| Backlight on, no picture | Your revision may use different display pins. See the warning above. |
| Wrong colours (inverted) | Add invert_colors: true under the display. |
| Touch is mirrored or sideways | Change the transform options: toggle swap_xy, mirror_x and mirror_y until the coordinates match your finger. |
| No touch messages at all | Check 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.
- 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 - 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.
- 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
- Add more buttons, or a second
pageand swipe or tap to switch pages. - Use the built-in light sensor to dim the backlight in dark rooms.
- Show weather or a sensor from Home Assistant using a
sensorof platformhomeassistantandlvgl.label.update. - Add scene buttons that call
scene.turn_on.
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.
- Power the board off. Connect the four wires as shown. Pigtail cables are usually colour-coded, but match pin names, not colours.
- In the configuration from step 3, replace the
i2c:section with two buses, and add the sensor below.
Merge thei2c: - 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"sensor:entries with the existingsensor:section (the ambient light sensor) so there is only onesensor:heading. The touchscreen already points ati2c_touch, so it keeps working. - 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
| Problem | What to try |
|---|---|
| Upload fails or the board is not found | Use 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 compiling | Your ESPHome is too old. Update ESPHome. |
| Screen draws but flickers or tears | Lower data_rate to 20MHz. |
| Image is the wrong way up | Change rotation to 270 and flip the touch transform options to match. |
| Buttons respond to the wrong spot | Re-do the touch transform options from the test in step 2. |
| Panel works but Home Assistant does nothing | Check 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 flaky | Use 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
- Guition ESP32 2.8" LCD Display JC2432W328C, ESPHome device page: pin assignments and the base configuration this guide builds on.
- ESPHome LVGL documentation and API / Home Assistant action documentation: syntax for widgets and
homeassistant.action. - Community vendor-package notes for the JC2432W328C: Arduino-side information and the differing pin listing mentioned above.
- f1atb.fr overview of the 2.8-inch ESP32 display family.