Designing screens

A “screen” is one image a device can display — a calendar view, a weather forecast, a lunch menu. Each device has a YAML config file (under CONFIG_DIR, normally configs/) that declares its data sources and the set of screens it can show, plus a schedule of when to show each one.

Getting a screen onto the panel goes through three stages:

  1. Config — the device’s YAML file says which Jinja template renders a given screen name, and what named data sources (a calendar feed, a weather API) are available to it. See Config format.

  2. Template → XML — the template (configs/**/*.xml.jinja) is a Jinja template whose output is an XML document: a small markup vocabulary of layout and content tags (<box>, <column>, <text>, <image>, …). Jinja handles anything dynamic (pulling data from a source, looping over calendar events, date formatting); the tags it emits describe the static layout. See Templates: Jinja → XML → image and Widget reference for the full tag reference.

  3. XML → image — the resulting XML tree is walked, each tag composited into a PIL.Image, and the final image is saved in the device’s raw e-paper format (or PNG, for previewing).

The fastest iteration loop while designing a screen is the todays_paper CLI (see Installing and running the server), which renders straight to a PNG without needing the server running:

uv run todays_paper dev -s family_calendar -o preview.png

To start from something that already works, see the Examples.