Skip to content

Add Board, Colors, and Measured-Colors headers to display API requests#299

Open
oetiker wants to merge 2 commits intousetrmnl:mainfrom
oetiker:add-display-property-headers
Open

Add Board, Colors, and Measured-Colors headers to display API requests#299
oetiker wants to merge 2 commits intousetrmnl:mainfrom
oetiker:add-display-property-headers

Conversation

@oetiker
Copy link
Copy Markdown
Contributor

@oetiker oetiker commented Jan 30, 2026

Summary

  • Define per-board DEVICE_BOARD, DISPLAY_COLORS, and DISPLAY_MEASURED_COLORS macros in config.h for all supported hardware variants
  • Add displayColors, displayMeasuredColors, and board fields to ApiDisplayInputs
  • Send Colors, Board, and Measured-Colors HTTP headers in display API requests

Why

The backend currently has no way to know which board variant or display color palette a device supports. By sending these as headers, the API can return optimized images matched to the actual hardware — e.g. serving 4-color images to trmnl_og_4clr or 16-shade grayscale to trmnl_x.

Measured-Colors provides the actual sRGB values the e-ink panel produces (derived from Pimoroni's photographed saturated palette and community spectrophotometer data), enabling better server-side dithering and quantization compared to idealized palette values.

Test plan

  • Verify all three headers appear in API requests on physical hardware or via network capture
  • Confirm correct values for each board variant build

🤖 Generated with Claude Code

Send device board identifier and display color palette as HTTP headers
so the backend can tailor responses to specific hardware capabilities.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ryanckulp
Copy link
Copy Markdown
Contributor

thanks for this. i'm curious why it's needed however. currently our Device Model picker maps the hardware's capabilities (colors, selected palette, screen size, etc) to our render pipeline, which generates images according to those specs and then returns that graphic to the device.

https://trmnl.com/api/models
https://trmnl.com/api/palettes

i could see this being useful if (for example) a Kindle and a Nook were requesting content with the same API key, as it would allow the /api/display endpoint to shuffle around the available (already generated) Screens to return the one being requested. but that is not officially supported.

user sets their device's model + palette preferences, and all requests for content with that device's API key incorporate those specs.

@oetiker
Copy link
Copy Markdown
Contributor Author

oetiker commented Jan 31, 2026

@ryanckulp I am the author of byonk, I added support for all the new device types you added recently. In order to properly prepare the images my software needs to know the available colors. Instead of tracking the models, I thought it would be simpler if the device could tell the backend which colors its display supports.

actually come to think of it, if the firmware was not only to provide the pallette to use for the png but also what the color looks like that would make image preparation even simpler.

@Fr3dr1ckson
Copy link
Copy Markdown
Collaborator

Thank you for opening this PR. I understand its importance, but I’ll need some time before I can review it properly. I’ll share my feedback once I’ve had a chance to go through it.

Enables server-side dithering/quantization using real measured display
colors rather than idealized palette values.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@oetiker oetiker changed the title Add Board and Colors headers to display API requests Add Board, Colors, and Measured-Colors headers to display API requests Feb 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants