The Complete Beginner’s Guide to Using a Cheap Yellow Display (CYD) with ESPHome

Are you looking for an ultra-low-cost way to add a touchscreen display to your Home Assistant smart home? The Cheap Yellow Display (CYD) , an ESP32-based development board with a built-in 2.8-inch touchscreen, is the perfect entry point. It offers incredible value for building custom dashboards, control panels, and visual indicators for your home automation projects.

This guide is written specifically for absolute beginners who have grabbed one of these boards and want to get it working with ESPHome, the powerful framework that seamlessly integrates ESP32 devices with Home Assistant. We’ll bypass the outdated tutorials and confusing jargon, giving you a clear, step-by-step path from unboxing to a working, touch-interactive display.

What is the Cheap Yellow Display (CYD)?

The “Cheap Yellow Display” is the maker community’s nickname for a family of very similar ESP32 development boards, typically the ESP32-2432S028 variant. They combine:

• An ESP32 microcontroller: 240MHz dual-core, 320KB RAM, 4MB flash.

• A 2.8″ resistive touchscreen: 320×240 pixel resolution, ILI9341 display driver, and an XPT2046 touch controller.

• All built-in: No need to wire a separate display; it’s all on one board, ready to go.

Its popularity exploded because it’s a complete, ready-to-use hardware platform for anyone wanting to build a portable, Wi-Fi-connected touch interface without breaking the bank.

Why Use ESPHome with Your CYD?

If you’re already using Home Assistant, ESPHome is a game-changer. It turns your ESP32 (and thus your CYD) into a first-class citizen of your smart home. Instead of writing complex C++ code, you configure devices using simple YAML files. ESPHome handles the compilation, over-the-air (OTA) updates, and deep integration with Home Assistant, making your CYD show up as entities you can automate and monitor.

Where to Buy Your CYD for the Best Price

You can find these boards easily by searching esp32s.com for “CYD” or “ESP32 2.8 inch touchscreen“. To get the absolute best value, look for “Bundle Deals” where you can buy multiple boards together.

Part 1: Getting ESPHome on Your CYD (The First Hurdle)

Your first task is to flash the ESPHome firmware onto the CYD. This is done via USB using the ESPHome Web installer.

1. Go to the ESPHome website and navigate to the “ESPHome Device Builder”.

2. Plug in your CYD via USB.

3. Click “Connect” and select the correct serial port.

4. When the “Preparing installation…” spinner appears, you must hold down the BOOT button on the back of the CYD. This is a crucial step that’s easy to miss! Keep holding it until the process starts.

5. Once installed, you can add it to your Home Assistant setup.

Part 2: The Minimal ESPHome YAML Configuration to Light Up the Screen

Once ESPHome is running and connected to your Wi-Fi, the fun begins. Below is the absolute minimum YAML configuration you need to get the display’s backlight on and show a test pattern. This verifies your wiring and basic setup are correct.

You’ll need to replace "xxxx" with your actual Wi-Fi credentials.

esphome:
  name: cyd

esp32:
  board: esp32dev
  framework:
    type: arduino  # 'arduino' is more stable for beginners than esp-idf here

logger:

api:

ota:
  - platform: esphome

wifi:
  ssid: "xxxx"
  password: "xxxx"

# --- CYD Specific Configuration Starts Here ---

# Control the display backlight (without this, the screen looks blank)
output:
  - platform: ledc
    pin: GPIO21
    id: backlight_pwm

light:
  - platform: monochromatic
    output: backlight_pwm
    name: "CYD Display Backlight"
    id: backlight
    restore_mode: ALWAYS_ON

# Define the SPI bus for the display
spi:
  - id: tft
    clk_pin: GPIO14
    mosi_pin: GPIO13
    miso_pin: GPIO12  # Often not used for display-only, but defined

# Configure the display itself
display:
  - platform: ili9xxx
    model: ILI9341
    spi_id: tft
    cs_pin: GPIO15
    dc_pin: GPIO2
    invert_colors: false   # Crucial: Set to false for CYD
    color_palette: 8BIT     # Crucial: Saves RAM, 16-bit is too much!
    show_test_card: true    # Displays a simple test pattern
    rotation: 0
    dimensions:
      width: 320
      height: 240

Upload this YAML. If all goes well, your CYD screen will light up and display the ESPHome test card. You’ve just conquered the hardest part!

Part 3: Calibrating the Resistive Touchscreen

The XPT2046 touch controller on the CYD is inexpensive and requires calibration. It doesn’t inherently know where your finger is on the screen. We need to teach it.

Upload this YAML, which adds the touchscreen component and logs raw touch values:
*(Remember to keep your Wi-Fi and display sections from Part 2)*

# ... (Keep your esphome, esp32, logger, api, ota, wifi, output, light, spi, and display sections from Part 2) ...

# Add a second SPI bus for the touchscreen
spi:
  - id: tft
    clk_pin: GPIO14
    mosi_pin: GPIO13
    miso_pin: GPIO12
  - id: touch_spi
    clk_pin: GPIO25
    mosi_pin: GPIO32
    miso_pin: GPIO39

# Add the touchscreen component
touchscreen:
  platform: xpt2046
  id: my_touchscreen
  spi_id: touch_spi
  cs_pin: GPIO33
  interrupt_pin: GPIO36
  # Placeholder calibration - we will replace this
  calibration:
    x_min: 0
    x_max: 4095
    y_min: 0
    y_max: 4095
  transform:
    swap_xy: true   # Often needed to correct axis orientation
  on_touch:
    - lambda: |-
        ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%d",
            touch.x,
            touch.y,
            touch.x_raw,
            touch.y_raw
        );

1. Upload this configuration. The screen will likely still show the test card.

2. Open the ESPHome logs for your device.

3. Take a stylus (or a fingernail) and carefully tap the four corners of the screen as close to the edge as possible. Watch the logs. You’ll see lines like:
   [10:50:48][I][cal:076]: x=319, y=238, x_raw=3823, y_raw=3835
[10:50:51][I][cal:076]: x=237, y=232, x_raw=208, y_raw=3748
[10:50:52][I][cal:076]: x=319, y=0, x_raw=3798, y_raw=288
[10:50:55][I][cal:076]: x=257, y=0, x_raw=225, y_raw=282

4. Find the minimum and maximum x_raw and y_raw values from your taps. Use these to update the calibration: section in your YAML. For the example above, the values would be:

   yaml

   calibration:
     x_min: 208
     x_max: 3823
     y_min: 282
     y_max: 3835

5. Re-upload with your new calibration values. Your touchscreen is now much more accurate.

Part 4: Your First Interactive Project – A Toggle Screen

Now let’s combine everything. This example displays “Hello World!” centered on the screen. Tapping anywhere on the screen toggles the text to “Goodbye World!” and back again. This demonstrates reading touch input and updating the display dynamically.

Here is the complete YAML. You’ll need to add your Wi-Fi credentials and potentially adjust the calibration values from the previous step.

esphome:
  name: cyd

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:

api:

ota:
  - platform: esphome

wifi:
  ssid: "xxxx"
  password: "xxxx"

# --- New: Font Configuration ---
# We need a font to draw text. This pulls Roboto from Google Fonts.
font:
  - file:
      type: gfonts
      family: Roboto
    id: roboto_large
    size: 40
    bpp: 4  # Bits per pixel (4 for good anti-aliasing)

# --- New: Global Variable ---
# This variable will track whether to show "Hello" or "Goodbye"
globals:
  - id: display_hello
    type: bool
    initial_value: 'true'

output:
  - platform: ledc
    pin: GPIO21
    id: backlight_pwm

light:
  - platform: monochromatic
    output: backlight_pwm
    name: "CYD Display Backlight"
    id: backlight
    restore_mode: ALWAYS_ON

spi:
  - id: tft
    clk_pin: GPIO14
    mosi_pin: GPIO13
    miso_pin: GPIO12
  - id: touch_spi
    clk_pin: GPIO25
    mosi_pin: GPIO32
    miso_pin: GPIO39

display:
  - platform: ili9xxx
    model: ILI9341
    spi_id: tft
    cs_pin: GPIO15
    dc_pin: GPIO2
    invert_colors: false
    color_palette: 8BIT
    rotation: 0
    dimensions:
      width: 320
      height: 240
    # --- New: Lambda to draw text ---
    lambda: |-
      auto font = id(roboto_large);
      const char* text;

      if (id(display_hello)) {
        text = "Hello World!";
      } else {
        text = "Goodbye World!";
      }

      // Calculate position to center the text
      int x1, y1, text_width, text_height;
      it.get_text_bounds(0, 0, text, font, TextAlign::TOP_LEFT, &x1, &y1, &text_width, &text_height);
      int x = (it.get_width() - text_width) / 2;
      int y = (it.get_height() - text_height) / 2;

      // Draw the text
      it.print(x, y, font, COLOR_WHITE, TextAlign::TOP_LEFT, text);

touchscreen:
  platform: xpt2046
  id: my_touchscreen
  spi_id: touch_spi
  cs_pin: GPIO33
  interrupt_pin: GPIO36
  # --- IMPORTANT: Replace with YOUR calibration values from Part 3 ---
  calibration:
    x_min: 208
    x_max: 3823
    y_min: 282
    y_max: 3835
  transform:
    swap_xy: true
  # --- New: on_touch trigger to toggle the global variable ---
  on_touch:
    lambda: |-
      id(display_hello) = !id(display_hello);

Upload this to your CYD. You now have a fully functional, touch-interactive display running on ESPHome, integrated with Home Assistant. The global variable display_hello could even be exposed to Home Assistant, allowing automations to change the text on the screen!

From Beginner to Builder

You’ve successfully navigated the initial pitfalls of the CYD and have a working platform for endless smart home projects. From here, you can:

• Display sensor data from your Home Assistant.

• Create touch buttons to control lights and switches.

• Build a dedicated panel for your security system or media center.

The Cheap Yellow Display, combined with the power of ESPHome and Home Assistant, puts a world of custom, connected touch interfaces at your fingertips—all for the price of a couple of coffees.

Contact Us