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
  • Implementations
  • API
  1. DIY TRMNL (Advanced)

BYOS

Buy a TRMNL device, then point it at your own server.

PreviousBYOD/SNextImageMagick Guide

Last updated 16 days ago

First, purchase a TRMNL from our . Then choose a BYOS implementation for your stack. Our reference implementation is Terminus (Hanami) and we recommended you get started there but you can also choose from other languages/frameworks as well.

Screencast

The following screencast will walk you through setting up Terminus and connecting your device to it.

Why BYOS?

TRMNL intends to ensure that every device is un-brickable and can run with zero external dependencies.

Implementations

We support multiple implementations developed by us and the community at large. The goal isn't for BYOS to match parity with our hosted solution but to provide enough of a pleasant solution for your own customized experience. There are trade offs either way but we've got you covered for whatever path you wish to travel.

Legend

Use this legend to understand the matrix of features below.

  • 🟢 Supported.

  • 🟡 Partially supported.

  • 🔴 Not supported or not implemented.

  • ⚫️ Archived with minimal maintenance support.

  • ⚪️ Unknown.

Matrix

Below is a list of all implementations in various languages/frameworks you can use to self-host and manage your devices with:

Implementation
Dashboard
Auto-Provisioning
Devices
JSON Data API
Image Previews
Playlists
Plugins
Recipes
Docker
Test Suite
Maintained
Semantic Versioning

🟢

🟢

🟢

🟢

🟢

🟡

🟢

🟢

🟢

🟢

🟢

🟢

🔴

🔴

🟢

🟢

🟢

🟢

🔴

🔴

🔴

🔴

🔴

⚪️

🟡

🔴

🟡

🟢

🔴

🔴

🔴

🔴

🟢

🟢

⚫️

🟢

🔴

🔴

🟢

🟢

🟢

🔴

🔴

🔴

🟢

🔴

🟢

⚪️

🟢

🟢

🟢

🟢

🟢

🟢

🟢

🟢

🟢

🟢

🟢

🔴

🟢

🟢

🟢

🟢

🟢

🔴

🔴

🟢

🔴

🔴

🟢

⚪️

The following provides a detailed breakdown of each of the above features:

  • Dashboard: Provides a high level overview of information mostly in terms of quick links, statistics, charts, graphs, system health, etc.

  • Auto-Provisioning: Devices can be automatically provisioned once added to your network. This includes the automatic provisioning of new and existing devices.

  • Devices: Provides device management in terms of updating each device, viewing current image, viewing logs, and more.

  • JSON Data API: Provides full API support using a JSON Data API for device management, image generation, logging, and more.

  • Image Previews: Provides a UI for quickly, and dynamically, generating new device screens.

  • Playlists: Supports playlist configuration and management in terms of timing, order, and display of screens on devices. This can also include proxying to our Core server.

  • Plugins: Supports installation and hosting of custom plugins. This can also include proxying to our Core server.

  • Recipes: Supports installation and hosting of custom plugins. This can also include proxying to our Core server.

  • Docker: Supports Docker for both local development and production deployment.

  • Test Suite: Has a test suite with near 100% test coverage, is fully runnable locally, and is wired up with automatic Continuous Integration (CI) builds.

  • Maintained: Project is maintained and kept up-to-date on a weekly (or monthly) basis in terms of dependencies, firmware updates, and keeping up-to-date with any/all Core changes.

API

At a minimum, the following API endpoints should be supported for all BYOS implementations:

Display

curl "http://byos.local/api/display" \
     -H 'ID: <redacted>' \
     -H 'Access-Token: <redacted>' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json'

Images

curl -X "POST" "http://byos.local/api/images" \
    -H 'ID: <redacted>' \
    -H 'Access-Token: <redacted>' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d $'{
 "image": {
   "content": "<p>Demo</p>"
   "file_name": "demo"
 }
}'

Logs

curl "http://byos.local/api/log" \
     -H 'ID: <redacted>' \
     -H 'Access-Token: <redacted>' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json'

Setup

curl "https://byos.local/api/setup/" \
    -H 'ID: <redacted>' \
    -H 'Access-Token: <redacted>' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

(Ruby + Hanami)

(Elixir + Phoenix)

(Ruby + Sinatra)

(Python + Django)

(PHP + Laravel)

(Next.js)

Semantic Versioning: Supports .

💡 For a detailed breakdown of all API endpoints and what they can do, please refer to the or the gem which provides a Ruby API client for talking to our servers.

strict semantic versioning
Terminus API Documentation
TRMNL API
home page
TRMNL Terminus
TRMNL
TRMNL
Community
Community
Community