12-button CYD touch panel

Some hardware links on this page are affiliate links. As an Amazon Associate I earn from qualifying purchases. We may earn a commission if you buy through them, at no extra cost to you. See the affiliate disclosure.

A Cheap Yellow Display is a $10-ish ESP32 with a resistive touchscreen already soldered on. This pack turns that board into a twelve-button scene panel: each cell shows a Home Assistant entity’s state (color + icon) and a tap toggles or calls an action. No extra keypad, no tablet kiosk.

Entity ids stay in substitutions. Do not paste a live house’s switch names into a published YAML.

What problem it solves

You want a dedicated tap surface next to a desk, bed, or workbench — lights, a fan, a script — without unlocking a phone or hunting a dashboard.

How it works

1. Display + touch in ESPHome — stock CYD pinout (ILI9341 SPI, XPT2046 touch, backlight GPIO). LVGL draws a 3×4 grid.
2. Each button is a set of substitutions — label, icon, entity id, and action at the top of the YAML. You fill twelve sets (or fewer, and hide the rest with bN_hidden).
3. Tap → HA action — short click runs homeassistant.action (toggle, turn_on, or a script). The device is a native-API node, not a browser.
4. Live state — a homeassistant text sensor subscribes to each entity’s state. On change, LVGL updates the cell background and icon (on = amber, off = dim navy, unavailable = muted).
5. Wake the panel — backlight comes up on touch and dims after idle so a bedroom panel is not a night light.

Default colors follow the site palette; swap them in substitutions if you want a different on-state.

Hardware notes

• Board. ESP32-2432S028 (the common 2.8″ “CYD”). Variants exist (C, 2-USB, capacitive). The pack YAML comments the stock resistive pinout; a capacitive sibling needs a different touch component.
• Power. USB-C 5 V. Avoid powering from a flaky hub if the backlight flickers on tap.
• Mount. A printed bezel hides the yellow PCB. Resistive touch wants a firm press; do not cover the screen with thick glass.
• Wi-Fi. 2.4 GHz only. Credentials stay in secrets.yaml — never in the published file.

Snippet

Each cell reads its label, icon, entity, and action from substitutions at the top of the file. One cell, trimmed:

substitutions:
  b1_label: "Ceiling"
  b1_entity: "light.change_me_1"
  b1_action: "homeassistant.toggle"
  b1_icon: "\U000F0769"

lvgl:
  pages:
    - id: panel_page
      widgets:
        - button:
            id: btn_1
            widgets:
              - label:
                  id: icon_1
                  text: "${b1_icon}"
              - label:
                  id: label_1
                  text: "${b1_label}"
            on_short_click:
              - homeassistant.action:
                  action: ${b1_action}
                  data:
                    entity_id: ${b1_entity}

text_sensor:
  - platform: homeassistant
    id: ha_state_1
    entity_id: ${b1_entity}
    internal: true
    on_value:
      - lvgl.widget.update:
          id: btn_1
          bg_color: !lambda |-
            return x == "on" ? lv_color_hex(0xC9A227) : lv_color_hex(0x1A2744);
# display, touch calibration, fonts, and the other eleven cells: full YAML in the pack

Setup outline

1. Add the CYD in ESPHome (USB first). Confirm the display lights and a tap registers in the logs.
2. Paste the pack YAML into the device, then fill the substitution labels, entity ids, and actions for the buttons you actually use.
3. Let Home Assistant adopt the node over the native API. Grant the device permission to call actions.
4. Calibrate touch if corners miss. Walk each button: tap → entity changes; change the entity elsewhere → cell color follows.

Troubleshooting

• White screen / no LVGL. Backlight GPIO or dc_pin does not match this CYD rev. Check the silkscreen (one-USB vs two-USB) against the pack comments.
• Taps land on the wrong cell. Resistive calibration is off, or swap_xy / invert flags are wrong. Recalibrate; do not guess with a rotation that the driver already applied.
• Tap does nothing in HA. The ESPHome device is missing action permission, or the entity id in the substitution is not the one HA knows. Check Settings → Devices → ESPHome → “Allow device to perform Home Assistant actions.”
• State color stuck. The homeassistant sensor platform never subscribed (typo in the entity id) or the entity is unavailable. Confirm the id in Developer Tools, not in a dashboard alias.

Credits

Based on CYD-panel-party and CYD-ESPHome-HA-Monitor. This write-up is an original overview; the pack YAML is a generic 12-button pattern, not a copy of those repos.