Image server for TRMNL built with Node.js, JSX and HTML

You can create TRMNL screen just like website: collect data with JavaScript and design layout with JSX(React) or HTML with Liquid templates.

This repository generates an image that you can use via Redirect or Alias plugins, or run it as own BYOS.

Goal: simple and easy to customize starter for people who are already familiar with the JavaScript ecosystem.

Features

• Creating screens with JSX or HTML(Liquid)
• Generating screen (image) with preview
• JSON Data API
• BYOS (Auto-Provisioning, screens, device logs)
• Migrating any Plugin (via Liquid)
• Playlists (set of screens)
• Proxying screens (plugins) from Core
• Docker
• no database required (everything in ENV and Config)
• no dashboard

Quick Start

1. Press button Use this template on Github, or clone this repository
2. Copy .env.local to .env.example and change values to yours
3. Run npm run watch for local preview

Or run via Docker:

docker build -t trmnl . && docker run --env-file .env.local -p 3000:3000 trmnl

After run, you can change files in src/Template and src/Data to something that you want to display.

Later, to display screen on device you would need to deploy, provide endpoints in plugin settings, or setup your device to BYOS.

---

Technologies used:

• Headless Chrome for rendering HTML or JSX to image
• Liquid for HTML templating (same used by usetrmnl.com)
• React if you want to use JSX components
• Express.js as API server
• TSX for supporting JSX/TSX files

Endpoints for plugins

Image https://yourserver.com/image?secret_key=...
↑ can be used for preview and Alias plugin

JSON https://yourserver.com/plugin/redirect?secret_key=...
↑ can be used for Redirect plugin

Liquid templates

see example here

JSX components

• You can use regular JSX components (similar to React), but without hooks, as screen is rendering only once.
  
• Starting point is App.tsx
  
• It's easier to collect all variables and data in one place, before components. But you can change to any structure that you prefer.
• You can include local images by using LocalImage component or specify public url to somewhere.

Your Server

To run your TRMNL server you need any form of server (VM, droplet, pod, instance) somewhere, for example AWS, Google Cloud, Digital Ocean.

• it can be run via Dockerfile or command npm run start
• Better to pass ENV parameters from secure storage that your cloud provider has

Bring your own server (BYOS)

You can skip using plugins and connect your device to your server directly by using BYOS mode. After changing configuration to BYOS your device will stop doing API requests to usetrmnl.com servers. You can even close it in private network for data security.

This repo implements basic BYOS server for one device.

You can enable it with those steps:

1. Set BYOS_ENABLED = true in Config
2. Put your device's MAC value to ENV key BYOS_DEVICE_MAC (it can be via .env.local). If you don't know it - you can do this step later.
3. Generate or use usetrmnl.com access token in ENV key BYOS_DEVICE_ACCESS_TOKEN
4. Hold round button on your device for more than 5 seconds - you should see connection instructions on screen.
5. Connect your phone to wifi called TRMNL
6. On setup choose Custom server (see screenshot below) and provide address of your server. In case of local computer in same WiFi network it would be something like http://192.168.0.26:3000

Troubleshooting:

• To find out MAC address for step 1 you can check logs of server: it will be attempts to connect
• If you see error wrong access-token value from device - you may need to click button Soft reset on device setup stage

BYOS Proxy

You can use both own server with own screen and some plugins from usetrmnl.com (aka core) by using Proxy mode. In this mode you will see your screen, one of screens from core after, and etc, one by one.

You can enable it with those steps:

1. Set BYOS_PROXY = true in Config
2. Repeat setup process for BYOS with doing soft reset
3. Check access-token received from usetrmnl.com and change ENV key BYOS_DEVICE_ACCESS_TOKEN to it

---

Goal of this repo: simple and easy to customize.