Office Display (TRMNL)
A TRMNL e-ink screen in the office that rotates live sales, inbox, fundraiser, show, review and alert screens rendered by the storefront.
Office Display (TRMNL)
A TRMNL 7.5" e-ink display (the Seeed "OG DIY Kit": XIAO ESP32-S3, 800×480 black-and-white panel) sits in the office and shows the business at a glance. It talks to the storefront directly using TRMNL's Bring Your Own Server protocol, so the data never passes through TRMNL's cloud and no TRMNL plugin is involved.
How it works
| Step | Endpoint | What happens |
|---|---|---|
| Once, after Wi-Fi setup | GET /api/trmnl/api/setup | An allow-listed device (by MAC) receives its access token. |
| Every wake | GET /api/trmnl/api/display | The server picks the next screen and returns a signed image URL and refresh_rate. |
| Right after | GET /api/trmnl/screens/:screen | The screen is rendered live to a 1-bit 800×480 PNG (next/og + sharp). |
| On device errors | POST /api/trmnl/api/log | Firmware errors are written to the function log. |
Code lives in apps/storefront/lib/trmnl/ (device.ts access, playlist.ts rotation,
data.ts loaders, dev.ts development sources and the brief, screens.tsx layouts, graphics.tsx
logo, star ratings and charts, logo.ts the pre-thresholded logo, render.tsx rasterising).
Screens
| Screen | Shows | Source |
|---|---|---|
today | Sales and orders since midnight Eastern, orders to ship, visitors, unread chats and emails, failed payments, latest orders with a sales-channel icon, and a chart of the last seven days' sales (today drawn as an outline while it fills) | Orders, operational queues, GA4, Gmail |
inbox | Unread mail in the connected Gmail inbox (mike@josemadridsalsa.com) and website chats waiting on a reply | Gmail API (live), Conversation/Message |
fundraising | Active fundraisers: revenue against goal, orders, days left | Fundraiser |
shows | Booked shows in the next 30 days | FeaturedEvent (synced from Google Calendar) |
reviews | 30-day average rating and count, reviews awaiting approval, the Google rating and newest Google review, latest product reviews | Review, SiteReview, Google Places (GOOGLE_PLACES_API_KEY, GOOGLE_PLACE_ID) |
social | Scheduled posts, posts and engagement (likes, comments, shares) over 7 days, the next two scheduled posts, the top posts and the newest failed publish. Direct messages need Meta's messaging approval and are not shown. | SocialMediaPost, SocialPostPublish |
traffic | Visitors today and over 7 days, add-to-carts, top traffic sources and countries | GA4 (the Analytics integration) |
shops | Per sales channel: live, pending and problem listings and the last sync; the newest listing errors | ShopListing |
dev | Production deploy state, CI on main (the CI result of the newest merged pull request into main, since CI runs on pull requests, not on main), open pull requests, unresolved Sentry errors in the last 24 hours, the last two deploys, the top two errors and the newest pull request | Vercel, GitHub and Sentry APIs (live) |
brief | A two-sentence summary of what shipped and up to three suggested next steps, written by Claude once per business day | dev data + Anthropic |
alerts | Up to three, most serious first: a failed latest production deploy, critical operator notifications nobody has read, website messages and contact-form submissions from the last two hours nobody has read, and unread mail Gmail marks important in Primary from the last hour. Each clears once read. | Vercel, Notification, Conversation, Gmail |
The display rotates one screen per wake (every 2 minutes by default, so a full cycle of ten
screens takes 20 minutes; lower TRMNL_REFRESH_SECONDS for a faster cycle). Contact form submissions arrive as website chats, so they show on
inbox. While a critical
alert is unread, every other wake shows the alerts screen; it clears as soon as any
operator reads that notification in the admin. Between 10 pm and 6 am Eastern the display
wakes every 30 minutes and shows today (or alerts).
Daily brief
The trmnl-brief cron (/api/cron/trmnl-brief, 10:30 UTC, before the office opens)
asks Claude for the day's brief and caches it for the business day, so the display never
waits on it. A failed generation is not cached: the next render of brief tries again, and
until then the screen reads "No brief yet today". Claude sees only deploy, pull request, CI
and error titles, never orders or customer records.
Setup
- Set
TRMNL_DEVICE_MACSandTRMNL_API_KEYin Vercel (see Environment variables). Generate the key withopenssl rand -hex 32. The MAC address is printed on the device's setup screen. - Set
TRMNL_SETUP_OPEN=trueand redeploy. A MAC address is not secret, so setup hands out the access token only while this is set. - Flash the TRMNL firmware onto the kit if it did not ship with it (TRMNL's web flasher).
- Hold the button to enter Wi-Fi setup, join the
TRMNLnetwork, choose your Wi-Fi, and under Custom server enterhttps://www.josemadridsalsa.com/api/trmnl. - The device registers, then shows the first screen within a refresh.
- Remove
TRMNL_SETUP_OPENand redeploy. The registered device keeps working; setup refuses everyone until you open it again. - Optional: set
TRMNL_VERCEL_TOKEN,TRMNL_GITHUB_TOKENandTRMNL_SENTRY_TOKENfor thedevandbriefscreens. - The display server at display.josemadridsalsa.com has no copies of those tokens: it reads the
finished development data and brief from
GET /api/trmnl/dev. SetTRMNL_DEV_FEED_SECRETto the same value on both Vercel projects; while it is unset here, the route refuses every call.
To preview a screen in the browser, sign in with the api_keys:manage permission (the one that
reads the owner's mailbox; admins and the developer by default) and open
/api/trmnl/screens/today (or any screen name above). Other staff cannot preview, since the
screens show the owner's email, revenue and analytics.
To revoke a device, change TRMNL_API_KEY: every device must then register again.
Changing it
- A new screen: add a loader in
data.ts, a layout inscreens.tsx, the case inrender.tsx, and the id toROTATIONinplaylist.ts. The render test fails if a worst-case screen overflows the panel or the 90 KB device limit. - Refreshes:
/api/displaysendsmaximum_compatibility: true, so every update is a full refresh (a ~3 s black-white flash). Partial refreshes left the previous screen showing through and made solid black speckled on the OG DIY Kit panel; keep it on. - Design rules: the panel is pure black and white; grey renders as black. Use size, borders and inverted bars for emphasis, and keep rows to one line.
- Icons and pictures: icons come from
lucide-react(already a dependency) and render through Satori as SVG; draw them atstrokeWidth2.5 so thin strokes survive the 1-bit threshold. Photos and colour artwork do not survive it: threshold an image ahead of time, aslogo.tsdoes for the round logo, and inline it so the function needs no file access.
How is this guide?
Last updated on