Buttons, sensors and other hardware

Your screen is a complete ESPHome device, and most boards have a few pins left over. Wire a button for the hallway light to one, a temperature sensor or a motion sensor to another, and add a few lines to the screen's Override YAML. After one update it shows up in Home Assistant next to the screen's own entities. From there it works like any other entity: in automations, on dashboards, and as a tile on any of your screens.

No new firmware needed

This works on every screen today. Tessera only uses the pins its display, touch and backlight need and leaves the rest to you. What you add lives in the screen's own Override YAML, so it stays through every update.

How to add something

1. Wire it to a free pin, with the screen unplugged. Find a free pin below says which ones you can use.
2. Open the screen in Tessera, press ··· and choose Override YAML.
3. Paste a recipe from this page. Change the pin, the names and the entity ids to match your home. If the file already has something in it, add the new blocks next to it. Each key, such as binary_sensor: or sensor:, appears only once in the file.
4. Press Save & check. ESPHome reads the whole file. A typo or a pin that is already taken shows up here, before anything is built.
5. Press Update firmware. The screen builds and installs over Wi-Fi. You don't need the USB cable.

Find a free pin

A pin your screen's display, touch or backlight uses is taken. Use one of them and the glass stays dark or the touch stops working.

CYD 2.8 inch

The CYD has two small connectors on its back. The drawings below show their pins by name. Go by those names, not by the position on the connector, which can differ between batches of the board.

Connector	Pins	What you can use
CN1	GND, IO22, IO27, 3V3	IO22 and IO27, for buttons, sensors and outputs. The connector also gives you 3.3 V and ground.
P3	GND, IO35, IO22, IO21	IO35 is input only, with no pull-up of its own: a button on it needs a resistor to 3.3 V. IO22 is the same pin as on CN1. IO21 drives the backlight: leave it alone.

Other screens

The page of your screen under Supported screens names its spare pins where they are known. You can also read which pins the screen uses in its board file in the repository, under packages/boards. Every pin you find there is taken.

Pins that decide how the chip starts

Some pins tell the chip how to start. A part that holds one of them high or low at power-on can keep the screen from starting at all. On the classic ESP32 (the CYD and the Hosyond) that is GPIO0, 2, 5, 12 and 15; on the ESP32-S3 GPIO0, 3, 45 and 46. GPIO34 to GPIO39 on the classic ESP32 are input only, with no pull-up of their own.

Recipes

A wall button for a light

A push button between a pin and GND. The pin's own pull-up keeps it high, a press pulls it low, and the screen asks Home Assistant to toggle the light.

Each button between its pin and GND. No resistor: the pin's own pull-up holds it high.

binary_sensor:
  - platform: gpio
    id: hallway_button
    name: "Hallway button"
    pin:
      number: GPIO22
      mode:
        input: true
        pullup: true
      inverted: true
    filters:
      - delayed_on_off: 30ms
    on_press:
      - homeassistant.action:
          action: light.toggle
          data:
            entity_id: light.hallway

• inverted: true makes the entity read On while you hold the button down.
• delayed_on_off: 30ms filters out the bounce of the contacts. Without it one press can toggle the light twice.
• A second button is a second entry under binary_sensor:, with its own id, name and pin.
• Any Home Assistant action works here: scene.turn_on, script.turn_on, cover.toggle, with the entity_id it needs.

Rather switch the light from an automation?

Leave out the on_press: part. The button is then just an entity, and a Home Assistant automation with the button turning on as its trigger switches whatever you like. Either way the button needs Home Assistant running, because it's Home Assistant that switches the light.

A rocker switch

A wall switch that stays where you flip it. Wire it the same way as a button, and use on_state: instead of on_press:, so every flip toggles the light, whichever way it goes:

binary_sensor:
  - platform: gpio
    id: porch_switch
    name: "Porch switch"
    pin:
      number: GPIO27
      mode:
        input: true
        pullup: true
      inverted: true
    filters:
      - delayed_on_off: 30ms
    on_state:
      - homeassistant.action:
          action: light.toggle
          data:
            entity_id: light.porch

A DS18B20 temperature sensor

The DS18B20 is a cheap, accurate temperature sensor with three wires. Data goes to a free pin, the other two to 3V3 and GND. A 4.7 kΩ resistor between data and 3V3 keeps the line high. Some DS18B20 modules already have that resistor on board.

Seen from its round side. Data (DQ) to IO27, power to 3V3 and GND, and a 4.7 kΩ resistor between data and 3V3.

one_wire:
  - platform: gpio
    pin: GPIO27

sensor:
  - platform: dallas_temp
    name: "Temperature"
    update_interval: 60s

• In Home Assistant it gets the screen's name in front, for example Hallway screen Temperature.
• More than one sensor on the same wire? Each one then needs its own address:. The screen's log lists the addresses it finds when it starts.

Keep it away from the screen

The board and the backlight get warm. A sensor taped to the board or inside the case reads a few degrees too high. Put it on a short cable outside the case.

A motion sensor

A motion sensor with a digital output that runs on 3.3 V, such as the small AM312. Power from 3V3 and GND, its output to a free pin:

binary_sensor:
  - platform: gpio
    id: hallway_motion
    name: "Motion"
    device_class: motion
    pin: GPIO22

With device_class: motion Home Assistant shows it as Detected and Clear, with the icon for motion, and so does its tile.

A relay or an LED

An output the screen switches: an LED, or a relay module that takes a 3.3 V signal. It becomes a switch in Home Assistant.

switch:
  - platform: gpio
    id: desk_lamp_relay
    name: "Desk lamp"
    restore_mode: RESTORE_DEFAULT_OFF
    pin: GPIO27

Mains voltage

Never wire mains voltage to the screen's board. Use a relay module made for it, in a closed case, and leave mains work to someone qualified. The 4 inch Guition sold on a wallbox base has its relays built in: its page under Supported screens links to the lines for them.

Show it on a tile

What you add is an entity of the screen in Home Assistant, like any other. In Tessera, open a page, press Add tile and pick it: a temperature shows as a value or a graph, a button or a motion sensor as a status. It can go on the screen it is wired to and on any of your other screens.

When it doesn't work

What you see	What to check
Save & check says a pin is used in multiple places	The pin is taken by the display, the touch or the backlight. Pick another one.
A press toggles the light twice	Raise the filter to delayed_on_off: 50ms.
A press does nothing, but the button entity changes	Home Assistant must allow the screen to perform actions. Tessera turns that on for every screen it knows. In Home Assistant it's under the ESPHome integration's Configure.
The button entity never changes	The wiring: one side of the button on the pin, the other side on GND.
The temperature reads 85 °C, or nothing at all	The 4.7 kΩ resistor is missing, or data and power are swapped. 85 °C is the value a DS18B20 reports before its first real measurement.
The build stops: the firmware is too large	The CYD and the Hosyond have 4 MB of flash and little room left. A button or a sensor takes a few kilobytes, but a long list of extras can be too much.

Share what you built

Got something working on your screen? Tell others which board you have and what you wired to it, or add your recipe to this page with Edit this page below.