Private Plugins | TRMNL Help Center

TRMNL customers with the Developer add-on may use our API to quickly and easily make their own personal dashboards.

Step 1 - Upgrade your Account

While logged into your TRMNL dashboard, visit the Account tab and pay a one-time fee to unlock the Developer edition of TRMNL.

If you purchased your device via Kickstarter and chose the "Developer edition" package, this will automatically be applied on your account and no additional action is required.

Step 2 - Stub a Private Plugin

From the Plugins tab, search for "Private Plugin" to begin configuring your personal creation.

Let's start with the Name. This is for your eyes only, and will help you keep track of all private plugins from both the Playlists interface and the previous screen, as you can build as many private plugins as you'd like.

Next is Visibility. We suggest starting with "Personal" for now, as we're still working on letting developers make their work public in the directory for all customers. If you choose "Public," this will allow TRMNL devices to render your* content, not their own content.

Your plugin's Strategy determines how TRMNL will receive data that gets rendered on a device screen. If you choose Webhook, you'll need to set up your own web service that sends a POST request to TRMNL with a payload of content. If you choose Polling, TRMNL will fetch this content on your behalf.

If you chose Polling as your strategy, TRMNL needs to know where to fetch this data. Provide a URL in the following Polling URL input box, and feel free to add additional params for authorization.

Markup is the last and most important configuration. This is the frontend HTML template for your data to be merged into. Use our template docs for help designing the perfect screen to showcase your content.

Only markup inside the <body> tag is required, as TRMNL will inject this into a fixed page layout with our native Plugin CSS and fonts.

TRMNL supports the popular Liquid templating engine to handle merge variables, which means you can leverage {{ variable }} syntax in your Markup to merge in data when you want to create a new screen.

Step 3 - Test your Plugin

In our template docs we provide a live example to help you build a private plugin with a webhook or polling strategy and see it on your device within seconds.

Here's a quick summary:

in the Strategy configuration, select the Polling option from the dropdown
input https://usetrmnl.com/custom_plugin_example_data.json as the Polling URL
copy/paste the sample markup (see below) into the Markup text area
click Save - this will automatically attempt to poll the URL and generate a screen
navigate to Playlists, drag/drop this Private Plugin to the top of your list, then click the button on the back of your TRMNL device to force-skip the content
your TRMNL device will refresh the screen, pulling the top-most item in your Playlist, which should be this sample render from your Private Plugin

Sample markup

<div class="layout">
  <div class="columns">
    <div class="column">
      <div class="markdown">
        <span class="title">Motivational Quote</span>
        <div class="content content--center">“I love inside jokes. I hope to be a part of one someday.”</div>
        <span class="label label--underline">Michael Scott</span>
      </div>
    </div>
  </div>
</div>

<div class="title_bar">
  <img class="image" src="https://usetrmnl.com/images/plugins/trmnl--render.svg" />
  <span class="title">Plugin Title</span>
  <span class="instance">Instance Title</span>
</div>

Step 4 - Share your Work

Totally optional, but we'd love to see what you built. Join the Developer-only Discord server (email [email protected] if you need an invite) and we can help you show it off on social media, etc.

Troubleshooting

I don't see any content

If you select Webhook as your strategy, you most POST data to the TRMNL server. Instructions to build this URL are available in our API docs.

If you select Polling as your strategy, TRMNL will GET from that endpoint and assume a JSON response. Headers are not supported at this time, only query params.

In all cases, the latest private plugin screen renders will appear first inside the Plugins > Private Plugin UI, then* on a device per your configured Playlist ordering and refresh rate.

I'm sending data but the screen isn't refreshing

By default, our backend skips generating screens if the merge variables are the same between requests. This applies to private and native plugins.

If you're atttempting to "force generate" a screen, perhaps in order to test new Markup or styling, you can work around this by by clicking the "Force Refresh" feature below your Plugin UUID.

Payload data isn't merging into my markup template

If you select Polling as your strategy, we suggest puting relevant merge variables in the root node of your payload.

GET /some-endpoint.json

# works
{
  name: "Jimmy",
  age: 43
}

# won't work unless markup uses {{ data.name }}, {{ data.age }} etc
{
  data: { name: "Jimmy", age: 43 }
}