Generic CircuitPython client + client protocol spec

[dmellok]

TL;DR

@bablokb is scoping a generic CircuitPython client for Tesserae, one codebase covering 400+ boards via CircuitPython's existing display libraries. To support that work (and any future third-party clients), there's now a full client protocol spec covering REST, MQTT, pairing, frame formats, and the steady-state loop:

📖 Client protocol spec (lives in the docs site, version-controlled, tracks main)

Why this thread

The spec is the authoritative reference, but conversations about ambiguities, edge cases, design tradeoffs, and progress updates happen here so others doing related work can follow along.

Status

• ✅ Spec drafted and shipped to the docs site
• ⏳ Bernhard scoping the CircuitPython client architecture
• ⏳ Reference: device-pico-bin (RP2350 C++ firmware, same wake / fetch / paint / sleep shape) is the closest in-tree analog for studying the existing pattern
• 🤔 Open question: PNG vs the packed .bin format on CircuitPython. The spec recommends PNG given how adafruit_imageload and the standard display library palette mapping already handle it; .bin is faster + lower memory but means porting the 4-bpp nibble unpacker.

How to contribute

• If you're building a client (any platform): read the spec, flag anything ambiguous or missing here. The spec gets firmed up based on what trips real implementations.
• If you're following the CircuitPython work: comment to subscribe, or post related questions.
• If you've built clients for adjacent projects (TRMNL, inky-dash, MagTag dashboards): comparison notes welcome, what's load-bearing in those protocols that might be load-bearing here.

Spec source lives at docs/dev/client-protocol.md; PRs welcome (especially "I tried this and it doesn't quite work" feedback I can encode into the doc).

[bablokb]

Well written spec, only one comment (maybe more pops up when I start implementing):

the client should be able to request the current local time, providing a timezone name in the request. The server might run in UTC, so servertime alone is not sufficient. Converting to local time is nothing trivial for a memory constrained client, especially with DST on/off rules.

[dmellok]

Quick question before I land the shape on this: what would the client actually use local time for?

Where I can see it earning its keep is smart-sync scheduling, so you can wake at local-time-aligned moments (top of the hour, 7am local, sunrise-ish) without needing an NTP sync. Anything else you'd lean on it for?

Painted frames already have the rendered date baked in by the server, so display doesn't need it. Logging timestamps can be stamped server-side when /log POSTs land. So the real value is probably in client-side scheduling decisions; happy to ship whatever shape genuinely helps once I know how you'd use it.

[bablokb]

Where I can see it earning its keep is smart-sync scheduling, so you can wake at local-time-aligned moments (top of the hour, 7am local, sunrise-ish) without needing an NTP sync. Anything else you'd lean on it for?

That is exactly the use case. I currently update the external RTC (if available) from a simple time-service running on a local Pi. This step can be skipped if the server provides the time. It is even more efficient, since only a single request is necessary.

[dmellok]

Shipped in v0.64.9, server-side change + spec update both live. The four new fields land on every POST /api/v1/device//status response:

{
  "status": 200,
  "config": { "sleep_interval_s": 300 },
  "next_poll_s": 300,
  "server_time": 1687000060.123,

  "local_time": "2026-06-22T19:00:00+02:00",
  "tz": "Europe/Berlin",
  "tz_offset_seconds": 7200,
  "dst_active": true
}

local_time is what you set the RTC to. tz_offset_seconds + dst_active let the RTC keep ticking in local terms between heartbeats so you don't need a round-trip for every paint. No NTP service needed on your network.

One refinement on the original shape: your client doesn't actually need to send anything to use this. The server already knows its own timezone (set during onboarding) and resolves into it automatically; your firmware just reads the four fields off the response. If the device is in a different zone from the server (mobile, geo-aware, multi-zone install) you can optionally send tz: "Europe/Berlin" in the heartbeat body to override, but the common case doesn't.

Live spec: https://dmellok.github.io/tesserae/dev/client-protocol/

[dmellok]

I've just built this in but let me know if any changes are required.

[bablokb]

That looks good, thanks. I must say I cannot keep up with your pace but I really appreciate your work!

Another suggestion, this time regarding /api/v1/device/<id>/log: would it make sense to change the msg field to a list? A typical use case would be to log tracebacks. Not really necessary, because the client could just concatenate all traceback lines into a single string. But I am thinking of memory constraint clients. E.g. Python already has the traceback in a list and it would save some RAM not having to concatenate the information again.

[dmellok]

Haha. I'm in between jobs right now and have too much free time.

I'll take a look at implementing this tomorrow :)

[dmellok]

@bablokb
Shipping in v0.64.20: msg on POST /api/v1/device//log now accepts a list of strings, joined server-side with \n. Your client can pass traceback.format_exception() output straight through, no on-device join. Also bumped the cap from 512 B to 4 KB. Both changes are backwards compatible; thanks for the suggestion.

[bablokb]

Thanks. Just a note: traceback.format_exception() returns a list of strings already terminated by a \n.

[dmellok]

Just pushed v0.64.21 with the double-newline fix; yell if any of the wire shapes don't translate cleanly.

[bablokb]

Repo created: https://github.com/bablokb/tessarae-device-circuitpython

Nothing usable in there yet, but just to sum up: the client will support all boards that are supported by CircuitPython and are powerful enougth to drive a display. A second prerequisite is a suitable hardware abstraction layer file for the hardware.

Important to note: one of the supported hardware types is "GENERIC_LINUX_PC". This works with CircuitPython+Blinka+PyGame. This hardware type is ideal for prototyping, since it can emulate any screen-size thus allowing development and testing without the slow deployment steps needed for real hardware. And in the end you could even run a dashboard on your multi-feet large desktop monitor.

My implementation plan now is to first create a library for the REST API and then implement a suitable data-provider and ui-provider for the application.

[dmellok]

Amazing work! I'm excited to see how this comes along!

[bablokb]

I seem to have problems with the name of this project. I renamed my repo now:

https://github.com/bablokb/tesserae-device-circuitpython

I also created the repo for the library

https://github.com/bablokb/circuitpython-tesserae

(no content yet)

[dmellok]

Haha I completely missed the typo in your first post.
I really appreciate you taking the time to work on this project.

[dmellok]

@bablokb, quick question: would you be comfortable if I added a
Planned row to the supported-hardware section on https://tesserae.ink
noting that a generic CircuitPython client is in development?

I was thinking something neutral like "CircuitPython · client in
progress · target: REST" with a link back to this thread. You're
doing the work; the wording is yours to set. Happy to drop or soften
any specific claim (board count, ETA) if it overstates.

No urgency. Just want your call before I touch the site.

[bablokb]

Yes, go ahead. This is a very nice website.

I am currently finishing another project (basically a roundup on the docs). After that, I will concentrate on the CircuitPython client.