tesserae-opendisplay

A bridge that pushes Tesserae-rendered dashboards to OpenDisplay BLE e-paper tags.

Tesserae renders your dashboards on the server; OpenDisplay tags are driven over Bluetooth LE. This bridge sits between them: it polls Tesserae's frame endpoint for each tag over the network, and when a frame changes it pushes the image to the tag over BLE with the py-opendisplay SDK, which dithers for whatever panel the tag advertises. One bridge drives many tags, and you can run several bridges (one per BLE cluster) against the same Tesserae server.

Requirements

• A running Tesserae server reachable over the network.
• A machine near your tags with a Bluetooth LE adapter (a Pi, a mini PC, an HA box) to run the bridge on.
• Bluetooth (BlueZ) running on that machine. On Linux the bridge talks to the adapter through BlueZ, so it needs to be installed and running:

  sudo apt install bluez
  sudo systemctl enable --now bluetooth
  sudo rfkill unblock bluetooth
  bluetoothctl list      # should show a controller
  

  A container or VM has no Bluetooth unless a real adapter is passed through, so run the bridge on the host (or a host with a USB dongle).
• Python 3.11+.

Install

pip install tesserae-opendisplay

Configure in a browser

The quickest way to set up: run the config web UI, then point a browser at the host on port 8080.

tesserae-opendisplay web            # then open http://<bridge-host>:8080/

It lets you point the bridge at your Tesserae server, scan for OpenDisplay tags over Bluetooth (reading each panel size), add them, and remove them, writing config.toml for you. Prefer the command line? Skip to Find your tags.

Find your tags

tesserae-opendisplay discover

This scans for tags in range and prints a [[tags]] stub for each, including the panel size it reads off the tag, so you can paste it straight into your config.

Configure

Create config.toml:

server_url = "http://tesserae.local:8000"
poll_interval_s = 300        # fallback cadence; the server can override per tag

[[tags]]
device_id = "kitchen"         # the Tesserae device id (you choose it)
ble = "AA:BB:CC:DD:EE:FF"      # tag BLE MAC (or a device name to auto-scan)
width = 800                   # the tag's panel, from `discover`
height = 480
pairing_code = "AB12CD"       # optional: a Tesserae pairing code to register this tag once
# token = "..."               # or a device token you already hold
# rotate = 0                  # optional 0 / 90 / 180 / 270
# fit = "contain"             # optional contain / cover / stretch / crop
# dither = "burkes"           # optional dither mode
# refresh = "full"            # optional full / partial

[[tags]]
device_id = "hall"
ble = "OpenDisplay-A1"
width = 400
height = 300
pairing_code = "AB12CD"

Generate a pairing code in Tesserae under Settings → Devices. The bridge registers each tag with that code on first run, then caches the token in config.toml.state.json so later runs skip registration. After a tag is registered it shows up in Tesserae like any other device: bind a dashboard, add it to a rotation, schedule it.

Run

tesserae-opendisplay --config config.toml

Each cycle the bridge asks Tesserae for every tag's frame (sending the last ETag, so unchanged frames cost nothing), and only pushes over BLE when a frame actually changed. BLE uploads happen one tag at a time (Bluetooth is serial), so a change to many tags refreshes them in sequence. Run it under systemd / an init supervisor for an always-on setup, or --once for a single pass (a cron-driven refresh).

Scaling to many tags

• One bridge cycles its tags sequentially. Fine for a wall that updates on an e-paper cadence.
• Multiple bridges, each on its own BLE adapter near its cluster of tags, all point at the same server_url. That's how you cover more tags or more rooms: shard the tags across bridges by location.

How it fits together

Tesserae server  ──HTTP /frame──►  bridge (this)  ──BLE upload──►  OpenDisplay tag
   renders                          polls + pushes                  displays

Tesserae renders each tag's dashboard as a full-colour PNG (the opendisplay device kind uses the pi_png renderer); the bridge hands that PNG to the OpenDisplay SDK, which does the panel-specific dithering. Nothing about the tag's geometry lives on the server beyond the panel size you register it with.

License

AGPL-3.0-or-later.