Flash a screen yourself

Tessera builds and installs the firmware for you. You can also do it yourself, with ESPHome Device Builder or the ESPHome command line, and the screen works the same in Tessera.

The screen's YAML ​

Every screen has a small YAML file of its own in the ESPHome folder of your Home Assistant configuration. It holds its name, Wi-Fi, API key, update password and a package reference to the shared firmware on GitHub.

Use Download screen files in the screen's details to get a zip with the files a build needs. Keep the package reference from that download. The stable app pins it to its own release, such as screens-v0.4.87 for app 0.4.87; the dev app uses dev. Changing it to main can build firmware newer than your installed app supports.

The file is yours. A build fetches the shared package at that reference, so you never replace your own YAML with a downloaded example.

With ESPHome Device Builder ​

Device Builder finds the screens' files in the ESPHome folder by itself; Tessera and Device Builder can share the folder. Install → Plug into this computer, Wirelessly or Manual download all work with the file. Use ESPHome 2026.9.0 for this release, the version included and tested with the app.

For an existing screen, always use its existing file. A new file means new keys, and Home Assistant sees a new device.

Into Home Assistant ​

A screen whose file is in the ESPHome folder Tessera reads joins Home Assistant by itself: once it is on your Wi-Fi, Tessera adds it with the key in that file and allows it to perform Home Assistant actions. That goes for a screen you install with Device Builder, and for one you build on your own computer from Download screen files, since its file stays in the folder.

A screen built from a file Tessera doesn't see, such as your own YAML and the ESPHome command line on another computer, is added by hand, like any ESPHome device: Add to Home Assistant by hand.

From Tessera, by hand ​

Firmware & USB in the sidebar builds any screen's file and installs it: on a USB port of the Home Assistant machine, from your browser on a screen plugged into this computer, over Wi-Fi to an address you type, or as a download. Check only validates; Build only builds without installing.

A USB install from Firmware & USB writes without erasing, so the screen keeps its settings and touch calibration. That is also the rescue for a screen that keeps restarting.

Override YAML ​

Some boards sold under one name have different parts inside. For those, every screen has a second small file, loaded after the shared firmware and kept through every update. Open it with Override YAML in the screen's ··· menu. The most common change is one line:

yaml
substitutions:
  DISPLAY_MODEL: "ST7789V"
SettingBoardsWhat it changes
DISPLAY_MODELCYD, HosyondThe display chip: ILI9341, ST7789V, ST7796
DISPLAY_DATA_RATECYD, HosyondThe display speed; some boards need 20MHz
DISPLAY_INVERT_COLORSCYD, Hosyond"true" when every colour shows as its opposite
BACKLIGHT_FREQUENCYCYD, Guition 4 and 3.5 inch, Waveshare 4B and 3.5 inch, HosyondHow fast the backlight is dimmed

Save & check validates the whole file with ESPHome; Update then builds it. The name, Wi-Fi, API, update password and package lines stay managed by Tessera, and a choice you made under New screen, such as the CYD's display chip, wins over the override. To change the display itself, use id: !extend my_display; a bare id: adds a second display and the build fails. Don't copy rotations from old forum posts: choose its orientation with Grid beside the pages in the editor.

The same file takes your own hardware: a wall button, a temperature sensor or a relay on a spare pin. Buttons, sensors and other hardware has the recipes.

Migrating a screen you built before ​

Keep the old YAML's device name, API key and update password in the new file, and the screen stays the same device in Home Assistant. Tiles you had fixed in YAML are not imported; choose them in Tessera.

Boards with 4 MB of flash ​

The CYD and the Hosyond moved to a partition table of their own. If you flash those yourself, read Screens with 4 MB of flash once.