Create custom screen on your e-ink TRMNL device just like website: collect data with JavaScript and design layout with JSX(React) or HTML with Liquid templates.
This repository is starter for Node.js server, that generates an image that you can use via Redirect or Alias plugins, or run it as own BYOS.
- Creating screens with JSX or HTML (Liquid)
- Design Framework from TRMNL
- Generating screen (image) with preview
- JSON Data API
- BYOS (auto-provisioning, screens, device logs)
- Migrating any Plugin (they are in Liquid)
- Playlists (set of screens)
- Proxying screens (plugins) from Core
- Docker
- no database required (everything in ENV and Config)
- no dashboard
- Press button
Use this templateon Github, or clone this repository - Copy .env.example to .env.local and change values to yours
- (optional) setup local Node.js and NPM, for example via nvm
- Run
npm run watch - See preview of the screen in browser http://127.0.0.1:3000/image?secret_key=...
Or run it via Docker:
docker build --no-cache -t trmnl . && docker run --env-file .env.local -p 3000:3000 trmnlAfter 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.
- 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
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
For BYOS work routes are:
/api/setup - auto-provisioning of new device
/api/display - JSON with link to Image endpoint
/api/log - receiving logs and displayind them app logs (stdout)
For putting variables into HTML we use Liquid templating library (same as TRMNL).
Its a great option for moving custom plugins from usetrmnl.com to your own server.
Liquid files are in src/Template directory with .liquid extension. Most of their contents is regular HTML.
Liquid 101 article from TRMNL.
See example here
- You can use regular JSX components (similar to React), but without hooks, as screen is rendering only once
- Starting point is App.tsx
After choosing between Liquid and JSX, you can disable another in Screen.ts
You have full support of JavaScript and CSS, so you can use Framework by TRMNL:
<html>
<head>
<link rel="stylesheet" href="https://usetrmnl.com/css/latest/plugins.css">
<script src="https://usetrmnl.com/js/latest/plugins.js"></script>
</head>
<body class="environment trmnl">
<div class="screen">
...
</div>See Header for adding styles, fonts, etc and screen (plugin) example HackerNews.liquid
You use any static files in folder assets - at moment of screen rendering they will be matched with relative links in HTML, that started with '/assets/...'
Example:
<img src='/assets/images/wallpaper.jpeg'/>It's easier to collect all variables and data in one place, before using it in templates.
You can collect it in any methods or files and assemble results in in PrepareData.ts.
Example: getting HackerNews posts.
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
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:
- Set
BYOS_ENABLED = truein Config - 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.
- Generate or use usetrmnl.com access token in ENV key BYOS_DEVICE_ACCESS_TOKEN
- Hold round button on your device for more than 5 seconds - you should see connection instructions on screen.
- Connect your phone to wifi called
TRMNL - 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:
- If you see
[404] GET /api/displayin logs - then you might forgot to enable BYOS in Config - If you see
Failed to check image- maybe you forgot to changePUBLIC_URL_ORIGINin ENV - 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 buttonSoft reseton device setup stage
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:
- Set
BYOS_PROXY = truein Config - Repeat setup process for
BYOSwith doingsoft reset - Check
access-tokenreceived from usetrmnl.com and change ENV key BYOS_DEVICE_ACCESS_TOKEN to it
See CONTRIBUTING.md
