Under the hood
The firmware's main building blocks and how a widget image travels to the screen.
You don't need any of this to use the device, but if you like knowing how things work, here is the machinery in broad strokes.
The building blocks
Display & UI engine
Owns the e-ink panel and the framebuffer. Draws widgets, menus, and popups, chooses between quiet partial refreshes and image-cleaning full refreshes, and runs the daily deep-clean that keeps ghosting away.
Network task
Runs while the device is awake: brings Wi-Fi up, checks in over TLS, downloads widget images, fetches Home Assistant and Self-Host images straight from your server, and handles firmware updates.
Power manager
Decides when to sleep and what may wake the device, tracks the battery through its voltage curve, reads the climate sensor, and pulls the emergency brake at critically low charge.
Storage
Your layout and settings (Wi-Fi credentials encrypted), plus an image cache of the most recent widget frames. The cache is what keeps the screen meaningful when a wake finds no network.
Widget images come from one of three sources, all polled the same way on each wake:
| Source | Mode | Where it runs |
|---|---|---|
| ZerryBit Cloud | App mode | Our servers render the widgets you configured in the app |
| Home Assistant add-on | HA widgets | Your Home Assistant machine, fetched directly on your network |
| Your own server | Self-Host | Anything that can answer an HTTP request with an image |
Home Assistant and Self-Host images never pass through the ZerryBit cloud.
How an image reaches the screen
On each wake the network task checks in, telling the server which layout and images it already has.
The server replies with only what changed: new widget images, a new layout, a firmware update, or simply "nothing new".
Fresh images are stored in the cache and handed to the display engine.
The display engine composes the grid, refreshes the changed areas of the panel, and the device sleeps.
Designed to fail gracefully
A few behaviours you'll only notice when something goes wrong:
- Offline wake: the cached widgets stay on screen, lightly dithered to show they're stale, with a small status box explaining the problem (the messages).
- One bad widget: that slot shows a placeholder; the rest of the screen updates normally.
- Interrupted update or crash: the device automatically falls back to its previous firmware and keeps working (more).