Getting started

Tessera turns a small ESP32 touch screen into a Home Assistant dashboard. You install one app in Home Assistant, plug in the screen once, and choose its tiles with your mouse. After that, you can change the tiles whenever you like, without installing the screen again.

Inside Home Assistant the app is called ESP Screen Manager, and its page in the sidebar is ESP Screens. This guide calls them "the app" and "ESP Screens".

Know your way around Home Assistant? The Quick start has the six steps on one screen.

In short, four steps:

1. Install the ESP Screen Manager app in Home Assistant.
2. Plug in your screen with a USB cable and click New screen.
3. Add the screen to Home Assistant.
4. Drag the tiles you want onto the screen and click Save & send.

Each step is explained below. The longest wait is the first install of a screen: a few minutes, and longer on a Raspberry Pi.

What you need

• Home Assistant OS on a 64-bit machine, such as a Raspberry Pi 4 or 5 or a regular PC. On Home Assistant Container, which has no app store, follow Install with Docker instead.
• A supported screen. Screens that look alike can have different parts inside, so check the model printed on the board or its box.
• A USB cable that carries data, not a charge-only cable. You need it once, for the first install.
• A 2.4 GHz Wi-Fi network. The screens can't join 5 GHz.

What the status means:

• Stable: the project tried it on real hardware.
• New: it was tried, but only a few of these screens are in use yet.
• Experimental: it is built and tested in software, but not yet tried on the real board. Please tell us how it goes.

The tile counts are for a screen lying down. Standing up gives a different grid.

1. Install the app

1. In Home Assistant, open Settings → Apps and go to the app store. On older versions this is Settings → Add-ons → Add-on Store.
2. Open the menu in the top right and choose Repositories.
3. Add https://github.com/MaxGramser/homeassistant_espscreen.
4. Find ESP Screen Manager in the list and install it.
5. Click Start.
6. Turn on Start on boot and Show in sidebar.
7. Click ESP Screens in the sidebar.

What you'll see: the ESP Screens page, with New screen in its sidebar.

The app brings its own copy of ESPHome, so you don't need the ESPHome Device Builder, MQTT, a blueprint or a long-lived token.

2. Install a new screen

1. Plug the screen into the machine that runs Home Assistant, using the USB data cable. Setting up several screens? Plug in one at a time.
2. In ESP Screens, click New screen.
3. Under Which screen do you have?, pick your board.
4. If your screen can hang both ways, choose Lying down or Standing up under Which way will it hang?. You can't change this later without installing the screen again.
5. Only on a CYD: pick its Display controller. Most CYDs have the first one. If the screen later shows noise or a garbled picture, install again and take the other one.
6. Type a Name, for example Kitchen screen. Every screen needs its own name.
7. The first time only: fill in your Wi-Fi name and password. ESP Screens saves them (in ESPHome's secrets.yaml file), and later screens use them automatically.
8. Under Install via, choose the USB port of this screen.
9. Click Install.

What you'll see: a log with the progress. Building can take 20 minutes or more on a Home Assistant machine such as a Raspberry Pi, the first time especially. That's normal. You can close the window: the install keeps running. When it says Done, the window shows the next steps, with the screen's key behind Show the API key. If something fails, the log stays open and you can click Retry.

On the screen itself you'll see the Tessera logo while it starts and connects. Until you choose tiles in step 4, it says Choose tiles in HA.

Setting up four screens? Go through New screen four times, with four different names. Never use New screen again for a screen you already have: that gives it new keys. To update a screen, use its own button (see Keep your screens up to date).

No USB port in the list?

The normal route is the one above: the screen plugged into the machine that runs Home Assistant. First check that it is plugged in there, with a data cable. A cable in your laptop doesn't count.

Only if Home Assistant still can't see a USB port (for example, it runs in a virtual machine without USB), install the screen from the computer you are using now:

1. Plug the screen into this computer with a USB data cable.
2. Open ESP Screens in Chrome or Edge, over https (for example your Home Assistant Cloud address). Other browsers, and plain http:// addresses, can't reach USB.
3. Under Install via, in Plugged into this computer, choose Install from this browser (Chrome or Edge).
4. Click Connect & install and choose the screen's port.

What you'll see: "Connected", then the build on your Home Assistant machine, then a progress bar while this page writes the firmware to the screen. The screen restarts and joins your Wi-Fi. From now on, updates go over Wi-Fi. Keep the tab open until it's done.

Can't use Chrome or https? Choose Download the file and flash it yourself instead, and install the file with ESPHome Web. The file holds your Wi-Fi password and the screen's keys, so don't share it.

Touch calibration (CYD and Hosyond only)

These two screens have a pressure-sensitive (resistive) touch panel that has to be measured once. On the first start, the screen shows a crosshair:

1. Tap the crosshair three times. Hold each tap briefly and lift your finger in between.
2. Move on to the next crosshair. There are five in total. The last one, in the middle, checks the result.
3. If a measurement fails, the screen asks you to start again.

The screen keeps the result, also through updates. To measure again later, use Calibrate touch in the screen's Screen settings tab. All other screens need no calibration.

3. Add the screen to Home Assistant

This step happens in Home Assistant itself. Until it's done, ESP Screens shows the screen under Screens with the note "not yet in Home Assistant" and an Open Devices & services button.

1. Open Settings → Devices & services.
2. Home Assistant has usually found the screen already: click Add on the ESPHome device. Not there? Add the ESPHome integration by hand, with the screen's IP address and port 6053.
3. Does Home Assistant ask for an encryption key? Paste the screen's API key: in ESP Screens, click Show the API key and copy it. (Not the OTA password, which is only for updates over Wi-Fi.) With the ESPHome Device Builder app installed, Home Assistant often fills it in by itself.
4. On the new ESPHome device, open Configure.
5. Turn on Allow the device to perform Home Assistant actions. Without this, the screen shows values but can't switch anything.
6. Go back to ESP Screens.

What you'll see: within about 30 seconds the screen appears in the ESP Screens sidebar, and the "not yet in Home Assistant" note disappears.

Does Copy API key copy nothing? This can happen when Home Assistant is opened over plain http. The key then appears selected in a box: press Ctrl+C, or Command+C on a Mac. A screen that is already added also has Copy API key, in case Home Assistant asks for the key again later.

4. Put tiles on your screen

1. Click your screen in the ESP Screens sidebar. The Layout tab shows a preview of its pages.
2. In the Library on the right, search by name, device or room, or use the filters.
3. Drag an entity onto a page. Or click an empty cell, then click an entity.
4. Click a tile to change it: its name, what a tap does (On tap), its Size and its Display.
5. Click Save & send.

What you'll see: "Saved · sent to screen", and within seconds the tiles appear on the screen. To change tiles later, just do this again. You never need to reinstall the screen for it.

Good to know:

• Sizes. A tile can be Normal (one cell), Double-width, 1 × 2, 2 × 2 or Full page. You can also drag a tile's edge.
• Pages. A screen holds up to eight pages and 64 tiles. + Add page adds one. Any page can be the Home page: the one the house button and "back to Home" go to.
• Cameras. On a screen with camera pictures, set a camera tile to Display → Live picture and the picture fills the tile. It refreshes every 5, 10, 15 or 30 seconds, your choice. See Cameras & snapshots.
• Clock. The built-in Clock is at the top of the library. Under Display, pick Digital clock, Analog clock, Simple dial or Flip clock.
• Live preview. The preview shows the real values from Home Assistant, so you see what the screen will show.

What a tap does on the screen:

Hold any tile to open its full card: for a light its brightness and colour, for a fan its speed.

You can change this under On tap. For example, Perform action runs any action Home Assistant offers for that entity. Pages & tiles explains pages, top bars and tile sizes in more detail.

A day after a new screen first comes online, its page in ESP Screens asks once: Does your screen work as you expect? Answering is optional and helps improve support for your board. What is shared? on the card lists exactly what is sent. You can change or delete your answer later under Screen settings → Feedback.

5. What the screen tells you

You can save tiles while a screen is offline. The app sends them as soon as the screen is back. Keep the app running: the screen needs it to show current values.

6. Screen settings

Open your screen in ESP Screens and click its Screen settings tab. A change applies at once: there is nothing to save. You can change the same settings on the screen itself (hold the top bar) and on the screen's device in Home Assistant, for example from an automation.

The Waveshare 4.3-inch and 7-inch screens have a backlight that is only on or off, so they have no brightness, standby or night settings. The 12 or 24-hour clock is set for all screens at once, under Settings → Language & region. Screen settings has every detail.

7. Keep your screens up to date

Update the ESP Screen Manager app first, then update each screen. A screen with newer software than the app shows "Configuration problem. Update add-on." until the app catches up.

To update every screen by itself, turn on Settings → Firmware updates → Update automatically every night in ESP Screens. It updates one screen at a time, between 03:00 and 06:00.

Before you update:

1. Make a Home Assistant backup that includes the ESP Screen Manager app.
2. Update the app. Never remove and reinstall it: that can erase your tiles.
3. Afterwards, reload any ESP Screens tab that was open during the update.

A screen that keeps restarting can't update over Wi-Fi. Install it once over USB from Firmware & USB, the same way as in step 2. Screens on firmware 0.3.6 could keep restarting on "Loading tiles". Firmware 0.3.7 and newer fixes this.

8. Advanced: Override YAML

Some boards sold under the same name use a different display part. For those, each screen has a small file of its own for changes that survive every update.

1. Open the screen in ESP Screens.
2. Choose More → Override YAML.
3. Add your change.
4. Click Save & check.
5. Click Update to build it.

The most common changes are one line:

substitutions:
  DISPLAY_MODEL: "ST7789V"

A new CYD doesn't need this for its display controller: New screen already asks for it. The override must still match the physical board. PROFILES.md lists everything an override can rely on.

9. Remove a screen

1. Unplug the screen first. A screen that is still powered on announces itself to Home Assistant again.
2. Open the screen in ESP Screens.
3. Click Remove screen.
4. Read the list of what goes, and confirm.

What goes:

• The screen's device and entities in Home Assistant. The list shows where automations or dashboards use them.
• The screen's ESPHome files that ESP Screens created.
• Its tiles, settings and update history in the app.

If something doesn't work

For more, see Troubleshooting.