Home Assistant

ZerryBit Engine is a Home Assistant add-on that turns your Home Assistant entities into crisp 1-bit widgets for e-ink displays. It includes a built-in visual Widget Builder, and everything runs locally on your Home Assistant.

This guide installs the add-on, opens the builder, and gets your first widget onto a ZerryBit. It takes about 10 minutes.

Before you begin

You'll need:

• Home Assistant OS (HAOS), the standard Home Assistant install that supports add-ons.
• Administrator access to your Home Assistant instance.
• (Optional) The ZerryBit device. It's not required to install the add-on or design widgets, only to show them on real hardware. Device setup lives in the Quick Start guide.

Step 1 — Add the ZerryBit repository

1. In Home Assistant, go to Settings → Add-ons → Add-on Store.

2. Open the ⋮ menu (top-right) and choose Repositories.

3. Paste this URL, click Add, then Close:

   https://github.com/ZerryGit/zb-ha-app

Step 2 — Install the add-on

1. Back in the Add-on Store, find ZerryBit Engine. It appears under its own ZerryBit Add-ons heading — you may need to refresh the page for it to show up.
2. Click it, then click Install.

Step 3 — Start the add-on

On the add-on page:

1. (Recommended) Turn on Start on boot and Watchdog so the add-on comes back automatically after a reboot or crash.
2. Turn on Show in sidebar for quick access.
3. Click Start.
4. Open the Log tab and confirm it started without errors.

Step 4 — Open the panel

Click ZerryBit Engine in the Home Assistant sidebar. The Widget Builder opens right inside Home Assistant. There's no separate login, because it's authenticated through your Home Assistant session.

Step 5 — Build your first widget

From the panel:

1. Pick the Home Assistant entities you want to show.
2. Open the Builder and arrange text, shapes, and graphs on the canvas.
3. Save the widget.

You can create several widgets, each with its own layout and size. The builder's built-in guide covers sources, bindings, and graphs in depth.

Step 6 — Show it on your ZerryBit

How the widget reaches the device depends on which mode the ZerryBit runs in. These are two different paths — pick the one that matches your device:

With the app (normal mode): QR pairing

Each widget in the builder has its own QR code, opened from the button in the builder's top bar. To pair:

1. In the ZerryBit app, add a Home Assistant widget to your layout.
2. When the app asks, scan the widget's QR code from the builder. The code carries the add-on's address, the widget's ID, and its size, so there is nothing to type.
3. On the device's next refresh (or a button press) the widget appears.

Notes on this mode:

• No Deploy needed. Paired widgets always render from the widget's saved state, so edits in the builder show up on the device's next refresh by themselves.
• Several HA widgets can run on one device at the same time, each paired to its own builder widget.
• If the builder widget has a fullscreen companion, it pairs through the same QR code, and clicking the widget on the device opens it. Create the companion before pairing — the QR only carries the fullscreen ID once the companion exists, so if you add it later, re-scan the QR in the app. Build the companion at 720 × 480 (the size the device requests); other sizes are rejected with "Incorrect image size".
• Requires firmware 1.1 or later and a current version of the app. The ZerryBit must be on the same network as your Home Assistant.

With Self-Host mode: Deploy

In Self-Host mode the device doesn't use the app or pairing at all. It simply fetches one full-screen image from the add-on:

1. Design the dashboard that should fill the screen.

2. Click Deploy. Deploying makes this widget the one the add-on serves — the device always receives whatever was deployed last, so repeat this step after edits.

3. Point the device at the add-on's image endpoint (the builder's Settings tab shows the exact URL for your setup):

   http://<your-ha-ip>:8000/image.bin

The device-side configuration is covered in the Self-Host guide.

Configuration (optional)

The defaults work out of the box, so you can skip this. If you need to change something, open the add-on's Configuration tab — for example to move the image port if 8000 is already in use, set an automatic re-render interval, or restrict which external hosts the add-on may fetch from. See the full documentation for the complete list of options.

Troubleshooting

The add-on doesn't appear in the store. Refresh the Add-on Store page. If it's still missing, reload the page or restart Home Assistant, then look under the ZerryBit Add-ons heading.

The log shows "Dockerfile is missing". Open a terminal and run ha supervisor reload, then reinstall the add-on.

The panel won't open. Make sure the add-on is Started (Step 3), then check the Log tab for errors.

It won't install / says add-ons aren't supported. Add-ons require Home Assistant OS. See Before you begin.

A paired widget shows "Unavailable, try again soon" and never recovers. Check that image_port_mode is on-demand (see Configuration above), and that the widget still exists in the builder.

The device shows "Can't reach Home Assistant". The ZerryBit and Home Assistant must be on the same network, and the image port (default 8000) must be reachable — check firewalls or VLAN rules between them.

Next steps

• Home Assistant widget — the widget's page in the app: sizes, pairing, and settings.
• Self-Host — connect a device without the app.
• Full documentation — endpoints, payload format, and the configuration reference.
• Report an issue — found a bug? Good. We would be happy if you let us know.