TRMNL API
HomeBuy a Device
  • 👋Overview
  • How it Works
  • Private Plugins
    • Screen Templating
    • Screen Templating (Graphics)
    • Create a screen
  • Reusing Markup
  • DIY TRMNL (Advanced)
    • Introduction
    • BYOD
    • BYOD/S
    • BYOS
  • ImageMagick Guide
  • Plugin Marketplace
    • Introduction
    • Plugin Creation
    • Plugin Installation Flow
    • Plugin Management Flow
    • Plugin Screen Generation Flow
    • Plugin Uninstallation Flow
    • Going Live
  • Private API
    • Introduction
    • Fetch Screen Content
    • Fetch Plugin Content
    • Account API
  • Partners API
    • Introduction
    • Getting Started
    • Provisioning Devices
Powered by GitBook
On this page
  1. Plugin Marketplace

Plugin Screen Generation Flow

Creating image content to display on a user's device.

PreviousPlugin Management FlowNextPlugin Uninstallation Flow

Last updated 10 days ago

TRMNL generates a screen every X minutes, where X is the refresh frequency set by the user.

TRMNL generates screens by sending a POST request to the plugin_markup_url endpoint you specified during . The request body will include the user_uuid (that particular user's plugin connection UUID) and some metadata. The request header contains an authorization key with the user's plugin connection access_tokenas the Bearer token. Here's an example of our server request:

curl -XPOST 'https://your-server.com/your-markup-url' \
-H 'Authorization: Bearer xxx' \
-d 'user_uuid=xx&trmnl=<metadata-object>'

The trmnl object in this payload may or may not be useful for your plugin, but includes the user-defined instance name, device dimensions, user timezone, and so on. Here's an example, subject to change:

{
  "user": {
    "name": "Jim Bob",
    "first_name": "Jim",
    "last_name": "Bob",
    "locale": "en",
    "time_zone": "Eastern Time (US & Canada)",
    "time_zone_iana": "America/New_York",
    "utc_offset": -14400
  },
  "device": {
    "friendly_id": "XXXXXX",
    "percent_charged": 74.17,
    "wifi_strength": 50,
    "height": 480,
    "width": 800
  },
  "system": {
    "timestamp_utc": 1747596567
  },
  "plugin_settings": {
    "instance_name": "Upcoming Assignments"
  }
}

Your web server should respond with HTML inside root nodes named markup, markup_quadrant, and so on to satisfy each layout offered by TRMNL. This markup should include whatever values you want the user to see rendered on their screen.

TRMNL uses the markup in your server's response to generate an e-ink friendly image. If the user connecting your plugin created a "full screen" playlist item, TRMNL will leverage the HTML inside the markup node. If they connected your plugin as part of a left/right Mashup, TRMNL will look for HTML inside the markup_half_vertical node.

Here's an example of a valid server response:

{
  "markup": '<div class="view view--full"><div class="layout"><div class="columns"><div class="column"><div class="markdown gap--large"><span class="title">Daily Scripture</span><div class="content-element content content--center">Hello</div><span class="label label--underline mt-4">World</span></div></div></div></div><div>', "markup_half_horizontal": '<div class="view view--half_horizontal">Your content</div>', "markup_half_vertical": '<div class="view view--half_vertical">Your content</div>', "markup_quadrant": '<div class="view view--quadrant">Your content</div>'
}

Pro tip: use the markup editor to develop the frontend of your plugin. This in-browser text editor supports live refresh and automatically applies the correct styling and JavaScript helpers to your markup.

Note: in order for your plugin to be published in the TRMNL public marketplace, you must provide HTML for all available markup layouts. .

Private Plugin
View them here
Plugin Creation