Release early, release often!
Hello,
I’ve just started with Home Assistant. I’m still in the evaluation phase,
figuring out what I actually want to do with it. One thing I wanted early on
was a “glanceable” dashboard I could check before leaving the house. Checking
if a window is still open? What does the weather look like? Is waste collection
tomorrow or is the cellar flooded?
The solutions I found were not satisfying. They either ran a headless browser
to take screenshots or were somehow duct-taped together. Home Assistant already
uses Pillow Pillow (PIL Fork) 12.2.0 documentation , so all the primitives
are right there, no external tools are needed.
So I started writing a new integration.
The hardware story
I got a TRMNL device recently. They are a nice little e-ink display designed
exactly for this kind of glanceable information. But after I set it up I
remembered that I have old Kindle e-readers lying around that I replaced with
newer models and never found a use for. My old Kindle Paperwhite 2 has a
better display than the TRMNL OG - 758×1024 at 16 grayscale levels versus
800×480 black-and-white.
After some research I found that you can repurpose a jailbroken Kindle as an
always-on display. There is an online screensaver around, but outdated and
not really energy efficient. I started a new project
kndl-online-screensaver.
A modern replacement for the old online screensaver projects, also covered
with tests.
It took me a while to figure out why the online screensaver corrupts the FAT
partition, but that is another anecdote ;-).
So now I had two different devices that both needed images pushed or
pulled from Home Assistant. That shaped the integration.
What it does
The integration renders your dashboard layout to a PNG image using Pillow
directly in Home Assistant - no Chromium, no ImageMagick, no Node.js. It
exposes the image via an HA image entity and an unauthenticated HTTP endpoint
that devices can poll on their own schedule.
For TRMNL devices, HA can push the rendered image via webhook after each
render. For Kindles (and any other device that can fetch a URL), you point the
device at the HTTP endpoint and let it pull on its own schedule, using ETag
headers to skip the download and e-ink refresh when nothing has changed.
The WYSIWYG Lovelace card lets you edit the layout on a canvas preview that
matches your device’s exact pixel dimensions. You can drag, resize, and
configure widgets and immediately see what the rendered output will look like.
Clicking Show rendered image fetches the actual Pillow-rendered PNG for a
pixel-exact comparison.
Current state
The configuration flow is working well and I have images being pushed to my
TRMNL and pulled by my Kindle Paperwhite 2. It is ready for an initial alpha
release. The widget set will need a lot of improvements but maybe someone is
interested in helping.
Expect bugs, this is an early release.
The project is at: GitHub - cryptomilk/hass-eink-dashboard: WIP · GitHub
Features
- Multiple e-ink displays - create a separate dashboard for each device
with its own layout, resolution, and refresh interval - Device presets - built-in profiles for Kindle 4/5, Paperwhite 1–4,
Oasis 2/3, TRMNL OG/X/RGB, or enter a custom resolution - Portrait and landscape - rotation is handled automatically based on the
device preset and chosen orientation - WYSIWYG Lovelace editor - drag, resize, and configure widgets on a
canvas preview that matches your device’s exact pixel dimensions - Pull and push delivery - devices can fetch the image on their own
schedule (Kindle) or have HA push it via webhook (TRMNL) - E-ink optimization - optional post-processing pipeline: autocontrast,
sharpness, contrast adjustment, and grayscale quantization (2/4/16/256
levels with Floyd-Steinberg dithering) - Jinja2 templates - text widgets support Home Assistant templates
(e.g.{{ now().strftime('%H:%M') }}) - ETag support - conditional HTTP responses so devices skip the download
and e-ink refresh when the image has not changed - Webhook rate limiting - push targets are throttled to one push per 5
minutes with a 5 MB size cap
How to contribute
This is alpha software - expect rough edges!
- Please create detailed bug reports when something doesn’t work
- Be friendly in communication
- Help to improve the documentation
- Create Pull Requests improving the code or widget designs
Cheers!
