mirror of
https://github.com/usetrmnl/api-docs.git
synced 2026-08-13 23:18:08 -07:00
Replace usetrmnl.com with trmnl.com
This commit is contained in:
DavidOrtmann
+1
-1
@@ -20,7 +20,7 @@ The TRMNL web server generates PNG images. When a device pings our [Display API]
|
||||
}
|
||||
```
|
||||
|
||||
For several ready-made OSS server implementations, see [BYOS Implementations](https://docs.usetrmnl.com/go/diy/byos#implementations). To develop your own server that is TRMNL firmware compatible out of the box:
|
||||
For several ready-made OSS server implementations, see [BYOS Implementations](https://docs.trmnl.com/go/diy/byos#implementations). To develop your own server that is TRMNL firmware compatible out of the box:
|
||||
|
||||
1. [build a device](byod.md)
|
||||
2. change the base URL to your own server or local network from the WiFi Captive Portal
|
||||
|
||||
+6
-6
@@ -20,14 +20,14 @@ Here's what you can expect to spend per component:
|
||||
**OSS approach**
|
||||
|
||||
1. Build a device and [flash our firmware](https://github.com/usetrmnl/trmnl-firmware)
|
||||
2. Spin up a [BYOS server client](https://docs.usetrmnl.com/go/diy/byos#implementations)
|
||||
2. Spin up a [BYOS server client](https://docs.trmnl.com/go/diy/byos#implementations)
|
||||
|
||||
**OSS + closed source approach**
|
||||
|
||||
1. Build a device and [flash our firmware](https://github.com/usetrmnl/trmnl-firmware)
|
||||
2. [Buy access](https://shop.usetrmnl.com/products/byod) to the TRMNL web app + API
|
||||
3. Create a BYOD device: [https://usetrmnl.com/claim-a-device](https://usetrmnl.com/claim-a-device)
|
||||
4. Visit your [device settings page](https://usetrmnl.com/devices/current/edit) to select your [Device Model](https://help.usetrmnl.com/en/articles/11547008-device-model-faq) and then, under the [Developer Perks](https://usetrmnl.com/devices/current/developer/edit) section set your DIY device's MAC address
|
||||
2. [Buy access](https://shop.trmnl.com/products/byod) to the TRMNL web app + API
|
||||
3. Create a BYOD device: [https://trmnl.com/claim-a-device](https://trmnl.com/claim-a-device)
|
||||
4. Visit your [device settings page](https://trmnl.com/devices/current/edit) to select your [Device Model](https://help.trmnl.com/en/articles/11547008-device-model-faq) and then, under the [Developer Perks](https://trmnl.com/devices/current/developer/edit) section set your DIY device's MAC address
|
||||
5. Your DIY device will render a 6-digit ID; this is your device's Friendly ID and is already visible inside your Device settings. No action is required.
|
||||
6. Connect native apps or **start building private plugins** from the Plugins tab; this is equivalent access as "Developer Edition" for TRMNL hardware.
|
||||
|
||||
@@ -36,7 +36,7 @@ Here's what you can expect to spend per component:
|
||||
On July 17, 2025 we announced a partnership with Seeed Studio.
|
||||
|
||||
* [Get the DIY kit](https://www.seeedstudio.com/TRMNL-7-5-Inch-OG-DIY-Kit-p-6481.html)
|
||||
* [Get a BYOD license](https://shop.usetrmnl.com/products/byod) (optional)
|
||||
* [Get a BYOD license](https://shop.trmnl.com/products/byod) (optional)
|
||||
* [Seeed Wiki - XIAO 7.5" panel](https://wiki.seeedstudio.com/xiao_7_5_inch_epaper_panel_with_trmnl/) (May 2025)
|
||||
* [Seeed Wiki - TRMNL DIY Kit](https://wiki.seeedstudio.com/trmnl_7inch5_diy_kit_main_page/) (July 2025)
|
||||
|
||||
@@ -56,4 +56,4 @@ Seeed Studio XIAO Esp32-C3 board
|
||||
|
||||
### Need Help?
|
||||
|
||||
Send us a live chat or join the Developer-only Discord, accessible from your [Account](https://usetrmnl.com/account) tab.
|
||||
Send us a live chat or join the Developer-only Discord, accessible from your [Account](https://trmnl.com/account) tab.
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ description: Buy a TRMNL device, then point it at your own server.
|
||||
|
||||
# BYOS
|
||||
|
||||
First, purchase a TRMNL from our [store](https://usetrmnl.com). Then choose a BYOS implementation for your stack. Our flagship implementation is Terminus (Hanami), so we recommended you get started there. But you can also choose from other languages/frameworks.
|
||||
First, purchase a TRMNL from our [store](https://trmnl.com). Then choose a BYOS implementation for your stack. Our flagship implementation is Terminus (Hanami), so we recommended you get started there. But you can also choose from other languages/frameworks.
|
||||
|
||||
**Why BYOS?**
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Create TRMNL-friendly images.
|
||||
|
||||
# ImageMagick Guide
|
||||
|
||||
TRMNL supports BMP3 and PNG images natively, starting with [FW v1.5.2](https://github.com/usetrmnl/firmware/releases/tag/v1.5.2). Below are some tips to generate TRMNL compatible images for DIY devices or [Alias](https://help.usetrmnl.com/en/articles/10701448-alias-plugin)/[Redirect](https://help.usetrmnl.com/en/articles/11035846-redirect-plugin) plugin applications.
|
||||
TRMNL supports BMP3 and PNG images natively, starting with [FW v1.5.2](https://github.com/usetrmnl/firmware/releases/tag/v1.5.2). Below are some tips to generate TRMNL compatible images for DIY devices or [Alias](https://help.trmnl.com/en/articles/10701448-alias-plugin)/[Redirect](https://help.trmnl.com/en/articles/11035846-redirect-plugin) plugin applications.
|
||||
|
||||
## Generating a BMP3 image <a href="#h_de4d75d195" id="h_de4d75d195"></a>
|
||||
|
||||
@@ -46,7 +46,7 @@ output.png PNG 800x480 800x480+0+0 8-bit Grayscale Gray 2c 1607B 0.000u 0:00.000
|
||||
|
||||
## Generating a PNG image (2 bit) <a href="#h_6b95d41fbd" id="h_6b95d41fbd"></a>
|
||||
|
||||
**This feature is experimental** and designed for OG model devices running [FW 1.6.0+](https://usetrmnl.com/flash) with grayscale + fast refresh support. After creating an image, upload it to a public or private/local network and point to it with an [Alias plugin](https://help.usetrmnl.com/en/articles/10701448-alias-plugin) instance.
|
||||
**This feature is experimental** and designed for OG model devices running [FW 1.6.0+](https://trmnl.com/flash) with grayscale + fast refresh support. After creating an image, upload it to a public or private/local network and point to it with an [Alias plugin](https://help.trmnl.com/en/articles/10701448-alias-plugin) instance.
|
||||
|
||||
First create a color map:
|
||||
|
||||
|
||||
+5
-5
@@ -6,18 +6,18 @@ description: Overview of TRMNL's architecture.
|
||||
|
||||
<figure><img src=".gitbook/assets/TRMNL architecture overview.png" alt=""><figcaption><p>Device, Server, Native Plugins, 3rd Party Developer, Firmware Components</p></figcaption></figure>
|
||||
|
||||
The TRMNL **web server** hosts a growing directory of [first-party plugins](https://usetrmnl.com/integrations) and [community plugins](https://usetrmnl.com/recipes) that are driven by [API endpoints](https://usetrmnl.com/api-docs) + a [templating engine](https://help.usetrmnl.com/en/articles/10671186-liquid-101). Our [Framework UI](https://usetrmnl.com/framework) design system is recommended, but not required, for plugin development. Learn how to build custom plugins [here](https://help.usetrmnl.com/en/articles/9510536-custom-plugins).
|
||||
The TRMNL **web server** hosts a growing directory of [first-party plugins](https://trmnl.com/integrations) and [community plugins](https://trmnl.com/recipes) that are driven by [API endpoints](https://trmnl.com/api-docs) + a [templating engine](https://help.trmnl.com/en/articles/10671186-liquid-101). Our [Framework UI](https://trmnl.com/framework) design system is recommended, but not required, for plugin development. Learn how to build custom plugins [here](https://help.trmnl.com/en/articles/9510536-custom-plugins).
|
||||
|
||||
The TRMNL **device** is a custom PCB featuring an ESP32-C3 microcontroller, 1800-2500 mAh battery, and 7.5" EPD screen housed in injection-molded ABS soft touch plastic. Customers may disassemble their device, mod their firmware, and retrieve their API keys without impacting our [Terms of Service](https://usetrmnl.com/terms).
|
||||
The TRMNL **device** is a custom PCB featuring an ESP32-C3 microcontroller, 1800-2500 mAh battery, and 7.5" EPD screen housed in injection-molded ABS soft touch plastic. Customers may disassemble their device, mod their firmware, and retrieve their API keys without impacting our [Terms of Service](https://trmnl.com/terms).
|
||||
|
||||
TRMNL **firmware** supports automatic OTA (over the air) updates to WiFi-connected devices and is [open source](https://github.com/usetrmnl/firmware). Here's how it works:
|
||||
TRMNL **firmware** supports automatic OTA (over the air) updates to WiFi-connected devices and is [open source](https://github.com/trmnl/firmware). Here's how it works:
|
||||
|
||||
1. TRMNL device wakes up and requests content from web server every _n_ period\*
|
||||
2. TRMNL web server generates a 1- or 2-bit PNG image. Response JSON includes a link to this image and timing instructions for the next "refresh" request.
|
||||
3. TRMNL device renders the content, then goes to sleep for the instructed amount of time.
|
||||
|
||||
{% hint style="info" %}
|
||||
\* "Displayable content" is the most recently created screen, in order of priority according to the [Playlists](https://help.usetrmnl.com/en/articles/11663305-playlist-scheduler) interface. "N" is a value in minutes, configurable by customers at a per-plugin or per-device level.
|
||||
\* "Displayable content" is the most recently created screen, in order of priority according to the [Playlists](https://help.trmnl.com/en/articles/11663305-playlist-scheduler) interface. "N" is a value in minutes, configurable by customers at a per-plugin or per-device level.
|
||||
{% endhint %}
|
||||
|
||||
## Opinionated device <> server relationship
|
||||
@@ -26,7 +26,7 @@ Most IoT products support SSH-ing directly into peripheral devices. We've heard
|
||||
|
||||
**Your TRMNL device pings our server, never the other way around**.
|
||||
|
||||
Each request to our `/api/display` endpoint ([docs](https://docs.usetrmnl.com/go/private-api/screens)) includes only the minimum details needed to support customers -- an API key, device mac address, firmware version, battery voltage, and WiFi signal strength.
|
||||
Each request to our `/api/display` endpoint ([docs](https://docs.trmnl.com/go/private-api/screens)) includes only the minimum details needed to support customers -- an API key, device mac address, firmware version, battery voltage, and WiFi signal strength.
|
||||
|
||||
**We do not collect any footprint of your location or identity**, such as IP address or WiFi credentials. Your local network's SSID and password are stored only on your TRMNL device.
|
||||
|
||||
|
||||
@@ -12,4 +12,4 @@ Example scenario:
|
||||
2. Acme wants to gift a free TRMNL device to their top customers. Acme creates coupon codes with the TRMNL Partners API that their customer can use at checkout for X% off their order.
|
||||
3. When Acme's customer device is shipped, it is associated to their account on Acme's platform. Upon unboxing + WiFi pairing, Acme's customer will see their Acme native dashboard on TRMNL device without any additional setup.
|
||||
|
||||
Continue reading to learn how this works with just a single API request, or email [partners@usetrmnl.com](mailto:partners@usetrmnl.com) to get started.
|
||||
Continue reading to learn how this works with just a single API request, or email [partners@trmnl.com](mailto:partners@trmnl.com) to get started.
|
||||
|
||||
@@ -35,7 +35,7 @@ If a quota is preferred, for example 50x maximum provisions per month, this endp
|
||||
|
||||
**Step 2 - TRMNL generates a coupon**
|
||||
|
||||
Provide the `code`from Step 1 to your customer with instructions to purchase a device from usetrmnl.com. They can provide this code at checkout.
|
||||
Provide the `code`from Step 1 to your customer with instructions to purchase a device from trmnl.com. They can provide this code at checkout.
|
||||
|
||||
If your discount is for 100% off, they will not be charged. If your code is for 50% off, they will pay 50% at checkout. You will be billed via invoice later for claimed discount codes during the agreed period. Additional terms are possible, for example requiring customers to pay for shipping, or only subsidizing a device with our regular (vs large size) battery, etc.
|
||||
|
||||
@@ -45,4 +45,4 @@ Prior to this workflow being implemented, TRMNL should have already tested your
|
||||
|
||||
Whatever key/values are provided in the `data` node of Step 1 will be saved to the user's pre-loaded plugin when their device is unboxed and set up. Thus these key/values should match exactly the merge variables required by the plugin setting instance.
|
||||
|
||||
Contact [partners@usetrmnl.com](mailto:partners@usetrmnl.com) with questions or requests.
|
||||
Contact [partners@trmnl.com](mailto:partners@trmnl.com) with questions or requests.
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Publish your plugin for all users with a simple submission flow.
|
||||
|
||||
# Going Live
|
||||
|
||||
After building and testing your plugin, copy/paste the following application into an email to team@usetrmnl.com.
|
||||
After building and testing your plugin, copy/paste the following application into an email to team@trmnl.com.
|
||||
|
||||
Subject: 
|
||||
|
||||
@@ -29,7 +29,7 @@ Video demonstration:
|
||||
{{ link to video, no audio required, of the plugin being installed from scratch. }}
|
||||
|
||||
How can we test this plugin works?
|
||||
{{ preferably a demo login email/password that we can own forever, ex "team@usetrmnl.com" }}
|
||||
{{ preferably a demo login email/password that we can own forever, ex "team@trmnl.com" }}
|
||||
|
||||
Will you promote TRMNL when this plugin is published? If so, how/where?
|
||||
{{ no wrong answers, but we prioritize plugins that help us grow }}
|
||||
|
||||
@@ -4,14 +4,14 @@ description: TRMNL's plugin marketplace lets anyone publish and share their work
|
||||
|
||||
# Introduction
|
||||
|
||||
Our plugin marketplace is where developers can make plugins for other users to install. Beginning November 2025 [TRMNL pays developers](https://usetrmnl.com/blog/creator-fund) for their work.
|
||||
Our plugin marketplace is where developers can make plugins for other users to install. Beginning November 2025 [TRMNL pays developers](https://trmnl.com/blog/creator-fund) for their work.
|
||||
|
||||
There are 2 approaches to publishing a plugin for other users — Public, or Recipe. Review the differences between them before continuing:
|
||||
|
||||
{% embed url="https://help.usetrmnl.com/en/articles/10546870-compare-custom-plugin-types" %}
|
||||
{% embed url="https://help.trmnl.com/en/articles/10546870-compare-custom-plugin-types" %}
|
||||
|
||||
**Recipes** may be built inside the TRMNL interface and do not require any 3rd party dependencies, user auth, etc. To build a Recipe, [start here](https://help.usetrmnl.com/en/articles/9510536-private-plugins). Or browse and install 100s of Recipes here:\
|
||||
[https://usetrmnl.com/recipes](https://usetrmnl.com/recipes)
|
||||
**Recipes** may be built inside the TRMNL interface and do not require any 3rd party dependencies, user auth, etc. To build a Recipe, [start here](https://help.trmnl.com/en/articles/9510536-private-plugins). Or browse and install 100s of Recipes here:\
|
||||
[https://trmnl.com/recipes](https://trmnl.com/recipes)
|
||||
|
||||
**Public plugins** require a simplified OAuth2 flow. In this scenario, the plugin author (you) maintains user data and is responsible for data privacy and security. TRMNL fetches markup from your server at regular intervals and generates images for the connected user's device to display. To build a Public Plugin, continue reading this guide. Or browse native + public plugins here: [https://usetrmnl.com/integrations](https://usetrmnl.com/integrations)
|
||||
**Public plugins** require a simplified OAuth2 flow. In this scenario, the plugin author (you) maintains user data and is responsible for data privacy and security. TRMNL fetches markup from your server at regular intervals and generates images for the connected user's device to display. To build a Public Plugin, continue reading this guide. Or browse native + public plugins here: [https://trmnl.com/integrations](https://trmnl.com/integrations)
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ description: Creating a plugin OAuth client.
|
||||
You can create a new plugin by visiting the following URL:
|
||||
|
||||
```
|
||||
https://usetrmnl.com/plugins/my/new
|
||||
https://trmnl.com/plugins/my/new
|
||||
```
|
||||
|
||||
<figure><img src="../.gitbook/assets/trmnl-plugin-form.png" alt="" width="375"><figcaption><p>TRMNL public plugin client</p></figcaption></figure>
|
||||
|
||||
@@ -21,7 +21,7 @@ body = {
|
||||
client_secret: 'your-plugin-secret',
|
||||
grant_type: 'authorization_code'
|
||||
}
|
||||
response = HTTParty.post("https://usetrmnl.com/oauth/token", body: body)
|
||||
response = HTTParty.post("https://trmnl.com/oauth/token", body: body)
|
||||
response['access_token']
|
||||
```
|
||||
|
||||
@@ -49,7 +49,7 @@ Body:
|
||||
{
|
||||
"user": {
|
||||
"name":"Ronak J",
|
||||
"email":"ronak@usetrmnl.com",
|
||||
"email":"ronak@trmnl.com",
|
||||
"first_name":"Ronak",
|
||||
"last_name":"J",
|
||||
"locale":"en",
|
||||
@@ -65,4 +65,4 @@ Body:
|
||||
Time zone mappings are available here under "Constants:"\
|
||||
[https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html](https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html)
|
||||
|
||||
The `plugin_setting_id`is useful for building a redirect URI in your own application, for example to send a user back to usetrmnl.com/plugin\_settings/:plugin\_setting\_id/edit.
|
||||
The `plugin_setting_id`is useful for building a redirect URI in your own application, for example to send a user back to trmnl.com/plugin\_settings/:plugin\_setting\_id/edit.
|
||||
|
||||
@@ -49,7 +49,7 @@ The `trmnl` object in this payload may or may not be useful for your plugin, but
|
||||
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.
|
||||
|
||||
{% hint style="success" %}
|
||||
**Pro tip**: use the [Private Plugin](https://usetrmnl.com/plugin_settings/new?keyname=private_plugin) 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.
|
||||
**Pro tip**: use the [Private Plugin](https://trmnl.com/plugin_settings/new?keyname=private_plugin) 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.
|
||||
{% endhint %}
|
||||
|
||||
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.
|
||||
@@ -66,4 +66,4 @@ Here's an example of a valid server response:
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** in order for your plugin to be published in the TRMNL public marketplace, you must provide HTML for all available markup layouts. [View them here](https://help.usetrmnl.com/en/articles/10168132-mashups).
|
||||
**Note:** in order for your plugin to be published in the TRMNL public marketplace, you must provide HTML for all available markup layouts. [View them here](https://help.trmnl.com/en/articles/10168132-mashups).
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
description: Control aspects of your usetrmnl.com account
|
||||
description: Control aspects of your trmnl.com account
|
||||
---
|
||||
|
||||
# Account API
|
||||
|
||||
In addition to the [device API](screens.md), users who have purchased a developer license can access the account API. You can enumerate your devices, import and export plugins, control playlists, and more.
|
||||
|
||||
See the [**OpenAPI specification**](https://usetrmnl.com/api-docs/index.html) for complete details.
|
||||
See the [**OpenAPI specification**](https://trmnl.com/api-docs/index.html) for complete details.
|
||||
|
||||
We have also open-sourced an official [**trmnl-api**](https://github.com/usetrmnl/trmnl-api) Ruby gem for API clients.
|
||||
|
||||
@@ -16,14 +16,14 @@ These endpoints are being continually improved upon as we discover new use-cases
|
||||
|
||||
## Authentication
|
||||
|
||||
The account API key can be retrieved from [your account settings](https://usetrmnl.com/account). It begins with `user_`.
|
||||
The account API key can be retrieved from [your account settings](https://trmnl.com/account). It begins with `user_`.
|
||||
|
||||
API authentication is done via the HTTP Authorization header with bearer tokens, e.g. `Authorization: Bearer user_xxxxx`
|
||||
|
||||
## Example
|
||||
|
||||
```javascript
|
||||
// GET https://usetrmnl.com/api/devices
|
||||
// GET https://trmnl.com/api/devices
|
||||
|
||||
{
|
||||
"data": [
|
||||
|
||||
@@ -6,4 +6,4 @@ description: Additional options to customize your setup.
|
||||
|
||||
To interact with Devices, Playlists, Plugin Settings, and other resources, see our Swagger docs:
|
||||
|
||||
[https://usetrmnl.com/api-docs/](https://usetrmnl.com/api-docs/index.html)
|
||||
[https://trmnl.com/api-docs/](https://trmnl.com/api-docs/index.html)
|
||||
|
||||
@@ -7,7 +7,7 @@ description: Retrieve parsed plugin JSON data for your own templates.
|
||||
No matter how many customizations we add to plugins, there will always be good reasons to add more. Instead of cluttering our interface, TRMNL offers a "data only" mode.
|
||||
|
||||
{% hint style="info" %}
|
||||
For more context on this feature, go [here](https://usetrmnl.com/blog/calendar-hackathon). For live examples, [go here](https://usetrmnl.com/blog/introducing-data-mode).
|
||||
For more context on this feature, go [here](https://trmnl.com/blog/calendar-hackathon). For live examples, [go here](https://trmnl.com/blog/introducing-data-mode).
|
||||
{% endhint %}
|
||||
|
||||
### Looking for the old way?
|
||||
@@ -32,17 +32,17 @@ Parsed data will appear inside a `<plugin_keyname>_<plugin_setting_id>` node of
|
||||
|
||||
<figure><img src="../.gitbook/assets/TRMNL-data-mode-example-node.png" alt=""><figcaption><p>Example - Outlook Calendar events JSON</p></figcaption></figure>
|
||||
|
||||
Reference as many connected plugins as you'd like. When TRMNL refreshes those plugins per your [Playlist Schedule](https://help.usetrmnl.com/en/articles/11663305-playlist-scheduler), updated values will map over to your private plugin with the Plugin Merge strategy.
|
||||
Reference as many connected plugins as you'd like. When TRMNL refreshes those plugins per your [Playlist Schedule](https://help.trmnl.com/en/articles/11663305-playlist-scheduler), updated values will map over to your private plugin with the Plugin Merge strategy.
|
||||
|
||||
### Markup Quickstart
|
||||
|
||||
If you only want to make small changes to the TRMNL native design, steal that markup here:
|
||||
|
||||
* [https://github.com/usetrmnl/plugins/](https://github.com/usetrmnl/plugins/) (raw inside `lib`, let us know what else you need)
|
||||
* [https://usetrmnl.com/plugins/demo](https://usetrmnl.com/plugins/demo) (rendered output, requires login)
|
||||
* [https://trmnl.com/plugins/demo](https://trmnl.com/plugins/demo) (rendered output, requires login)
|
||||
|
||||
In the raw/GitHub option, note that native plugins leverage the ERB templating language, so markup `<% variable %>` references will need to be replaced with Liquid `{{ variable }}` and so forth.
|
||||
|
||||
In the `/demo` option, click the plugin you're rebuilding and all layouts will appear with sample data. If you've connected a plugin natively, your latest cached JSON will be embedded instead of demo data.
|
||||
|
||||
Another tip on the `/demo` option is to add `?data=true` to the URL, for example `https://usetrmnl.com/plugins/google_calendar?data=true` to see how TRMNL combines your own JSON data with our native ERB markup. If you have multiple instances that you'd like to check out, also append `&plugin_setting_id=<id-here>` to render a specific plugin instance on the demo page.
|
||||
Another tip on the `/demo` option is to add `?data=true` to the URL, for example `https://trmnl.com/plugins/google_calendar?data=true` to see how TRMNL combines your own JSON data with our native ERB markup. If you have multiple instances that you'd like to check out, also append `&plugin_setting_id=<id-here>` to render a specific plugin instance on the demo page.
|
||||
|
||||
@@ -4,16 +4,16 @@ description: Retrieve TRMNL image data, device-free.
|
||||
|
||||
# Fetch Screen Content
|
||||
|
||||
First, set up a TRMNL device or [BYOD license](https://shop.usetrmnl.com/products/byod).
|
||||
First, set up a TRMNL device or [BYOD license](https://shop.trmnl.com/products/byod).
|
||||
|
||||
Next, grab your API Key from [Devices > Edit](https://usetrmnl.com/devices) and make a request like below.
|
||||
Next, grab your API Key from [Devices > Edit](https://trmnl.com/devices) and make a request like below.
|
||||
|
||||
### Auto advance content
|
||||
|
||||
This endpoint is used by our firmware (on your device) to fetch new screen content. Making a request to this endpoint automatically 'advances' your Playlist to the next item in your queue. To simply grab the current screen instead, skip to the next section below.
|
||||
|
||||
```
|
||||
curl https://usetrmnl.com/api/display --header "access-token:xxxxxx"
|
||||
curl https://trmnl.com/api/display --header "access-token:xxxxxx"
|
||||
```
|
||||
|
||||
This will respond with several fields, for example:
|
||||
@@ -40,10 +40,10 @@ These attributes impact the response content by instructing the device to either
|
||||
|
||||
### Current screen
|
||||
|
||||
If you're expanding a TRMNL fleet with BYOD devices, such as a [Raspberry Pi](https://usetrmnl.com/blog/rpi-trmnl) or [Kindle](https://usetrmnl.com/guides/turn-your-amazon-kindle-into-a-trmnl), [Android](https://github.com/usetrmnl/trmnl-android), or [Kobo](https://github.com/usetrmnl/trmnl-kobo) tablet, you may prefer to mirror whatever content is showing on your official TRMNL or BYOD device.
|
||||
If you're expanding a TRMNL fleet with BYOD devices, such as a [Raspberry Pi](https://trmnl.com/blog/rpi-trmnl) or [Kindle](https://trmnl.com/guides/turn-your-amazon-kindle-into-a-trmnl), [Android](https://github.com/usetrmnl/trmnl-android), or [Kobo](https://github.com/usetrmnl/trmnl-kobo) tablet, you may prefer to mirror whatever content is showing on your official TRMNL or BYOD device.
|
||||
|
||||
```
|
||||
curl https://usetrmnl.com/api/current_screen --header "access-token:xxxxxx"
|
||||
curl https://trmnl.com/api/current_screen --header "access-token:xxxxxx"
|
||||
```
|
||||
|
||||
This will respond with the following fields:
|
||||
@@ -51,12 +51,12 @@ This will respond with the following fields:
|
||||
```
|
||||
{"status" => 200,
|
||||
"refresh_rate" => 1800,
|
||||
"image_url" => "https://usetrmnl.com/rails/active_storage/blobs/redirect/hash-here/plugin-YYYY-MM-DD-TXX-XX-XXZ-hash",
|
||||
"image_url" => "https://trmnl.com/rails/active_storage/blobs/redirect/hash-here/plugin-YYYY-MM-DD-TXX-XX-XXZ-hash",
|
||||
"filename" => "plugin-YYYY-MM-DD-TXX-XX-XXZ-hash",
|
||||
"rendered_at" => nil
|
||||
}
|
||||
```
|
||||
|
||||
{% hint style="info" %}
|
||||
**Note**: the `current_screen` endpoint was designed for consumption by our [Chrome extension](https://usetrmnl.com/chrome). Please don't abuse it.
|
||||
**Note**: the `current_screen` endpoint was designed for consumption by our [Chrome extension](https://trmnl.com/chrome). Please don't abuse it.
|
||||
{% endhint %}
|
||||
|
||||
@@ -6,9 +6,9 @@ description: Go deeper with custom screen styling, data visualization, and more.
|
||||
|
||||
## Overview
|
||||
|
||||
The TRMNL design system is actively improving to suit the needs of our [growing plugin directory](https://usetrmnl.com/integrations) and requests from developers like you.
|
||||
The TRMNL design system is actively improving to suit the needs of our [growing plugin directory](https://trmnl.com/integrations) and requests from developers like you.
|
||||
|
||||
As we extend [native components](https://usetrmnl.com/framework), you are welcome to provide in-line styling to plugin markup to achieve your desired effect.
|
||||
As we extend [native components](https://trmnl.com/framework), you are welcome to provide in-line styling to plugin markup to achieve your desired effect.
|
||||
|
||||
You may also included 3rd party libraries, for example [Highcharts](https://www.highcharts.com/), to create data visualizations like charts and graphs.
|
||||
|
||||
@@ -50,7 +50,7 @@ Highcharts.chart("container", {
|
||||
</script>
|
||||
```
|
||||
|
||||
If this is saved into a [Private Plugin](https://usetrmnl.com/plugin_settings?keyname=private_plugin) > Markup field, the following screen will be rendered:
|
||||
If this is saved into a [Private Plugin](https://trmnl.com/plugin_settings?keyname=private_plugin) > Markup field, the following screen will be rendered:
|
||||
|
||||
<figure><img src="../.gitbook/assets/chart-example.bmp" alt=""><figcaption><p>Un-styled chart example</p></figcaption></figure>
|
||||
|
||||
@@ -61,8 +61,8 @@ Here's another line chart with TRMNL-friendly styling:
|
||||
<figure><img src="../.gitbook/assets/trmnl-line-chart-example.png" alt=""><figcaption><p>Styled line chart example</p></figcaption></figure>
|
||||
|
||||
Get all the code + learn how to do this here:\
|
||||
[https://usetrmnl.com/framework/chart](https://usetrmnl.com/framework/chart)
|
||||
[https://trmnl.com/framework/chart](https://trmnl.com/framework/chart)
|
||||
|
||||
## More Charts and Graphs
|
||||
|
||||
Our [Framework docs](https://usetrmnl.com/framework) are the best place for the latest examples and tips to improve the look and feel of graphical embeds from 3rd party tools like Highcharts.
|
||||
Our [Framework docs](https://trmnl.com/framework) are the best place for the latest examples and tips to improve the look and feel of graphical embeds from 3rd party tools like Highcharts.
|
||||
|
||||
@@ -6,14 +6,14 @@ description: TRMNL's native design system for developing beautiful, e-ink friend
|
||||
|
||||
## Overview
|
||||
|
||||
The TRMNL OG device is an **800x480 pixel, black and white, 2-bit grayscale display**. This means we had to abandon a lot of modern web styling techniques. Learn more about this process [here](https://usetrmnl.com/blog/design-system).
|
||||
The TRMNL OG device is an **800x480 pixel, black and white, 2-bit grayscale display**. This means we had to abandon a lot of modern web styling techniques. Learn more about this process [here](https://trmnl.com/blog/design-system).
|
||||
|
||||
For the latest documentation on building beautiful plugins with TRMNL, see our Framework docs:\
|
||||
[https://usetrmnl.com/framework](https://usetrmnl.com/framework)
|
||||
[https://trmnl.com/framework](https://trmnl.com/framework)
|
||||
|
||||
### Quickstart (TRMNL account)
|
||||
|
||||
The easiest way to start building with TRMNL is by [making a Private Plugin](https://usetrmnl.com/plugin_settings?keyname=private_plugin) from inside your account. This includes an inline editor, merge variable interpolation, and a live previewer.
|
||||
The easiest way to start building with TRMNL is by [making a Private Plugin](https://trmnl.com/plugin_settings?keyname=private_plugin) from inside your account. This includes an inline editor, merge variable interpolation, and a live previewer.
|
||||
|
||||
<figure><img src="../.gitbook/assets/trmnl-markup-editor-live-preview.png" alt=""><figcaption><p>TRMNL markup editor with live preview</p></figcaption></figure>
|
||||
|
||||
@@ -27,8 +27,8 @@ The example below has simple markup for a "full" layout plugin. We also offer ha
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<link rel="stylesheet" href="https://usetrmnl.com/css/latest/plugins.css">
|
||||
<script src="https://usetrmnl.com/js/latest/plugins.js"></script>
|
||||
<link rel="stylesheet" href="https://trmnl.com/css/latest/plugins.css">
|
||||
<script src="https://trmnl.com/js/latest/plugins.js"></script>
|
||||
</head>
|
||||
<body class="environment trmnl">
|
||||
<div class="screen">
|
||||
@@ -46,7 +46,7 @@ The example below has simple markup for a "full" layout plugin. We also offer ha
|
||||
</div>
|
||||
|
||||
<div class="title_bar">
|
||||
<img class="image" src="https://usetrmnl.com/images/plugins/trmnl--render.svg" />
|
||||
<img class="image" src="https://trmnl.com/images/plugins/trmnl--render.svg" />
|
||||
<span class="title">Plugin Title</span>
|
||||
<span class="instance">Instance Title</span>
|
||||
</div>
|
||||
@@ -70,12 +70,12 @@ Note: in some cases you may need to include the 'Inter' font (inside the `<head>
|
||||
|
||||
### Customize and make it dynamic
|
||||
|
||||
Use our [Framework Docs](https://usetrmnl.com/framework) to enhance your design and show/hide logic (example: [overflow management](https://usetrmnl.com/framework/overflow), [number formatting](https://usetrmnl.com/framework/format_value)).
|
||||
Use our [Framework Docs](https://trmnl.com/framework) to enhance your design and show/hide logic (example: [overflow management](https://trmnl.com/framework/overflow), [number formatting](https://trmnl.com/framework/format_value)).
|
||||
|
||||
When you're satisfied with the design, replace dynamic content with `{{ variable }}` references. TRMNL uses the [Liquid templating library](https://shopify.github.io/liquid/) by Shopify to interpolate values into your template markup. You can then save
|
||||
|
||||
{% hint style="info" %}
|
||||
[Tutorial - How to create a custom plugin](https://help.usetrmnl.com/en/articles/9510536-custom-plugins)
|
||||
[Tutorial - How to create a custom plugin](https://help.trmnl.com/en/articles/9510536-custom-plugins)
|
||||
{% endhint %}
|
||||
|
||||
**Note**: You may also leverage [Liquid Filters](https://shopify.dev/docs/api/liquid/filters) to reduce the sanitization required by the service producing data for your TRMNL plugins. For example, you can convert "10" to "$10.00" via [money\_with\_currency](https://shopify.dev/docs/api/liquid/filters/money).
|
||||
|
||||
@@ -7,18 +7,18 @@ description: Send a payload of merge variables to create a custom screen.
|
||||
{% hint style="info" %}
|
||||
#### Before you begin
|
||||
|
||||
Learn how to build Private Plugins [here](https://help.usetrmnl.com/en/articles/9510536-private-plugins). The guide below only explains how to use the "Webhook" data retrieval strategy.
|
||||
Learn how to build Private Plugins [here](https://help.trmnl.com/en/articles/9510536-private-plugins). The guide below only explains how to use the "Webhook" data retrieval strategy.
|
||||
{% endhint %}
|
||||
|
||||
### Rate Limits
|
||||
|
||||
_Request volume_
|
||||
|
||||
You may send data to TRMNL's server up to 12x per hour. [TRMNL+](https://help.usetrmnl.com/en/articles/11861887-trmnl-faq) subscribers may send up to 30x payloads per hour. Webhooks sent at a faster pace will receive a `429` rate limit response. To temporarily increase your rate limit during development, enable "Debug Logs" on your plugin settings page.
|
||||
You may send data to TRMNL's server up to 12x per hour. [TRMNL+](https://help.trmnl.com/en/articles/11861887-trmnl-faq) subscribers may send up to 30x payloads per hour. Webhooks sent at a faster pace will receive a `429` rate limit response. To temporarily increase your rate limit during development, enable "Debug Logs" on your plugin settings page.
|
||||
|
||||
_Request size_
|
||||
|
||||
You may send up to 2kb of data. [TRMNL+](https://help.usetrmnl.com/en/articles/11861887-trmnl-faq) subscribers may send up to 5kb of data. To stay within these boundaries while also creating a data rich experience, consider using the `deep_merge` and `stream` strategies documented below.
|
||||
You may send up to 2kb of data. [TRMNL+](https://help.trmnl.com/en/articles/11861887-trmnl-faq) subscribers may send up to 5kb of data. To stay within these boundaries while also creating a data rich experience, consider using the `deep_merge` and `stream` strategies documented below.
|
||||
|
||||
### Authorization
|
||||
|
||||
@@ -37,7 +37,7 @@ This is accessible from your plugin instance's configuration form > Webhook URL
|
||||
Send a `POST` request to your Webhook URL. Put data inside a `merge_variables` node like so:
|
||||
|
||||
```
|
||||
curl "https://usetrmnl.com/api/custom_plugins/asdfqwerty1234" \
|
||||
curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"merge_variables": {"text":"You can do it!", "author": "Rob Schneider"}}' \
|
||||
-X POST
|
||||
@@ -52,7 +52,7 @@ You will see this payload inside the Your Variables dropdown of the Markup Edito
|
||||
To fetch existing `merge_variables` from a private plugin, `GET` from the same endpoint:
|
||||
|
||||
```
|
||||
curl "https://usetrmnl.com/api/custom_plugins/asdfqwerty1234"
|
||||
curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234"
|
||||
```
|
||||
|
||||
### Update existing content
|
||||
@@ -66,7 +66,7 @@ There are two strategies to accomplish this: `deep_merge`, and `stream`.
|
||||
The `deep_merge` strategy combines existing key/value pairs with the new values incoming on the webhook. It's a good way to update nested data with only a few values here and there.
|
||||
|
||||
```
|
||||
curl "https://usetrmnl.com/api/custom_plugins/asdfqwerty1234" \
|
||||
curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"merge_variables": {"sensor": {"temperature": 42}}, "merge_strategy": "deep_merge"}' \
|
||||
-X POST
|
||||
@@ -77,7 +77,7 @@ curl "https://usetrmnl.com/api/custom_plugins/asdfqwerty1234" \
|
||||
The `stream` strategy is useful for accumulating values in arrays. Any top-level arrays are appended with the incoming values, and the `stream_limit` parameter ensures that old values drop off the arrays so they don't grow forever.
|
||||
|
||||
```
|
||||
curl "https://usetrmnl.com/api/custom_plugins/asdfqwerty1234" \
|
||||
curl "https://trmnl.com/api/custom_plugins/asdfqwerty1234" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"merge_variables": {"temperatures": [40, 42]}, "merge_strategy": "stream", "stream_limit": 10}' \
|
||||
-X POST
|
||||
@@ -89,4 +89,4 @@ Now you may iterate through the combined data inside your markup, for example:
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
For more help, see our [Private Plugin guide](https://help.usetrmnl.com/en/articles/9510536-custom-plugins) or join the developer Discord from your account tab.
|
||||
For more help, see our [Private Plugin guide](https://help.trmnl.com/en/articles/9510536-custom-plugins) or join the developer Discord from your account tab.
|
||||
|
||||
@@ -6,4 +6,4 @@ description: Valid plugin categories to increase search exposure.
|
||||
|
||||
When developing a Public or Recipe style plugin, you may add indexed categories to improve visibility in search results.
|
||||
|
||||
[https://usetrmnl.com/api/categories](https://usetrmnl.com/api/categories)
|
||||
[https://trmnl.com/api/categories](https://trmnl.com/api/categories)
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user