Help — getting started

[dmellok]

First time setting up Tesserae? Ask here. No question too small.

Things worth including in your post:

• Which install path you took (Docker, install.sh, manual)
• The panel you're aiming at
• Where you got stuck (a log snippet beats a vague "doesn't work")

For known-broken bugs, please open a bug report instead.

[RealGandy]

Hi

installed via Docker (using compose) - server up and running fine.
Have an old Kindle now running the TRMNL plugin and successfully registered and pulling dashboards

What I'm struggling with is getting the clock and calendar widgets to register the correct time.
When I see the preview via Web GUI, both clock and calendar widgets show the correct 'current' time, but when the image is rendered and sent to device, the time is one hour wrong. For example it is currently 13:45 and the clock widget is rendered as 12:45.
I have calendar linked to a google calendar and the 'current' time on the calendar widgets also shows as 12:45 and all events are shown an hour early, for exampe an event at 13:30 is shown at 12:30.

I've played with the timezone settings, both 'system' and 'Europe/London' but with the same results. We are currently in daylight savings, which is UTC+1. I would expect the system to pick up daylight savings changes automatically?

Any advice?
Cheers

[dmellok]

Thanks for the detailed report. You've found a real bug, not a config issue on your end.

What's happening: the frame pushed to your Kindle is painted by a headless Chromium inside the Tesserae container, which was reading UTC from the container instead of your "Europe/London" setting. The preview path doesn't have this problem because it runs in your own browser.

The fix is in v0.44.10. Once that lands in the HA add-on / Docker image, your Timezone setting will be respected all the way through, including the BST→GMT switch in October.

Really appreciate the level of detail. "Preview correct, render wrong" pointed straight at it.

[tommerty]

Hi, I'm likely "skill issued" to be honest, but I set up tesserae via the home assistant addon/app and have a trmnl x but the docs are super not clear on how to actually set it up, or maybe they are and I'm jus "skill issued" as said before. Would it be possible to get a very basic step by step this is how you add the trmnl and setup a basic layout/view/render?

[dmellok]

Glad it works. Happy to help if you hit anything else!

[tommerty]

Sadly got some ongoing issues, not sure if maybe an issue is better rather than the discussion? But the TLDR is my trmnl is still showing the placeholder, and when I created a simple dashboard (showing weather) and attempt to push it nothing happens. Looking in the events I can see it failed. Looking in the logs I see this:

RuntimeError: transport not connected; can't publish to 'tesserae/trmnl_34be20/frame/trmnl'
2026-06-16 11:27:52,033 INFO waitress, Client disconnected while serving /events/stream
2026-06-16 11:28:40,292 INFO app.ha_options, HA add-on: applied broker config (4 field(s))
2026-06-16 11:28:40,292 INFO app.secret_box, SecretBox using key derived from session secret; set TESSERAE_SECRET_KEY for a stable, operator-owned key
2026-06-16 11:28:40,346 INFO app.plugin_loader, Loaded plugin calendar_core (kind=data)
2026-06-16 11:28:40,362 INFO app.plugin_loader, Loaded plugin calendar_day (kind=widget)
2026-06-16 11:28:40,380 INFO app.plugin_loader, Loaded plugin calendar_month (kind=widget)
2026-06-16 11:28:40,396 INFO app.plugin_loader, Loaded plugin calendar_week (kind=widget)
2026-06-16 11:28:40,412 INFO app.plugin_loader, Loaded plugin clock_analog (kind=widget)
2026-06-16 11:28:40,428 INFO app.plugin_loader, Loaded plugin clock_sunrise_sunset (kind=widget)
2026-06-16 11:28:40,444 INFO app.plugin_loader, Loaded plugin clock_word (kind=widget)
2026-06-16 11:28:40,460 INFO app.plugin_loader, Loaded plugin countdown_date (kind=widget)
2026-06-16 11:28:40,477 INFO app.plugin_loader, Loaded plugin fonts_core (kind=font)
2026-06-16 11:28:40,494 INFO app.plugin_loader, Loaded plugin ha_battery (kind=widget)
2026-06-16 11:28:40,511 INFO app.plugin_loader, Loaded plugin ha_camera (kind=widget)
2026-06-16 11:28:40,529 INFO app.plugin_loader, Loaded plugin ha_climate (kind=widget)
2026-06-16 11:28:40,547 INFO app.plugin_loader, Loaded plugin ha_core (kind=data)
2026-06-16 11:28:40,565 INFO app.plugin_loader, Loaded plugin ha_energy (kind=widget)
2026-06-16 11:28:40,583 INFO app.plugin_loader, Loaded plugin ha_entities (kind=widget)
2026-06-16 11:28:40,602 INFO app.plugin_loader, Loaded plugin ha_history (kind=widget)
2026-06-16 11:28:40,619 INFO app.plugin_loader, Loaded plugin ha_lights (kind=widget)
2026-06-16 11:28:40,637 INFO app.plugin_loader, Loaded plugin ha_locks (kind=widget)
2026-06-16 11:28:40,654 INFO app.plugin_loader, Loaded plugin ha_media (kind=widget)
2026-06-16 11:28:40,673 INFO app.plugin_loader, Loaded plugin ha_sensor (kind=widget)
2026-06-16 11:28:40,690 INFO app.plugin_loader, Loaded plugin ha_todo (kind=widget)
2026-06-16 11:28:40,708 INFO app.plugin_loader, Loaded plugin ha_zones (kind=widget)
2026-06-16 11:28:40,725 INFO app.plugin_loader, Loaded plugin news_hacker_news (kind=widget)
2026-06-16 11:28:40,746 INFO app.plugin_loader, Loaded plugin news_reddit (kind=widget)
2026-06-16 11:28:40,763 INFO app.plugin_loader, Loaded plugin news_rss (kind=widget)
2026-06-16 11:28:40,780 INFO app.plugin_loader, Loaded plugin news_wikipedia_otd (kind=widget)
2026-06-16 11:28:40,797 INFO app.plugin_loader, Loaded plugin picture_apod (kind=widget)
2026-06-16 11:28:40,822 INFO app.plugin_loader, Loaded plugin picture_gallery (kind=widget)
2026-06-16 11:28:40,844 INFO app.plugin_loader, Loaded plugin todo (kind=widget)
2026-06-16 11:28:40,859 INFO app.plugin_loader, Loaded plugin weather_core (kind=data)
2026-06-16 11:28:40,879 INFO app.plugin_loader, Loaded plugin weather_forecast (kind=widget)
2026-06-16 11:28:40,898 INFO app.plugin_loader, Loaded plugin weather_hourly (kind=widget)
2026-06-16 11:28:40,916 INFO app.plugin_loader, Loaded plugin weather_now (kind=widget)
2026-06-16 11:28:40,933 INFO app.plugin_loader, Loaded plugin weather_now_scenic (kind=widget)
2026-06-16 11:28:40,950 INFO app.plugin_loader, Loaded plugin webpage (kind=widget)
2026-06-16 11:28:40,965 INFO app.plugin_loader, Loaded plugin year_progress (kind=widget)
2026-06-16 11:28:40,983 INFO app.plugin_loader, Loaded plugin calendar_schedule (kind=widget)
2026-06-16 11:28:40,993 INFO app.renderer_loader, Loaded renderer esp32_bin (device=esp32, topic=tesserae/esp32/frame/bin)
2026-06-16 11:28:41,003 INFO app.renderer_loader, Loaded renderer esp32_bw_bin (device=esp32, topic=tesserae/esp32/frame/bin)
2026-06-16 11:28:41,013 INFO app.renderer_loader, Loaded renderer pi_bin (device=pi_bin, topic=tesserae/pi_bin/frame/bin)
2026-06-16 11:28:41,022 INFO app.renderer_loader, Loaded renderer pi_png (device=pi_png, topic=tesserae/pi_png/frame/png)
2026-06-16 11:28:41,031 INFO app.renderer_loader, Loaded renderer trmnl_png (device=trmnl, topic=tesserae/trmnl/frame/trmnl)
2026-06-16 11:28:41,043 INFO app.device_loader, Loaded device esp32_bw_client (renderers=['esp32_bw_bin'], status=tesserae/esp32/status)
2026-06-16 11:28:41,055 INFO app.device_loader, Loaded device esp32_client (renderers=['esp32_bin'], status=tesserae/esp32/status)
2026-06-16 11:28:41,066 INFO app.device_loader, Loaded device pi_bin_client (renderers=['pi_bin'], status=tesserae/pi_bin/status)
2026-06-16 11:28:41,077 INFO app.device_loader, Loaded device pi_png_client (renderers=['pi_png'], status=tesserae/pi_png/status)
2026-06-16 11:28:41,090 INFO app.device_loader, Loaded device trmnl_client (renderers=['trmnl_png'], status=http-polled)
2026-06-16 11:28:41,090 INFO app.device_loader, Loaded device instance trmnl_34be20 (kind=trmnl_client, status=None)
2026-06-16 11:28:44,929 ERROR app.transport_wiring, MQTT connect failed (host=core-mosquitto); leaving transport offline
Traceback (most recent call last):
  File "/app/app/transport_wiring.py", line 505, in _rebuild_transport
    transport.connect()
  File "/app/app/transport.py", line 144, in connect
    self._client.connect(self._config.host, self._config.port, self._config.keepalive)
  File "/usr/local/lib/python3.12/dist-packages/paho/mqtt/client.py", line 1435, in connect
    return self.reconnect()
           ^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/dist-packages/paho/mqtt/client.py", line 1598, in reconnect
    self._sock = self._create_socket()
                 ^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/dist-packages/paho/mqtt/client.py", line 4609, in _create_socket
    sock = self._create_socket_connection()
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/dist-packages/paho/mqtt/client.py", line 4640, in _create_socket_connection
    return socket.create_connection(addr, timeout=self._connect_timeout, source_address=source)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/app/capabilities.py", line 251, in _hooked_create_connection
    return _original_create_connection(address, *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/socket.py", line 828, in create_connection
    for res in getaddrinfo(host, port, 0, SOCK_STREAM):
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/socket.py", line 963, in getaddrinfo
    for res in _socket.getaddrinfo(host, port, family, type, proto, flags):
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
socket.gaierror: [Errno -5] No address associated with hostname
2026-06-16 11:28:44,933 INFO app.push, pruned 6 orphaned render artifact(s)
2026-06-16 11:28:44,976 INFO app.network, Resolved host IP via HA Supervisor: 192.168.0.100 (iface=end0)
2026-06-16 11:28:45,080 INFO app.main, Starting waitress on http://0.0.0.0:8765/  (--dev for Flask dev server)
2026-06-16 11:28:45,081 INFO waitress, Serving on http://0.0.0.0:8765
2026-06-16 11:30:35,829 INFO app.renderer, render phases (s): attempt=1 goto=0.12 compose=0.09 images=0.01 fonts=0.01 screenshot=0.06 (url=http://127.0.0.1:8765/compose/0d108e0fd081?for_push=1&w=800&h=480)
2026-06-16 11:30:35,971 ERROR app.push, renderer trmnl_png__trmnl_34be20 failed
Traceback (most recent call last):
  File "/app/app/push.py", line 759, in _fan_out
    result = self._publish_artifact(
             ^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/app/push.py", line 1010, in _publish_artifact
    self._transport.publish(
  File "/app/app/transport.py", line 159, in publish
    raise RuntimeError(f"transport not connected; can't publish to {topic!r}")
RuntimeError: transport not connected; can't publish to 'tesserae/trmnl_34be20/frame/trmnl'

[dmellok]

Good point, Open an issue if you have a moment, I'll debug this output in the meantime.

** Edit - hang tight I have a fix coming in around 10 minutes. if you run into anything else, open an issue! :)

[dmellok]

0.49.1 is live: https://github.com/dmellok/tesserae/releases/tag/v0.49.1

The fix lifts the MQTT requirement for TRMNL: the push pipeline now skips the broker publish for devices whose manifest declares no status topic, and writes the frame straight to the latest-renders map that /api/display reads from. Once the HA add-on store picks up the new tag, update and you should be unblocked with no other config changes.

Optional sidenote on Mosquitto: if you do install HA's Mosquitto add-on later, Tesserae's HA MQTT auto-discovery lights up too. Every Tesserae device shows up as native HA entities you can put on a dashboard or trigger automations from. That's the real upside of having Mosquitto around, not a Tesserae plumbing requirement.

Thanks for sticking with it.

[tommerty]

Update did the trick and all working nicely! Had to manually adjust the resolution, but I'm seeing info on my screen, thank you!

[RealGandy]

Any plans to implement an equivalent to the TRMNL /mirror endpoint?

Use case: Would allow a non-supported device to present a dashboard image via HTTP(s).

I have an old iPad running iOS12 which has no TRMNL client, but could run Safari hitting this endpoint that delivers a dashboard via HTTP(s) with a refresh to get it to auto pull the latest?

[dmellok]

Shipped in the latest release. We already had /preview/<device_id>.png for the HA generic camera use case, which serves the latest composition PNG behind a stable URL. The new /mirror/<device_id> is the auto-refreshing HTML wrapper around it for your exact use case: point Safari at a single URL, walk away.

For your iPad:

http://<your-tesserae-host>:8765/mirror/<your_device_id>

Defaults to the refresh cadence you've set on the device (sleep_interval_s), override with ?refresh=60 etc. If the iPad is mounted sideways relative to the panel, ?rotate=90 (or 180 / 270) applies a CSS rotation client-side so it lands the right way up.

Settings → Devices now also has a Mirror button on each device card so you don't need to remember the URL.

Once your install picks up the latest version (Docker users pull latest or restart; git installs run the in-app updater), it's there waiting. Let me know if iOS 12 throws any surprises.

(BTW, opened up GitHub Sponsors on the repo recently if anyone ever wants to throw a couple of dollars at hosting / Codespaces / docs costs, no pressure obviously.)

[bablokb]

I am using a LAN only Baikal-server for my calendars and todo-lists. Authentication is via digest. Is this kind of setup supported?

[dmellok]

Yes, this works as of the next release (on edge now). On the Calendar Feeds page (Plugins → Calendar Core) each feed has an Authentication option; set it to Digest with your Baikal username and password. Because Tesserae fetches feeds server-side, a LAN-only Baikal is fine as long as the Tesserae host can reach it.

There is also a Discover box: paste your CalDAV calendar-home URL (the folder that holds your calendars, e.g. https://baikal.lan/dav.php/calendars/you/) with the same credentials and it lists every calendar and todo list it finds, so you can add each in one click instead of building the ?export URLs by hand.

For the todo lists specifically: calendars render through the existing calendar widgets, and there is a new CalDAV Todo widget (in the marketplace) that shows a task list'''s VTODO items as a read-only checklist.

[bablokb]

Awesome! I will test it next week. It seems I can retire some of my own solutions with a single Tesserae server.