There is an e-ink screen in my bathroom. It runs on a battery, which means it spends almost all of its life asleep. Every so often it wakes up, says hello over Bluetooth, takes a new picture if someone has one ready, and goes back to sleep. I’ve worked with OpenDisplay to make this possible and seamless over time: queuing images for sleeping devices and always queuing deliveries in the Home Assistant integration, telling the display how long to sleep after each image, delta updates in the firmware and the Python client, delta updates from Home Assistant, and streaming decompression for faster uploads.
The important part is if someone has one ready. The screen doesn’t wait around. If the image isn’t there while it is awake, it sleeps on the old one, and the next chance is the next wake-up. Which, for a battery panel, might be hours away.
For a while, the image was never ready in time.
The Setup
The screens are OpenDisplay panels. Home Assistant talks to them, and a script pushes a full-screen image with opendisplay.drawcustom and a single dlimg element. HA fetches the PNG from a URL and sends it to the panel over BLE:
action: opendisplay.drawcustom
data:
payload:
- type: dlimg
url: http://<renderer>/page/screen-21-5?palette=6c
x: 0
y: 0
xsize: 800
ysize: 480
The bathroom panel is a Seeed reTerminal E1002, a 7.3" 800×480 six-colour screen. An automation watches the panel’s “last seen” sensor, and when it comes back from unavailable (the panel woke up), it runs the push script. The script gives up after a minute.
For the image itself, I wanted pixel-perfect control. Lovelace cards are built for screens you look at up close, not for a fixed 800×480 grid with six inks. So I made hass-vue, a custom HA app that compiles Vue pages into modules Home Assistant serves as custom cards. Each page is plain HTML and CSS, laid out exactly how I want it, and it still gets the frontend’s hass object with every entity state.
That gave me a page. To turn it into a PNG, I used Puppet, an add-on that runs headless Chromium, opens a Lovelace dashboard and screenshots it. Point it at the dashboard with my hass-vue card, and anything I can lay out in HTML ends up on paper.
On a desktop it is fine. On my Home Assistant box, an ODROID-M1, it was the problem.
Two Ways to Be Wrong
A cold start was the first problem. Chromium has to start, load the whole HA frontend, connect, and then render my card, and on the ODROID that took an unpredictable amount of time. Puppet screenshots after a fixed wait, not when the page is ready, so if it was too quick I got HA’s loading screen on my bathroom wall instead of a dashboard.
Puppet has a keep_browser_open option for exactly this, so I turned it on. Chromium, with the full HA frontend loaded, stays resident between renders, and a screenshot takes a second or two. That is fast enough for any wake window.
Then the bathroom screen went blank. Not broken, just a clean #fafafa field: HA’s background colour. The PNG was 2 KB.
Puppet keeps a single tab and only navigates when the requested path changes. Mine never changed, so every request screenshotted the same tab, and at some point that tab had died (probably when I rebuilt the card). The browser was fast, and it was faithfully serving me a picture of nothing. It would happen again after any card rebuild, frontend update or dropped websocket.
So I turned keep_browser_open off again, and measured what I had been hiding from. Every render now starts a fresh Chromium, loads the HA frontend, waits, and screenshots. On the ODROID, same page, back to back:
| Render | Gap before | Time | Result |
|---|---|---|---|
| 1 | 0 s | 70.5 s | Correct |
| 2 | 3 s | 110 s | Timed out |
| 3 | 10 s | 66.1 s | Correct |
| 4 | 35 s | 16.8 s | Error card |
| 5 | 0 s (browser still open) | 3.0 s | Correct |
| 6 | 60 s | 15.8 s | Blank grey |
| 7 | 5 min | 11.0 s | “Loading…” splash |
| 8 | 10 min | 18.7 s | “Loading…” splash |
The correct cold renders took over a minute. The fast ones were the old problem: the fixed wait ran out first, and they caught a splash screen or a card still loading.
That left me choosing between a browser that is quick and wrong, and a browser that is right but still loading long after the screen has gone back to sleep. Neither works for a panel that is only listening for a moment.
What I Actually Needed
I wrote down what mattered:
- Fast on a small box. The ODROID (and a Pi 4) is the target, not my desktop.
- Nothing running in between. The panels update every 15 minutes to 6 hours. Keeping a browser alive for that is waste.
- Pixel-perfect layout.
drawcustomcan draw text and shapes itself, but I wanted real HTML/CSS: icons, conditional elements, a proper layout. - No new widget framework. HTML and CSS, nothing to learn.
The realisation was that I didn’t need a browser. I needed HTML and CSS turned into pixels. Lovelace cards are web components, so rendering an existing dashboard without a browser is impossible. But if I own the page, I don’t need the dashboard.
Enter: hass-snapshotter
hass-snapshotter is a Home Assistant app that does exactly that. A page is a small JS file in /config/dashboard-pages/. It reads hass.states and returns markup:
export const size = [800, 480];
export default function render(hass, { html, mdi }) {
const temp = hass.states["sensor.outdoor_temperature"];
return html`
<style>.big { font-size: 64px; display: flex; align-items: center; background: #fff; }</style>
<div class="big">${mdi("mdi:thermometer", { size: 64 })} ${temp?.state ?? "--"}°</div>`;
}
A request to /page/<name>?palette=6c does this:
- Starts a short-lived child process.
- Fetches all states in one REST call, while loading the renderer and fonts.
- Calls the page’s
render(). - Hands the markup to Takumi, a Rust HTML/CSS renderer. Flexbox, grid, inline SVG; no JavaScript, no browser.
- Maps the pixels to the panel’s inks (or greys), and writes the PNG.
- Exits.
Between renders, only a ~20 MB Node process is left. There is no tab to go stale, because there is no tab. And because states are fetched at render time, there is no frontend subscribed to every entity change in the house.
The first version on the ODROID rendered the bathroom page in about 2 seconds. The push script went from 42 seconds through Puppet to 2.2 seconds. The Docker image went from 1.2 GB (while it still had a Chromium mode) to 169 MB.
Making It Faster Anyway
Two seconds fits the wake window comfortably. But the bathroom isn’t my only display. In the entrance hangs a 10.3" greyscale panel, essentially a reTerminal E1003: 1872×1404 pixels at 4 bits per pixel (16 greys), which is 1.3 MB per image. That is almost seven times the pixels of the bathroom panel, and anything that touched every pixel showed it.
So I added a debug page that logs every step with its time, and looked at where the time went.
The renderer itself was only 4-10% of a request. The biggest single step after startup was mapping pixels to the panel’s palette: 0.6-0.8 seconds on the ODROID for the colour palettes, even at 800×480. Each pixel snaps to the nearest ink, but anti-aliased edges need care, or text gets coloured fringes.
That loop moved to Rust, compiled to WebAssembly with SIMD (one .wasm file for both amd64 and arm64), including its own PNG writer. The palette step on the ODROID dropped to 10-30 ms at 800×480, and about 30 ms for the full 1872×1404 greyscale image, with byte-identical pixels.
With the palette out of the way, the debug page pointed at the next cost: starting over every time. Each render boots a fresh Node process, which takes 0.4-0.5 seconds before any of my code runs, and then spends about a second loading Takumi, fonts and HA’s config. That is most of a two-second render, and none of it is rendering.
So there is an opt-in renderer_keep_alive setting that keeps the process around for a while and reuses it. Only the HA states are fetched again. With it, the entrance page goes from ~2.3 seconds in a fresh process to ~0.4 in a kept one, saving almost 2 seconds per render. The price is 40-85 MB of memory while the process is kept, so the default is still a fresh process per render; keep-alive only pays off for screens that update more often than the timeout.
Where It Stands
The bathroom panel now gets a correct image every time it wakes. On the entrance panel, a full push takes ~20-30 seconds, and the render is ~0.4 of that.
That is the real win: the renderer is no longer the slow part, so the rest of the chain is worth looking at. Uploading those 1.3 MB over BLE takes 6-8 seconds even compressed, and the panel’s own refresh about 4. That is where I can work now, starting with delta updates that send only the parts of the image that changed.
hass-snapshotter is installable from my app repository, with example pages in the repo.