tesseraBy the moment it goes wrong. Many problems go away after an update: the app first, then each screen. Still stuck? Send a report from the screen's page, and nobody has to hunt for logs.
Something doesn't work: send a report
Every screen in Tessera has a button My screen doesn't work right, on its page under Screen settings and in the screen's menu. It collects, in about a minute, what is needed to find the cause, shows it to you, and sends it only when you say so.
- Open the screen in Tessera and click My screen doesn't work right.
- Write what happened: what you saw, what you did just before, how often it happens. Leave your e-mail address if we may ask you a question about it; without it the report is anonymous.
- Tick the fuller report if you can. It adds your pages with their entity names and the rest of Home Assistant's ESPHome log lines, which helps a lot with finding the cause.
- Click Collect and wait about a minute: the app also records the screen's live log for 45 seconds.
- Read what is in it. Every file can be opened on the page; nothing has left your Home Assistant yet. Download zip keeps a copy.
- Tick the consent box and click Send. You get a reference like
TR-7K3M9Q. - Quote the reference in a GitHub issue or on Discord; the button on the page opens an issue with it filled in.
What is in the report: the board and every version (firmware, app, Home Assistant, ESPHome), the plugins the screen runs, the screen's own YAML, the crash the screen kept from its last restart and a minute of its log, Home Assistant's log lines about this screen and its diagnostics of the device, the app's log and the last build. Passwords, keys, Wi-Fi names, IP and MAC addresses and the screen's name are taken out before you see it. Tessera keeps a report for 30 days and then deletes it; the privacy page says the rest.
A screen that crashes shows its last crash on the same page, with how often it happened this week. The app notices every restart of a screen and keeps what the screen remembers about it.
The button is off for a screen whose YAML isn't in Tessera's ESPHome folder, such as one you built with the ESPHome command line on your own computer; for that screen, attach its log to the issue by hand. The report is new in the dev version of Tessera and comes to everyone with the next release.
Installing the app
Tessera isn't in the app store
The standard store lists only Home Assistant's own repositories. One click adds Tessera's; Install the app shows how to do it by hand under the store's Repositories. Not in the list afterwards? Reload the page. Home Assistant Container has no store: use the Docker route.
Flashing
The USB port isn't in the list
The list shows the USB ports of the machine that runs Home Assistant. A cable into your laptop doesn't count, and a server or a virtual machine may have no port at all. Plug the screen into the Home Assistant machine with a cable that carries data, or choose From this computer and install from your browser. Or Download the file and use ESPHome Web.
From this computer: no port, or it won't connect
Only Chrome and Edge on a computer can reach USB, and only with Tessera opened over https, for example your Home Assistant Cloud address. Over plain http the option says so and stays off. Some computers need a driver for the board's USB chip: CP210x, CH340 or CH9102. Most CYDs have a CH340. The board doesn't answer? Hold its BOOT button while you choose the port, until the install starts. Unplugging and plugging in again can help. "The screen's port is in use by another program or tab" means a serial monitor or ESPHome Web still has it: close that first.
Wrong board on the cable
Tessera checks the chip before it writes: "The board on the cable has an ESP32-S3 chip, but this screen's firmware is for an ESP32" means you picked another board than the one plugged in. Nothing was written. Plug in the right screen, or choose its board.
The build fails
The first build downloads fonts and code from the internet and needs memory. Open the log with Show details and read the first real error. Check the internet connection and the free disk space; on a Raspberry Pi with little memory, close heavy apps and click Retry. The build itself takes 20 minutes or more on a Pi the first time; that is not a failure.
Several boards on USB
Connect one at a time for the first install. With several, Tessera asks which port is this screen's.
Wi-Fi and Home Assistant
The screen doesn't join Wi-Fi
The screens use 2.4 GHz only. The name and password come from the two Wi-Fi lines in ESPHome's secrets.yaml; a typo there reaches every new screen. A guest network often keeps devices away from Home Assistant: use the main network. Tessera's install window waits three minutes and then offers Change Wi-Fi and install again.
Most boards open a hotspot called "Screen name Setup" about 90 seconds after losing the network; the screen shows its name and password. Join it with your phone and pick the right Wi-Fi. The CYD and the Hosyond have no hotspot: install them again over USB from Firmware & USB; the name, keys and calibration stay.
A new screen doesn't show up in Home Assistant
Tessera adds a screen to Home Assistant by itself once the screen is on your Wi-Fi, when the screen's YAML is in the ESPHome folder Tessera reads. Its card under Screens in Tessera's sidebar says Installed. Waiting for it to join your Wi-Fi... and then On your Wi-Fi. Getting it ready.... Still waiting for Wi-Fi? See The screen doesn't join Wi-Fi.
When Tessera can't add it, the card says "Tessera can't add it to Home Assistant by itself" and offers Open Devices & services and Copy API key. Usually Home Assistant can't reach the screen: it is on another network segment or VLAN that mDNS doesn't cross, or a guest network or client isolation on a mesh system keeps it away. Put the screen on the same network as Home Assistant, or add it to Home Assistant by hand. A screen built outside Tessera's ESPHome folder, such as with the ESPHome command line on your own computer, is always added by hand.
The screen stays on "Connecting to Home Assistant"
Home Assistant hasn't connected to the screen yet. A new screen gets there once Tessera has added it; if its card in Tessera says it can't, see the entry above.
A screen that worked before and stays here after a power cut probably got a new address from your router, while Home Assistant keeps trying the old one. Open the screen's settings page, This screen, and note the Address; tap Restart, and Home Assistant usually finds it within a minute or two. Otherwise choose Reconfigure on the ESPHome entry and type the new address. A fixed address in your router prevents it.
Copy API key copies nothing
Browsers block the clipboard over plain http. Tessera shows the key selected in a box: press Ctrl+C, or Command+C on a Mac. The key is also in the screen's YAML under api:, encryption:, key:. Don't use the OTA password.
"Waiting for Tessera" or "Choose your tiles"
The screen is in Home Assistant. Choose your tiles: the screen has no tiles yet. Open Tessera, pick tiles for it and click Save & send; they appear at once. Waiting for Tessera: the app hasn't sent anything yet; check that it runs, and that the screen's Tile settings entity isn't disabled in Home Assistant. Firmware before 0.45.0 says Waiting for Tessera in both cases.
The screen isn't in Tessera's list
The list is Home Assistant's own list of ESPHome devices with Tessera firmware. Check that the ESPHome integration shows the screen as connected and that its Tile settings entity is enabled. A screen built by hand from the shared files needs the board's own package file, which sets its board and device name.
"HA not connected" or "Tessera not active"
The screen lost Home Assistant, or heard nothing from the app for about five minutes. The last tiles stay on the glass, taps are blocked. Check that Home Assistant and the app run; after an app restart a screen recovers within a minute.
A removed screen comes back
A screen that is still powered announces itself again. Unplug or erase it, then Remove screen in Tessera, which removes it from Home Assistant too. Deleting only the YAML leaves it in the list.
The picture
The picture is garbled, noisy or wrongly coloured on a CYD
CYDs that look alike have different display chips: most an ILI9341, some an ST7789V, a few an ILI9342. Install again with New screen and the other Display controller; for an ILI9342 choose the board "CYD ESP32-2432S028 ILI9342". Still wrong? Override YAML with DISPLAY_DATA_RATE: 20MHz for noise, or DISPLAY_INVERT_COLORS: "true" for inverted colours; see Flash a screen yourself. Don't copy rotation lines from forum posts: choose its orientation with Grid beside the pages in the editor.
The picture is upside down
Change Rotation in the screen's settings: half a turn on every screen, a quarter on a square one. It applies at once.
A Guition 7 inch shows white with a band of noise
It is the other revision. Look for "V2" on the rear label, or a date code of 2622 or later on the panel board behind the back cover, and install with the other choice. A wrong choice does no harm.
A Guition 7 inch won't start after a power cut
Older firmware started the panel too fast. Install once over USB with firmware 0.3.4 or newer.
A Guition 10.1 inch doesn't start, or its picture is washed out
The three revisions need their own firmware. A V3 on the first firmware never gets past the bootloader; a V2 shows a washed-out picture with a coloured line. Pick the model that matches the label and install over USB, since a screen that doesn't start can't update over Wi-Fi.
A Guition 4 inch looks off below 90 % brightness
Firmware 0.3.5 fixed the dimming. Update the screen; an old backlight override can go.
A Waveshare 4.3, 5 or LCD-7 never dims
By design. Their backlight is on or off only, and switching it on from dark makes the board restart, so these models have no standby, night mode or screensaver. Owners of the 7 inch can add a wire for dimming; the Waveshare 7 inch page explains.
An experimental board shows only the page buttons
The app and the firmware are out of step. Update the app, then the screen, put a few tiles on it and Save & send. Still empty? Open an issue with a photo, both versions and the boot log.
The screen restarts over and over on "Loading tiles…"
A bug in firmware 0.3.6 on boards that keep pages in extra memory. Update to the current app and firmware. Too fast to update over Wi-Fi? Install once over USB from Firmware & USB.
Touch
Taps land in the wrong place on a CYD or Hosyond
Their touch panel is pressure-sensitive and must be measured per panel. Open the screen's settings page, This screen → Calibrate touch (also in Tessera's Screen settings tab and as a button on the device in Home Assistant). Tap each of the five crosshairs three times, holding each tap briefly. Every other screen needs no calibration.
Taps are off after turning the screen
An old rotation line in Override YAML fights the built-in one. Remove the old YAML override and rebuild once to remove it from the firmware. Then choose Landscape or Portrait under Grid in the editor. On a resistive panel, recalibrate if touches are still misplaced.
A tap switches twice, or switches back
An automation in Home Assistant reacts to the same device. Try the same action from Home Assistant's dashboard and check your automations.
A Guition 10.1 inch shows tiles but ignores my finger
Firmware before 0.6.2 never got touches from the V3's chip; update. Still dead, with "Read RAM: 0, 0, 0, 0" in the log? The touch chip is stuck: unplug the board for a few seconds, battery included if it has one.
Swiping doesn't change the page
Swipe between pages is off by default; see Navigation. On most screens the swipe must start at the left or right edge; on the CYD and the Hosyond it is a quick swipe anywhere.
Tiles
Tiles show values, but tapping does nothing
A screen needs Home Assistant's permission to perform actions. Tessera turns on Allow the device to perform Home Assistant actions for every new screen, and turns it back on as soon as Home Assistant reports that it ignored a tap. When it can't, the screen's page in Tessera says "Home Assistant doesn't let this screen perform actions yet, so a tap on a tile does nothing", with an Allow actions button. In Home Assistant itself the switch is under Settings → Devices & services → ESPHome, the screen, Configure.
A tile says Unavailable
The entity is missing or unavailable in Home Assistant. A renamed entity counts as missing: choose it again in Tessera.
A thermostat or vacuum offers fewer options than expected
A tile offers only what the integration reports to Home Assistant. Try it in Home Assistant itself first.
A page can't be reached
With Page buttons off, only swiping and Go to page tiles change the page. Tessera warns which pages become unreachable when you turn the bar off.
The screen keeps going back to the first page
Back to Home does that after two minutes without a touch, by default. See Navigation.
The editor refuses a camera or map tile
The CYD, the Hosyond and the Waveshare 3.5 inch have no memory for pictures. Every other screen shows them.
"Preparing pages 3/8"
Normal. A screen with extra memory builds every page once after a new layout, in a second or two.
Music and pictures
The media card shows an icon instead of the cover
The CYD has no memory for pictures. It keeps the player, its speakers and the favourites, without the cover and the library.
Camera pictures or covers don't load on Docker
The screens fetch pictures from port 8098 of the Docker host. Let them in through the firewall, and set SCREEN_CAMERA_URL when the screens reach the host under another address; see Home Assistant Container.
The camera isn't video
The screens show still pictures: full screen every four seconds, on a tile every 5 to 30 seconds. ESPHome has no video decoder.
Updates
A new feature doesn't show on the screen
Update the app first, then the screen with its Update button. No button? Firmware & USB, choose the screen's profile, Wi-Fi / OTA, Build & install. Reload open Tessera tabs afterwards.
"Configuration problem. Update add-on."
The screen's firmware is newer than the app. Update the app.
"Configuration problem. Check screen and add-on versions."
The app and the screen don't understand each other's layout. Update the app, then the screen.
A CYD or Hosyond update failed with "Build or install failed"
An app older than 0.4.56 builds firmware that no longer fits those boards. Update the app, then try again. The screen keeps running its old firmware.
A CYD or Hosyond went dark for a minute during an update
Normal, once: a small firmware in between moves the screen to its new partition table. It comes back with its settings. Dark for an hour? Install it over USB from Firmware & USB. Screens with 4 MB of flash has the whole story.
"The OTA partition on the ESP is too small"
ESPHome Device Builder says this for a CYD or Hosyond you flash yourself. Press Update in Tessera once, or install once over USB; see Screens with 4 MB of flash.
Tiles gone after removing and reinstalling the app
Reinstalling isn't updating, and can wipe the app's data. Restore the Home Assistant backup that includes the app.
Docker
The sidebar panel shows 502: Bad Gateway
Home Assistant runs on a bridge network, as on Docker Desktop, and can't reach Tessera on its own address. Follow Home Assistant on a bridge network.
No "Home Assistant connected" in the log
Check that ha_token holds only the token, and that HA_API ends in /api and reaches Home Assistant from inside the container.
The page asks to be opened through Home Assistant
You opened port 8099 from another address. Use the sidebar panel or an SSH tunnel; the page has no login of its own.
The container says unhealthy
Old versions had a health check that could never pass. Update the app.