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.
I lead Tessera's development and maintenance, with contributions from the community. Your support gives me more time to build, review and test improvements. A small monthly contribution or a one-time coffee is welcome.
or buy me a coffee once
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, or more on the boards with the memory for them, as many per page as the glass holds: lights, climate, humidifiers, blinds and curtains, the vacuum, media, the weather,
history graphs, the energy of your house live, clocks and timers, your alarm with its keypad, and your cameras and a map of where everyone is 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. Tessera 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 · The manual · Pages · Screen settings · Troubleshooting · What's new
The manual is on the Tessera website: from the quick start to every tile, every screen setting, every supported screen and troubleshooting, with search. Anyone with a GitHub account can improve a page with Edit this page. This README is the overview; the files under docs/ are the reference for contributors.
Requests, questions and bugs
GitHub Issues are for bugs only. Feature requests, improvements and new board requests posted on GitHub will not be reviewed. Submit and discuss them on the Tessera wishlist. Questions and general discussions are handled in Community, not GitHub Discussions.
- Features and improvements: search the wishlist. Upvote an existing wish or add your own.
- New ESP boards and displays: use the New boards category. Include the exact model, a product link and whether you can test it. Votes show how many people would use it and help set priorities. They do not guarantee support or a release date.
- Questions and examples: post in Community, where the earlier GitHub conversations and replies have moved.
- Bugs: use GitHub Issues for something that is broken in existing functionality. Include reproducible steps and version information.
- Code changes: open a pull request and link the bug or website wish it implements.
Sign in on the website with GitHub to vote, post or reply. Search before posting so the conversation and votes stay together.
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
Print a stand for your screen
A screen looks best on a stand that was made for it. These are free to download and print on MakerWorld, each with a
ready Bambu Studio print profile and no supports needed.
- Home Assistant tablet base for the Seeed reTerminal D1001 (8 inch): a
round base with a dock, tilted 30 degrees. Two printed rails hold the screen by its VESA holes, with four M4 x 8 mm
screws. The ESP32-P4 inside plays your cameras live and talks to Assist.
- Wedge stand for the Guition 4" ESP32-S3-4848S040: a calm wedge that
holds the square screen at a comfortable angle. Take the small back plate off the screen first (two tiny screws on
its back), then push it in.
- Upright stand for the same Guition 4": the first Tessera stand, with a
small heart in its speaker grille. Push the screen in, no screws.
Printed one? A like or a Boost on MakerWorld costs you nothing and helps keep Tessera free, and a photo of your
make with your own layout is always welcome.
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-five 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. Each board starts on the grid that suits its glass, and the editor changes the columns and rows
beside the pages, without a new build: the 10.1-inch Guition holds up to forty tiles on a page with eight rows.
Your house's energy, live
Meters for every sensor
Taller tiles, richer cards
Weather, heating, cameras, your alarm and your locks
Music, from the speaker to the library
Where everyone is
A clock beside your bed
On the screen
Managed from Home Assistant
In your language
The screens, the editor and its messages speak English (US and UK), Nederlands, Deutsch, Français, Italiano,
Español, Português, Polski and Magyar. Nothing to set up: Tessera takes the language of your Home Assistant.
- 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 Tessera walks through both; a language without a file falls back to English
while it keeps your country's clock and numbers.
Alerts
Installing from Home Assistant
Which screen
| Screen | Resolution | Display / touch |
|---|
| CYD ESP32-2432S028 | 320 × 240, 2 × 3 tiles | ILI9341 / resistive XPT2046 |
| CYD ESP32-2432S028 with ILI9342 (experimental) | 320 × 240, 2 × 3 tiles | ILI9342 / resistive XPT2046; hardware acceptance pending |
| 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-5 (new) | 800 × 480, 3 × 3 tiles | RGB / capacitive GT911, the 4.3-inch's board with 5-inch glass (backlight always on: no standby, no night; details) |
| Guition JC8048W550C_I, 5 inch (experimental) | 800 × 480, 3 × 3 tiles | ST7262 RGB / capacitive GT911; dimmable backlight, the capacitive variant only (details) |
| 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-7B (experimental) | 1024 × 600, 4 × 4 tiles | RGB / capacitive GT911; dimmable backlight, 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.
Tessera 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.
Tessera 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.
Nothing to set up in Home Assistant. As soon as a flashed screen is on your Wi-Fi, Tessera adds it
to Home Assistant's ESPHome integration with the screen's own key and allows it to perform Home Assistant
actions, which a tile needs to control anything.
| Component | Needed? | What for? |
|---|
| Tessera 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 Tessera |
| ESPHome integration in HA | Yes, Tessera adds every screen to it by itself | 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:
-
Tessera is not in the standard App store, so add its repository first. One click does it:
Or add it by hand: open the App store, choose Repositories in the menu in the top right, and add
https://github.com/MaxGramser/homeassistant_espscreen.
-
Install Tessera Screen Manager from the store, start the app, and open Tessera in the sidebar.
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 click + beside Screens in the sidebar. New screen takes three steps: Screen (pick your board),
Set up (name it and choose which way it hangs) and Install (choose USB on Home Assistant and click
Install). If Wi-Fi is missing from the ESPHome secrets.yaml, Set up
asks for it once and Tessera 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 From this computer in the Install step:
Tessera builds the firmware and the page puts it on the screen, in Chrome or Edge with
Home Assistant opened over https. Or choose Download the file 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. The screen joins your Wi-Fi and shows up in Tessera by itself.
-
Select the screen in Tessera, choose your tiles, and click
Save & send. Then test the physical controls.
New firmware goes on over Wi-Fi with the Update button of a screen in Tessera, 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 manual on the website walks through every step in more detail.
More
- The manual on the Tessera website: installing,
pages, 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
ESP Screens was inspired by Adrian Kuehlewind's
ESPHome-touch-display-mount, and its
very first version started from his code. The project has gone its own way since, but his repository
is still the place to go to give a CYD a proper home. It has beautiful 3D-printable desk, under-desk,
wall and flush mounts.
Not to be confused with Tesserae (tesserae.ink), a separate open-source project that
makes calm dashboards for e-ink panels in Home Assistant. Same word, different screens: Tessera is for colour LCD
touch screens, Tesserae for e-ink. A question meant for the other project is gladly passed on.
The front door in the camera pictures is a photo by
Virginia Marinova on Unsplash.
Tessera (formerly ESP Screens) is licensed under the GNU Affero General Public License v3.0, see LICENSE
and NOTICE. Releases up to and including 0.4.38 were MIT licensed and stay so.
