paperboard

Designed e-ink dashboards from Home Assistant data, served straight to TRMNL devices.

paperboard draws dense, readable dashboards for 1-bit and greyscale e-ink panels, using your Home Assistant data, inside Home Assistant:

• No browser, no add-on, no cloud. It works on Home Assistant OS, Supervised and Container installs alike.
• It is the device's server. TRMNL devices (OG, X, and DIY/BYOD panels running TRMNL firmware) talk to Home Assistant directly.
• Other clients: ESPHome displays, Kindles and other image clients can fetch the same image from a URL.

Why

No sensor is ever required. A home without solar panels, a battery, a CO₂ sensor or an electricity price still gets a clean screen:

• Missing data: a missing value shows "—", or that section collapses and its neighbours take the space.
• Gone entities: a Repairs notice tells you which entity is gone.
• Enforced: every widget and every bundled layout is tested against a house with zero entities, and against garbage data, on every change.

Layouts

Seven layouts are bundled. Each is a YAML file, and you can write your own.

Timeline (tidslinjen) — now, expected solar and price on one 24-hour axis, six days, energy	Newspaper (tidningen) — a newspaper page with a written headline; warning days invert
Bento (bento) — tiles with a black hero	Board (tavlan) — the morning board: hour by hour with price
TRMNL (trmnl) — TRMNL's own visual language	Almanac (almanackan) — calendar first: the week with weather and events
Energy (energi) — energy flow, price and expected solar stacked on one axis	The same Timeline in a house with no entities at all

Language: British English by default, and Swedish. The screen follows Home Assistant's language (Settings → System → General); a language Paperboard does not have yet falls back to English, and a layout can pin one with lang:. The name in brackets is the layout's id, used in files and settings; it is the same in every language. Want your language? See Add a language.

Install

1. In HACS, search for Paperboard and download it. It needs Home Assistant 2026.3 or newer.

   

   If it does not show up yet, add https://github.com/the-louie/paperboard as a custom repository (HACS → ⋮ → Custom repositories, category Integration) and download it from there.

2. Restart Home Assistant, then go to Settings → Devices & services → Add integration → Paperboard.

   • Give the base URL your devices use to reach Home Assistant.
   • Use the LAN address (e.g. http://192.168.1.10:8123), not the cloud URL.
   • Set it on Docker installs with a bridge network: without it, image links for other clients use the container's own address (details).

Set up a screen

The full guide to every setting is in docs/configuration.md. The short version:

1. Roles: on the Paperboard entry, open Configure → Sensors and data (roles) and pick what each role means in your home. Leave anything you don't have empty.

   Role	Typical entity
   Weather (forecast)	weather.home
   Outdoor / second temperature, feels-like, humidity, rain today	weather-station sensors
   Electricity price	Nord Pool (core or HACS), ENTSO-e
   Expected solar energy today	"Energy production today" from Forecast.Solar, Open-Meteo Solar Forecast or another integration that feeds the Energy dashboard (Solcast via its attributes): the hourly curve is read from the same integration
   Solar / grid / house / battery power, house energy today, battery charge	inverter and meter sensors. Tick "Grid meter reports export as positive" for Huawei-style meters.
   Rooms, calendars	any number of temperature sensors and calendars

2. Screen: Add screen. Pick a name and a layout. Leave Panel on Automatic: it follows the model the device reports, from 58 TRMNL models, Kindles and BYOD panels.

3. Pair: press the screen's Pair device button. You then have 5 minutes.

   • On the device's setup portal, choose Custom server and enter the base URL.
   • Pairing only works from your local network, never through the cloud URL or through a proxy on behalf of a caller outside it.
   • After a factory reset, press Pair device again: a MAC address proves nothing, so a panel is never re-paired without the window. Home Assistant tells you under Repairs when a known panel asks to pair again.

Each screen gets:

• an image entity, which previews in a picture-entity card;
• battery, Wi-Fi signal, firmware and last check-in sensors;
• a Missed check-in problem sensor, which turns on after 3 missed polls.

The device redraws only when the picture changed, which saves flashes and battery.

Your own layouts and schedules

• Layouts: put *.yaml files in /config/paperboard/. They are picked up within 30 s; a broken file shows a Repairs issue and the last working version keeps rendering.
  • Format: docs/design/layout-schema.md. It has a CSS-like grid with named areas, 18 widget types, rules, boxes and black tiles.
• Schedules: a schedule file switches layouts by time of day and condition. For example, Tavlan from 07:00 to 08:00 on school days, and a quiet night layout that wakes the device once an hour. See Schedules and refresh policy.
• The device button: a short press shows the next layout for 30 minutes; a double click goes back to the schedule. See the device button.
• Other clients: ESPHome, Kindle, TRMNL Alias and LaraPaper: docs/clients.md.

How it works

HA states + services (forecast, prices, solar, calendars)
  → snapshot (event loop) → SVG layout (executor) → resvg → exact 1/2/4-bit PNG
  → /api/display (TRMNL firmware) · image URL (others) · image entity (HA)

Design documents are in docs/design/:

• device API, including its security review;
• rendering;
• data sources;
• testing.

Rendering budget: the densest layout renders in ~80 ms, with frames of 5–8 kB.

FAQ

• "I don't have a CO₂ sensor / solar panels / a battery."
  • Nothing breaks: those sections are left out.
  • A role bound to an entity that later disappears raises a Repairs issue.
• "The screen shows GAMMAL BILD / STALE IMAGE."
  • The last render failed, and the last good image is being shown.
  • See the screen's Render error sensor and the integration's diagnostics.
• "It renders tiny on my TRMNL X."
  • Layouts scale to the panel. Some widget spacing does not scale yet (tracked).

Contributing

Contributions are welcome: bug reports, layouts, widgets, translations, documentation and code.

• CONTRIBUTING.md: development setup, tests, golden images, and what a pull request needs.
• Open an issue for bugs and ideas.
• Security problems: report privately, see SECURITY.md.
• Everyone taking part follows the Code of Conduct.

All documentation: docs/. Changes per version: CHANGELOG.md.

How this was built

Paperboard was developed with help from an AI coding assistant (Anthropic's Claude), under the maintainer's direction. Every change is reviewed by the maintainer and checked by the test suite: pixel-exact golden images, the empty-house tests, and CI on x86-64 and aarch64.

Credits

• Device API, PNG/BMP encoders and battery curve: ported from the author's own TRMNL BYOS server (MIT).
• Prior art: cryptomilk/hass-eink-dashboard showed that resvg inside Home Assistant works.
• Fonts: TRMNL12/16/21 (© Heavyweight Digital Type Foundry) and Inter (© The Inter Project Authors), both SIL OFL 1.1.
• Icons: Material Design Icons (Pictogrammers, Apache-2.0).

Licence

Apache-2.0.