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: its name, its Wi-Fi (from secrets.yaml), its API key and update password, its language and the way it hangs. Everything else comes from one line that points at the shared firmware on GitHub:

packages:
  display:
    url: https://github.com/MaxGramser/homeassistant_espscreen
    ref: main
    files: [packages/guition.yaml]
    refresh: 0s

The file is yours. A build fetches the shared part fresh, so you never replace your own YAML with a downloaded one. The screen's details in Tessera have Download screen files, a zip with exactly the files a build needs.

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. Device Builder needs ESPHome 2026.6.2 or newer; the 10.1-inch Guition needs 2026.8.0, the Waveshare 7B 2026.7.0.

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

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:

substitutions:
  DISPLAY_MODEL: "ST7789V"

Setting	Boards	What it changes
DISPLAY_MODEL	CYD, Hosyond	The display chip: ILI9341, ST7789V, ST7796
DISPLAY_DATA_RATE	CYD, Hosyond	The display speed; some boards need 20MHz
DISPLAY_INVERT_COLORS	CYD, Hosyond	"true" when every colour shows as its opposite
BACKLIGHT_FREQUENCY	CYD, Guition 4 and 3.5 inch, Waveshare 4B and 3.5 inch, Hosyond	How fast the backlight is dimmed
GRID_ROWS	Guition 4 inch	4 for four rows of smaller tiles

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: the way a screen hangs is chosen under New screen.

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.