Tessera

Touch screens for Home Assistant. A screen for every room, one simple editor.

Website · Quick start · Supported screens · Community · My screen works

_{Tessera is the new name for ESP Screens. In Home Assistant the app is called Tessera Screen Manager and its panel Tessera (app 0.3.18); the repository, the add-on and your screens stay exactly as they are.}

Thank you! I work on this project with a lot of love, and every bit of support helps. I truly love the Home Assistant community.

The Guition 4-inch screen on a table: the second page with scenes and scripts, the robot vacuum and a table lamp with a brightness slider The vacuum card on the Guition: docked and charging, start cleaning and dock, the cleaning mode, suction and water

A touch screen for every room that you lay out yourself, and manage from Home Assistant. Incredibly easy to set up and to use.

Why. Your phone is in the other room and a tablet on the wall is expensive. A small ESP32 touch panel costs a fraction of that, sits on a table or in a wall box, and is always at hand for the lights, the heating or the vacuum.

What. Firmware for affordable panels, five of them today, from the 2.8-inch CYD to the 10.1-inch Guition, with tiles over up to eight pages, as many per page as the glass holds: lights, climate, blinds and curtains, the vacuum, media, the weather, history graphs, clocks and timers, your alarm with its keypad, and your cameras on every screen with room for pictures. A tile can take the whole page, one big switch you push without looking, and a tile can go to another page. An automation can put an alert on every screen when someone rings the bell, and a screen with room for pictures shows who is there with the doorbell camera's picture. A tap can run any action Home Assistant has for a tile, and Dark mode suits a screen beside the bed.

How. ESP Screen Manager is an app inside Home Assistant. It flashes a new screen over USB, updates it over Wi-Fi and sends it your tiles. Changing a screen is pick, drag and Save & send: no reflash, no YAML to write, no blueprint, MQTT or token. Brightness, night hours and Dark mode can also be changed on the screen or by an automation, and your own YAML for one screen survives every update.

Install it · Documentation · Pages and tiles · Troubleshooting · What's new

The full documentation is on the Tessera website: a quick start, getting started, pages and tiles, screen settings, cameras, Docker and troubleshooting, kept up to date for users. This README is the overview; the files under docs/ are the reference for contributors.

In real life

A Guition in the living room, 37 seconds in one take: tapping tiles, swiping through the pages, opening cards and a history graph, while the lamp behind it goes from purple to orange.

https://github.com/user-attachments/assets/f9f6a933-d388-4c8b-9c9a-011dfa37617b

The Guition on a wooden sideboard beside a glowing purple lamp: the living room page with the airco, an analog clock with the date, two scenes and a dimmer at 36 percent The same screen showing a temperature history over 24 hours, with its highest and lowest point marked and the 1 hour, 24 hours and 1 week keys The light card of the purple lamp: the colour slider at 304 degrees, the brightness slider at 20 percent and the effects key at the top right

_{Real photos, not renders: the 4-inch Guition next to the lamp it controls.}

Five screens supported, 2.8 to 10.1 inch

One home, five panels. A screen is built for the glass it runs on: it measures its own canvas at boot and gives a page the cells that board has, six tiles on the 2.8-inch CYD and twenty on the 10.1-inch Guition, while a tile stays about the same size in millimetres. The same tiles, the same cards, the same editor; the bigger the glass, the more of your home fits on one page.

The five supported screens side by side on one scale, each showing a page of the same home: the small 2.8-inch CYD, the square 4-inch Guition, the wide 4.3-inch Waveshare, the 7-inch Waveshare and the large 10.1-inch Guition

_{To scale, each with the page it fills: the same home on the 2.8-inch CYD, the 4-inch Guition, the 4.3-inch and 7-inch Waveshare, and the 10.1-inch Guition. Rendered from the firmware's own code, one board at a time.}

The kitchen page on the 2.8-inch CYD: the weather with five days, a pasta timer, the coffee machine, the kitchen lamp and the power usage The living room page on the 4-inch Guition: an analog clock with the date, a temperature graph, the weather, the table lamp and Sam at home The hallway page on the 4.3-inch Waveshare: a clock, a wide temperature graph, the weather, Sam, the heating with minus and plus, and the table lamp

The bedroom page on the 7-inch Waveshare: sixteen cells with a clock, a wide temperature graph, the weather, the heating, the ceiling light and Sonos with sliders, the energy graph, the robot and a good-night script The study page on the 10.1-inch Guition: twenty cells with a clock, graphs, the weather, the heating, the ceiling light, a timer, Sonos, the curtains, the power usage, the robot, the coffee machine and a good-night script

Two of the same screens built standing up, to scale: the 10.1-inch Guition as a kitchen wall panel with twenty tiles over four columns, and the 7-inch Waveshare by the front door with fourteen tiles in two columns

_{The same home standing up. Which way a screen hangs is chosen when it is built, and every board that is not square hangs either way, with a grid of its own: the 10.1-inch Guition 4 × 5 instead of 5 × 4, the 7-inch Waveshare 2 × 7 instead of 4 × 4. Which board is which, and what to look for when you buy one: Which screen.}

Taller tiles, richer cards

A full page on the 10.1-inch Guition: a clock with the date, the weather for five days, a media tile two cells wide and two high with the album cover dimmed behind the title and the play keys, the blinds one cell wide and two high with a position slider, the heating two by two with minus, plus and every mode key, a temperature graph, a table lamp dimmer and a coffee machine switch

The 4-inch Guition: a media tile two by two with the album cover behind the track, the artist and the previous, pause and next keys, above a table lamp with its dimmer The heating two by two: the target temperature between minus and plus, the room temperature under it and a row of mode keys, heat lit in orange, above a temperature graph Two tiles one cell wide and two high: the blinds with their position in large type and a slider, and the coffee machine with its icon, name and switch in the middle; the robot vacuum with start, stop and dock below

The 4.3-inch Waveshare: the media tile two by two with its album cover, a bedroom thermostat one cell wide and two high, a lamp dimmer and a person The same screen in dark mode: the heating two by two with its mode keys beside the setpoint, the blinds one by two, a temperature graph and the coffee machine

_{A tile can be 1 × 2 or 2 × 2 cells as well as one cell, double width or the whole page, and the card follows the room it gets: a player shows its album cover behind the track (every screen but the CYD), the heating shows its setpoint and the modes Home Assistant lists for it (the last key opens the card when they do not all fit), a blind shows its position, and its slats where there is room, an on/off tile stands centred with its switch. Every board works out the same card from its own glass. Each page has its own title and top bar, any page can be Home, and a page can stay out of the page dots and be opened from a tile, with a Back key to return. Rendered from the firmware's own LVGL code with a demo home.}

Weather, heating, cameras and your alarm

The 4-inch Guition with two weather tiles: a wide one with today and the next three days, and a big one listing the days under each other, each with a coloured bar from its low to its high on one scale Three thermostats: the heating with its setpoint between minus and plus and a bar with Heat and Auto, an airco on cool with heat, cool and more behind three dots, and a short bedroom tile with the stepper on one row A garden camera on a tile of two by two cells, its picture filling the whole card with the camera's name at the bottom, above the garden lights and the garden temperature

Four alarm panels as tiles: the house disarmed in grey, the garage armed away in green, the shed arming in orange and the studio armed home in green The alarm card: the shield in its circle, keys for Home, Away, Night and Vacation, and the Disarmed key The keypad to arm away: four dots for the code, the digits 1 to 0, a clear key and a check key

The 4.3-inch Waveshare: a wide weather tile with the coming days, the heating with its stepper, a front door camera filling a tile of two by two cells, and the dryer The select card of a washing machine on the 4.3-inch Waveshare: its programmes in two columns, Cotton eco checked, and page dots for the rest

_{The weather with the coming days, and on a bigger tile the whole week with a bar from each day's low to its high. A thermostat has its − / + and a bar with a key per mode; an airco shows heat and cool first and the rest behind "…". A live camera on a taller tile fills the card with its picture and its name, or shows the whole picture. Your alarm is a tile in Home Assistant's colours, with a key for every mode and Home Assistant's keypad when the panel asks for a code; someone coming in wakes every screen with the keypad to disarm. A select, such as a washing machine's programme, opens a list with a check at the one it is on. On every screen with the memory for it, every page is built ahead and kept, so the next one is there the moment you turn to it. Rendered from the firmware's own LVGL code with a demo home.}

On the screen

Guition 4-inch screen: an analog clock with the date, a temperature graph, the weather forecast, a lamp and presence Double-width tiles with direct control: the heating setpoint, a dimmer and the Sonos volume An energy graph, the robot vacuum, a coffee machine, a fan and a good-night script with pastel backgrounds

A full-page tile: one big amber light switch that fills the screen, so you push anywhere without looking A full-page heating tile: the room temperature big in the middle, the mode keys at the bottom

Weather card: current weather, the coming hours and the coming days with chance of rain Climate card: the target temperature between big minus and plus keys, the mode keys, and fan and swing choices Light control: color, color temperature and brightness

Vacuum card: docked and charging, start and dock, the cleaning mode vacuum, vac and mop or mop, suction and water Cover card for a venetian blind: its battery, the position slider with the blind hanging from the top, the tilt slider over slats, and open, stop and close A finger on the history graph: the top of the card shows the average of that hour and its time, the graph stays as it is

The effects page of a WLED lamp: the effect, colour palette, preset and playlist rows with what they are set to, and the speed and intensity sliders The effect picker: a drum with every effect Home Assistant lists, TV Simulator in the middle, and the check key at the top right that sends it The same effects page on the CYD: four rows and the two sliders in 320 by 240 pixels

The media card on the Guition: the album cover, the title, artist and album, a progress bar with the elapsed and total time, previous, pause and next keys and the volume slider A media player over the whole page: the cover at the left, the track, the bar and the keys beside it, the volume row along the bottom The media card in dark mode: the same cover and keys on a black page

_{Tap a tile to switch it, hold it for the full card. Keys and sliders right on the tile, pastel colors, a clock, the weather and history you can read with a finger. A lamp with modes (a WLED) gets an effects page with a drum picker, named and filled from what Home Assistant lists for it. The media card shows what plays with its album cover, fetched by ESP Screens like a camera picture, and a media tile can show that cover in the icon's place (how). Rendered from the firmware's own LVGL code with a demo home.}

Cameras as tiles on the Guition: the front door camera filling a tall tile with its name at the bottom, a porch camera showing its whole picture with black above and below, the porch light and Sam at home A camera tile tapped: the front door camera full screen, with the round back key and the camera's name at the top The same camera in an alert: its picture across the top of the card, with the card's rounded corners

_{Cameras are tiles too, not only part of an alert: any camera or snapshot in Home Assistant (a doorbell's last ring, for example) goes on a screen like any other tile. Tap it for the picture full screen, refreshed every four seconds, or let the tile itself show its live picture (Display → Live picture, every 5 to 30 s) over the whole tile, on every size up to a full page, filled or whole, with or without its name; an alert can carry the same picture. Every screen but the CYD, the Waveshare 3.5-inch and the Hosyond 4-inch, which have no memory for pictures (how it works).}

CYD 2.8-inch screen: the weather forecast, a kitchen timer, the coffee machine, a lamp and power usage as a large value Second CYD page: Sonos volume, presence, a scene and an energy graph The weather card on the CYD: current weather, the coming hours and the coming days

The CYD with heating mode keys, playback keys for the radio and a ceiling fan's speed slider The vacuum card on the CYD: state, battery and charging, clean and dock, the cleaning mode, suction and water The history card on the CYD: power over 24 hours with its highest and lowest moment, an axis in watts and clock times

The media card on the CYD: the player's icon where the cover would be, the title, artist and album, the bar with its times, the keys and the volume slider A media player over the whole CYD page: the icon at the left, the track and the keys beside it, the volume row along the bottom The media card on the CYD in dark mode

_{The same cards on the 2.8-inch CYD, 320 × 240. The CYD has no memory for pictures: its media card shows the player's icon in the cover's place.}

Dark mode on the Guition: the same home page with a black page, graphite cards and soft white text, the clock, the temperature graph, the weather, a lamp and presence Dark mode with direct control: the heating setpoint, the dimmer's slider and the Sonos volume keep their colours Dark mode with pastel backgrounds: the coffee machine and the good-night script keep their colour, deeper

_{Dark mode, for a screen beside the bed: the same pages, darker. It is a switch on the screen, in ESP Screens and in Home Assistant, so an automation can turn it on at bedtime.}

The settings page on the Guition, Screen: back to page 1 by itself and after how long, also on standby and swiping between pages, with the page buttons and the rotation on its second page The same Brightness page right after turning Dark mode on: a black page with graphite rows and soft white text

_{Settings on the screen itself: hold the top bar. The same brightness, Dark mode, standby, night hours, clock and rotation as in ESP Screens, and every one of them is an entity in Home Assistant.}

Managed from Home Assistant

ESP Screens in Home Assistant: your screens in the sidebar, the pages of the living room screen side by side with their top bar, and the entity library on the right

_{ESP Screens, a page in Home Assistant: your screens on the left, the pages of the chosen screen in the middle with the values Home Assistant reports right now, the library on the right.}

Choosing tiles: the pages of the screen side by side, next to the library with its search and filters Tile settings of the curtains in the drawer: double-width with open, stop and close on the tile, what a tap does, and the pastel background

_{Search your home, drop a tile on the preview, tap it for its name, width, control and color, and for what a tap does: open its card, switch it, or run any action Home Assistant has for it, such as the curtains to 50 %. Save, and the screen has it. ⌘K searches screens, entities and actions; Identify blinks a screen so you know which one it is.}

Add to the top bar, in the drawer: the time, an analog clock, the date, suggestions from your own home and any entity Settings in ESP Screens: New screen and Firmware & USB, the firmware updates, the Alerts cheatsheet, and the Claude skill

_{A top bar built from your own home, firmware updates over Wi-Fi (every night if you like), and a skill so Claude can rearrange your screens.}

The Screen settings tab in ESP Screens: Brightness with Dark mode and standby, Night with its hours and brightness, and Screen with back to page 1, swiping, the page buttons and the rotation

_{Screen settings apply at once, and a change made on the screen or by an automation shows up here too.}

Override YAML for the living room screen: a small file of its own, loaded after the shared package, here with the example that changes the display controller

_{Other hardware on your board? A CYD with the other display controller is a choice in New screen, and for anything else every screen has an Override YAML of its own, checked by ESPHome before a build and kept through every update.}

In your language

A Guition in German: Dienstag 15 Sept. beside the analog clock, Teilweise bewölkt with the days Di Mi Do Fr Sa, the table lamp at 75 % The same screen in French: mardi 15 sept., Éclaircies with the days ma me je ve sa, and Sam is Maison The same screen in Polish: wtorek 15 wrz, częściowe zachmurzenie with the days wt śr cz pt sb, and Sam is w domu

_{The same home in German, French and Polish. The screens follow your Home Assistant: its language, its words for a light or a robot, and how your country writes a date, a time and a number: 75 % in German and French, 75% in Polish and English.}

The screens, the editor and its messages speak English (US and UK), Nederlands, Deutsch, Français, Italiano, Español, Português and Polski. Nothing to set up: ESP Screens takes the language of your Home Assistant.

Language and region in ESP Screens: the screen language set to Home Assistant's language, the time format and the number format, each following the language

_{Settings → Language & region, when you want something else than Home Assistant's own.}

The editor follows the language of your Home Assistant profile, so two people in one house each read their own.
A screen carries one language, built into its firmware: change it and press Update on the screen (or let the nightly round do it). The clock (24 hours or 12 with AM/PM) and the number format change straight away, on every screen at once.
Words from Home Assistant stay Home Assistant's: what a door, an airco or a robot says on a tile and in its card is the word its own dashboard shows, in your language.

Most languages still need someone who speaks them to read the texts through, and a new language is one file. Translating ESP Screens walks through both; a language without a file falls back to English while it keeps your country's clock and numbers.

Alerts

An alert on the Guition with the front door camera's picture across the top: someone is at the door, with a Coming button The front door camera full screen on the Guition, with the round back key and the camera's name at the top

_{Someone at the door? One event in an automation wakes every screen and shows it. Add the doorbell camera and a Guition shows who is there; tap the picture, or a camera tile, for the camera full screen, refreshed every few seconds. Camera images.}

An alert on the Guition asking to open the garage, with a red Decline and a green Accept button side by side The Alerts cheatsheet in ESP Screens: the action name of every screen, ready to copy

_{Any alert, on one screen or all of them, in a pastel color of your choice, with one button or two to choose from, each in a color of its own and with its own action. How alerts work. An automation can also put a page in front, such as the page with the full-page player when the music starts: Open a page from an automation.}

Installing from Home Assistant

Which screen

Screen	Resolution	Display / touch
CYD ESP32-2432S028	320 × 240, 2 × 3 tiles	ILI9341 / resistive XPT2046
Guition ESP32-S3-4848S040, 4 inch	480 × 480, 2 × 3 tiles	ST7701S RGB / capacitive GT911
Waveshare ESP32-S3-Touch-LCD-4.3	800 × 480, 3 × 3 tiles	ST7262 RGB / capacitive GT911 (backlight always on: no standby, no night)
Waveshare ESP32-S3-Touch-LCD-7 (experimental)	800 × 480, 4 × 4 tiles	RGB / capacitive GT911; backlight always on, hardware acceptance pending (details)
Waveshare ESP32-S3-Touch-LCD-4B, 4 inch (experimental)	480 × 480, 2 × 3 tiles	ST7701S RGB / capacitive GT911; dimmable backlight, hardware acceptance pending (details)
Waveshare ESP32-S3-Touch-LCD-3.5 (new)	480 × 320, 2 × 2 tiles	ST7796 SPI / capacitive FT6336; dimmable backlight, no camera pictures (details)
Hosyond ESP32-32E, 4 inch (experimental)	480 × 320, 2 × 3 tiles	ST7796 SPI / resistive XPT2046; dimmable backlight, no camera pictures, hardware acceptance pending (details)
Guition JC8012P4A1, 10.1 inch	1280 × 800, 5 × 4 tiles	MIPI-DSI JD9365 / capacitive GSL3680, ESP32-P4 (new)
Guition JC1060P470 and JC1060P470 V2, 7 inch (experimental)	1024 × 600, 4 × 4 tiles	MIPI-DSI JD9165 / capacitive GT911, ESP32-P4; hardware acceptance pending (details)

Each screen links to its page on the Tessera website, with what owners report about it.

Got your screen working? Tell the next person. Whether a board is worth buying is something only owners can tell. On the website, My screen works records your exact board, its firmware version and whether the display, touch and connection work, one report per account and board. It takes a minute (you sign in with GitHub), and it is how an experimental board becomes one people can buy with confidence. Something not right? Report a problem there, or open an issue here.

Use these exact board variants: similar-looking product names can have different controllers or connectors. Wallbox relays are not controlled by default; a 4-inch Guition with relays can switch them through its Override YAML (docs/GUITION.md).

The one we use ourselves is the 4-inch Guition, and it has been good to us: bright, responsive touch, and it has been on the wall for months without a hiccup. We buy it here: Guition ESP32-S3-4848S040 on AliExpress. AliExpress being AliExpress, that link may go dead at some point. If it does, search for "ESP32-S3-4848S040" and check the listing says 480 x 480, ST7701S and a capacitive GT911 touch panel before you order.

ESP Screens builds with its own ESPHome 2026.9.0. The firmware also builds in your own ESPHome Device Builder with ESPHome 2026.6.2 or newer; the 10.1-inch Guition asks for 2026.8.0 or newer, because its touch panel is newer than that.

The 10.1-inch Guition is new in this release and has not yet been through our own acceptance test: its hardware was worked out and flashed on a real panel, and the screens' own software is the same on every board, but the two have not stood on one desk together. Tell us how it goes. It needs a panel with pre-v3 silicon (the boot log says chip revision: v1.3 or another below v3.0), which is what these panels have shipped with so far; rev3 silicon needs a firmware of its own.

Do I need ESPHome?

You don't need to install the separate ESPHome Device Builder app. ESP Screen Manager already includes the ESPHome CLI and can build firmware itself, install it via USB, put it on a screen plugged into your own computer from the browser, or give you the file, and later update it wirelessly over OTA.

You do need to pair the flashed screen via the ESPHome integration in HA. That pairing lives under Settings → Devices & services, not in the App store. Add the discovered device there. If it doesn't appear automatically, choose Add integration → ESPHome and enter the screen's IP address. If asked for a key, use the api.encryption.key from your own device YAML, and grant the device permission to perform Home Assistant actions.

Component	Needed?	What for?
ESP Screen Manager app	Yes, for this installation route	Installing firmware, managing tiles, and sending current data to the screen
ESPHome Device Builder app	No, optional	Alternative editor and firmware installer; the same CLI is already in ESP Screens
ESPHome integration in HA	Yes, pair every screen	The connection between Home Assistant and the physical screen

So a fresh installation without ESPHome Device Builder also works. If there's no ESPHome secrets.yaml yet, our wizard asks for Wi-Fi once and stores it locally. Existing Wi-Fi secrets are reused. API and OTA keys are generated per new screen and stay in that device's own profile.

Step by step

For Home Assistant Container (Docker) without the App store, follow Install with Docker.

For Home Assistant OS with Apps/Add-ons on aarch64 or amd64:

Open the App store and add this repository: https://github.com/MaxGramser/homeassistant_espscreen.
Install ESP Screen Manager, start the app, and open ESP Screens. ESPHome Device Builder is optional: the ESPHome CLI is already in this app.
Connect the screen with a USB data cable to the Home Assistant machine and choose New screen in the sidebar: your board, which way it hangs, a name, the USB port, and Install. If Wi-Fi is missing from the ESPHome secrets.yaml, the window asks for it once and ESP Screens only adds the missing lines. The profile with unique API and OTA keys goes into the ESPHome folder; the build and flash run in the same window (a first build takes a few minutes on a Raspberry Pi). Each screen gets its own profile. Is Home Assistant on a server or in a virtual machine, out of reach of the screen? Plug the screen into your own computer and choose This computer under Install via: ESP Screens builds the firmware and the page puts it on the screen, in Chrome or Edge with Home Assistant opened over https. Or choose Download and put it on the screen with ESPHome Web. After that, updates go over Wi-Fi as usual.
CYD: go through the calibration on the screen. Guition: uses GT911 without resistive calibration. Then pair the discovered ESPHome device in Settings → Devices & services using the API key the window shows after installation (copy button). Grant the device permission to perform Home Assistant actions.
Select the screen in ESP Screens, choose your tiles, and click Save & send. Then test the physical controls.

New screen in ESP Screens: choose the board, give it a name, pick the USB port and install Choosing tiles: the pages of the screen side by side, next to the library with its search and filters

_{New screen (step 3) and choosing your tiles (step 5).}

New firmware goes on over Wi-Fi with the Update button of a screen in ESP Screens, or by itself every night if you turn that on under Settings; Firmware & USB → Wi-Fi / OTA in the sidebar installs it by hand. For an existing screen, always use the existing profile; creating a new installation profile generates new keys.

The getting started guide on the website walks through every step in more detail.

Documentation on the Tessera website: getting started, pages and tiles, screen settings, cameras, Docker and troubleshooting.
Full reference: every card and setting, alerts and wake/sleep from an automation, the top bar, the settings page on the screen, and how updates keep your settings.
Guition hardware, mounting, and rotation · CYD calibration and USB diagnostics · Release history

Credits and license

The very first version started from Adrian Kuehlewind's ESPHome-touch-display-mount. Little of that code is left, but his repository has 3D-printable desk, under-desk, wall and flush mounts for the CYD.

The front door in the camera pictures is a photo by Virginia Marinova on Unsplash.

Tessera (formerly ESP Screens) is MIT licensed, see LICENSE.