This is a Ruby/Hanami project that allows you to point a TRMNL device to your own server which can be running on your local network or in the cloud. This is also the flagship implementation officially supported by TRMNL.
-
Allows you to run your own server.
-
Provides automatic detection of your server’s IP address.
-
Uses htmx.
-
Uses ImageMagick.
-
Uses Overmind.
-
Uses PostgreSQL.
-
Uses Puma.
-
Supports YJIT.
-
Supports Docker.
-
Supports TRMNL devices.
The following is a high level overview you can use to compare/contrast when deciding between using this Build Your Own Server (BYOS) implementation or our hosted solution.
Legend
-
⚪️ Planned.
-
🟢 Supported.
-
🟡 Partially supported.
-
🔴 Not supported, not implemented, or isn’t applicable.
Matrix
| Terminus | Hosted | |
|---|---|---|
Dashboard |
🟢 |
🟢 |
Auto-Provisioning |
🟢 |
🟢 |
Devices |
🟢 |
🟢 |
JSON Data API |
🟢 |
🟢 |
Image Previews |
🟢 |
🟢 |
Playlists |
🟡 |
🟢 |
Plugins |
🟢 |
🟢 |
Recipes |
🟢 |
🟢 |
Account |
đź”´ |
🟢 |
Open Source Components |
🟢 |
🟡 |
Docker |
🟢 |
đź”´ |
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. 🎉
To set up this project, run:
git clone https://github.com/usetrmnl/byos_hanami terminus
cd terminus
bin/setupđź’ˇ The setup script is idempotent so you can run it multiple times without harm. To rebuild a file managed by the setup script, delete the desired file and rerun setup to recreate.
To launch the server, run:
# Development
overmind start --port-step 10 --procfile Procfile.dev --can-die assets,migrate
# Production
overmind start --port-step 10 --can-die assets,migrateTo view the app, use either of the following:
-
Secure: https://localhost:2443
-
Insecure: http://localhost:2300
There are a few environment variables you can use to customize behavior:
-
API_URI: Used for connecting your device to this server or via Docker. Defaults to the wired IP address and port of the server you are running Terminus on. This also assumes you are connecting your device directly to the same server Terminus is running on. If this is not the case and you are using a reverse proxy, DNS, or any service/layer between your device and Terminus then you need to update this value to be your host. For example, if your host ishttp://demo.iothen this value must behttp://demo.io. This includes updating your device, via the TRMNL captive Wifi portal, to be usinghttp://demo.ioas your custom host too. How you configurehttp://demo.ioto resolve to the server you are running Terminus on is up to you. All your device (and this value) cares about is what the external host (or IP and port) is for the device to make API requests too (they must be identical). -
DATABASE_URL: Necessary to connect to your PostgreSQL database. Can be customized by changing the value in the.env.developmentor.env.testfile created when you ranbin/setup. -
HANAMI_PORT: The default port when running the app locally or via Docker. When using Docker, this is used for the internal and external port mapping. -
PREVIEWS_ROOT: The root location for all device screen preview images when designing new screens. Default:public/assets/previews. -
RACK_ATTACK_ALLOWED_SUBNETS: Defines the Rack Attack subnets that are allowed to connect to this server which helps when adding DNS, a reverse proxy, or a VPN, etc. between your device and this application so you can use this environment variable to add more subnets as desired. This takes a single subnet/IP or an array — with no spaces — of subnets/IPs as values. Example: "111.111.111.111,150.120.0.0/16". Alternatively, you can disable Rack Attack altogether by removing theconfig.middleware.use Rack::Attackline fromconfig/app.rbor customize Rack Attack via theconfig/initializers/rack_attack.rbfile. Any of these approaches will allow you to get your service layer properly configured so your device can talk to this server. By default, the following subnets are allowed:10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.1, and::1. -
SCREENS_ROOT: The root location for all device screens (images). Default:public/assets/screens. -
PG_DATABASE: Defines your database name. Used by Docker only. Default:terminus. -
PG_PASSWORD: Defines your database password. Used by Docker only. Default: (auto-generated for you during setup). -
PG_PORT: Defines your database port. Used by Docker only. Default:5432. -
PG_USER: Defines your database user. Used by Docker only. Default:terminus.
There are a couple of ways you can provision a device with this server.
The first is automatic which happens immediately after you have successfully used the WiFi captive portal on your mobile phone to connect your TRMNL device to your local network where this server is running. You can also delete your device, via the UI, and it’ll be reconfigured for you automatically when the device next makes a Display API request.
The second way is to manually add your device via the UI. At a minimum, you only need to know your device’s MAC Address when entering your device information within the UI.
There are two background pollers that cache data from the remote Core server for improved performance:
-
Firmware (
bin/pollers/firmware): Downloads the latest firmware for updating your local devices. By default, this checks for updates every six hours. -
Screen (
bin/pollers/screen): Downloads device screens for any device you have set up to proxy to the Core server. You only need to toggle proxy support for any/all devices you want to pull from Core. This allows you to leverage any/all recipes/plugins you have configured via your remote account. By default, this checks for updates every five minutes.
All pollers can be configured to use different polling intervals by supplying the desired seconds in which to poll. You can do this by modifying each script. Example:
# bin/pollers/firmware
poller.call seconds: 60
# bin/pollers/screen
poller.call seconds: 30Each automatically run in the background as separate processes in both the Procfile and Procfile.dev files. The latter is built for you when running bin/setup.
When using Overmind, you can restart these pollers (as with any process managed by Overmind) as follows:
overmind restart firmware_poller
overmind restart screen_pollerThis can be handy if you want to force either of these poller’s to check for new content.
To disable any of the pollers, remove them from the Procfile.dev and/or Procfile files. For example, delete these lines:
firmware_poller: bin/pollers/firmware screen_poller: bin/pollers/screen
You could also configure them to have a massive number of seconds as mentioned above when supplying custom seconds in which to poll.
By default, the Firmware Poller will automatically download the latest firmware but you’ll need to enable firmware updates for your device to have each new firmware release automatically applied. You can do this by editing your device and clicking the Firmware Update checkbox to enable. Otherwise, newer firmware versions will be cached on the server but your device won’t update.
In situations where your device updated to a newer Firmware version and it was a bad/broken version, you can revert to and older version by following these steps:
-
Ensure the device you want to downgrade has firmware updates turned on (you’ll also want to ensure devices you don’t want to downgrade have this setting turned off).
-
Visit the Firmwares page within the UI.
-
Delete all latest versions until you only have the version you want to downgrade to listed at the top of the list.
-
Short click the button on the back of your device to force a refresh and wait for the firmware downgrade to complete.
-
That’s it!
Each API endpoint uses HTTPS which requires accepting the locally generated SSL certificate by this application when running the Ruby stack locally. If you don’t want this behavior, you can switch to using HTTP (see above). For Docker, at the moment, none of this applies so can only use HTTP requests.
See each category/endpoint, below, for further details.
The following endpoints are used to communicate with your device’s TRMNL Firmware. These endpoints typically require authentication via the HTTP ID header which is your device’s MAC address. Any changes to these endpoints require updates to both the firmware and this implementation so they don’t change often.
Used for displaying new content to your device. Your device’s refresh rate determines how often this occurs.
Request
Without Base64 Encryption
curl "https://localhost:2443/api/display" \
-H 'ID: <redacted>' \
-H 'Content-Type: application/json'With Base64 Encryption via HTTP Header
curl "https://localhost:2443/api/display" \
-H 'ID: <redacted>' \
-H 'Content-Type: application/json' \
-H 'BASE64: true'With Base64 Encryption via Parameter
curl "https://localhost:2443/api/display?base_64=true" \
-H 'ID: <redacted>' \
-H 'Content-Type: application/json'Only the ID HTTP header is required for all of these API calls but these optional headers can be supplied as well which mimics what each device includes each request:
-
ACCESS_TOKEN: Can be the API key or an empty string. -
BATTERY_VOLTAGE: Must a a float (usually 0.0 to 4.1). -
FW_VERSION: The firmware version (i.e.1.2.3). -
HOST: The host (usually the IP address). -
REFRESH_RATE: The refresh rate as saved on the device. Example: 100. -
RSSI: The signal strength (usually -100 to 100). -
USER_AGENT: The device name. -
WIDTH: The device width. Example: 800. -
HEIGHT: :The device height. Example: 480.
Response
Without Base64 Encryption
{
"filename": "demo.bmp",
"firmware_url": "http://localhost:2443/assets/firmware/1.4.8.bin",
"image_url": "https://localhost:2443/assets/screens/A1B2C3D4E5F6/demo.bmp",
"image_url_timeout": 0,
"refresh_rate": 130,
"reset_firmware": false,
"special_function": "sleep",
"update_firmware": false
}With Base64 Encryption
{
"filename": "demo.bmp",
"firmware_url": "http://localhost:2443/assets/firmware/1.4.8.bin",
"image_url": "data:image/bmp;base64,<truncated>",
"image_url_timeout": 0,
"refresh_rate": 200,
"reset_firmware": false,
"special_function": "sleep",
"update_firmware": false
}Used by device firmware to log information about your device. Mostly used for debugging purposes. You can find device specific logs within the UI by clicking on your device logs.
Request
curl -X "POST" "https://localhost:2443/api/log" \
-H 'ID: <redacted>' \
-H 'Content-Type: application/json' \
-d $'{
"log": {
"logs_array": [
{
"log_id": 1,
"creation_timestamp": 1742022123,
"log_message": "returned code is not OK: 404",
"log_codeline": 597,
"device_status_stamp": {
"wifi_status": "connected",
"wakeup_reason": "timer",
"current_fw_version": "1.5.2",
"free_heap_size": 160656,
"max_alloc_size": 200000,
"special_function": "none",
"refresh_rate": 30,
"battery_voltage": 4.772,
"time_since_last_sleep_start": 31,
"wifi_rssi_level": -54
},
"additional_info": {
"retry_attempt": 1
},
"log_sourcefile": "src/bl.cpp"
}
]
}
}'Response
Logs details and answers a HTTP 204 status with no content.
Used for new device setup and then never used after.
Request
curl "https://localhost:2443/api/setup/" \
-H 'ID: <redacted>' \
-H 'Content-Type: application/json'Response
{
"api_key": "<redacted>",
"friendly_id": "ABC123",
"image_url": "https://localhost:2443/assets/setup.bmp",
"message": "Welcome to TRMNL BYOS"
}The following endpoints are unique to this server implementation and allow you to interact via your favorite JSON Data API client. Most of these endpoints require an HTTP Access-Token header which is your device’s API key.
These endpoints are faster to change/update since they won’t break any communication with your device. Any/all error responses adhere to RFC 9457 (Problem Details for HTTP APIs) as implemented by the Petail gem which also means you can use Petail to easily parse the error responses in your own application if desired.
Lastly, these endpoints are constantly evolving and not entirely stable as of yet.
Allows you to manage your devices.
GET Request
# All devices.
curl "https://localhost:2443/api/devices" \
-H 'Content-Type: application/json'
# Single device.
curl "https://localhost:2443/api/devices/1" \
-H 'Content-Type: application/json'GET Response
# All devices.
{
"data": [
{
"id": 9,
"model_id": 1,
"playlist_id": null,
"friendly_id": "DEMO11",
"label": "Demo",
"mac_address": "A1:B2:C3:D4:E5:F6",
"api_key": "OScdcN0kFbKjFcid9Kz6Cx",
"firmware_version": null,
"firmware_beta": false,
"wifi": 0,
"battery": 0.0,
"refresh_rate": 500,
"image_timeout": 0,
"width": 0,
"height": 0,
"proxy": true,
"firmware_update": true,
"sleep_start_at": "23:00:00",
"sleep_stop_at": "06:00:00",
"created_at": "2025-06-29T19:11:48+0000",
"updated_at": "2025-06-29T19:11:48+0000"
}
]
}
# Single device.
{
"data": {
"id": 9,
"model_id": 1,
"playlist_id": null,
"friendly_id": "DEMO11",
"label": "Demo",
"mac_address": "A1:B2:C3:D4:E5:F6",
"api_key": "OScdcN0kFbKjFcid9Kz6Cx",
"firmware_version": null,
"firmware_beta": false,
"wifi": 0,
"battery": 0.0,
"refresh_rate": 500,
"image_timeout": 0,
"width": 0,
"height": 0,
"proxy": true,
"firmware_update": true,
"sleep_start_at": "23:00:00",
"sleep_stop_at": "06:00:00",
"created_at": "2025-06-29T19:11:48+0000",
"updated_at": "2025-06-29T19:11:48+0000"
}
}You’ll get an empty array when no devices exist.
POST Request
# Minimum
curl -X "POST" "https://localhost:2443/api/devices" \
-H 'Content-Type: application/json' \
-d $'{
"device": {
"label": "Demo",
"model_id": 1,
"mac_address": "A1:B2:C3:D4:E5:F6"
}
}'# Maximum (all possible fields)
curl -X "POST" "https://localhost:2443/api/devices" \
-H 'Content-Type: application/json' \
-d $'{
"device": {
"model_id": 1,
"playlist_id": null,
"label": "Demo",
"friendly_id": "DEMO11",
"mac_address": "A1:B2:C3:D4:E5:F6",
"api_key": "OScdcN0kFbKjFcid9Kz6Cx",
"refresh_rate": "500",
"image_timeout": "0",
"firmware_beta": false,
"firmware_update": true,
"proxy": true,
"sleep_start_at": "23:00:00",
"sleep_stop_at": "06:00:00"
}
}'POST Response
{
"data": {
"id": 9,
"model_id": 1,
"playlist_id": null,
"friendly_id": "DEMO11",
"label": "Demo",
"mac_address": "A1:B2:C3:D4:E5:F6",
"api_key": "OScdcN0kFbKjFcid9Kz6Cx",
"firmware_version": null,
"firmware_beta": false,
"wifi": 0,
"battery": 0.0,
"refresh_rate": 500,
"image_timeout": 0,
"width": 0,
"height": 0,
"proxy": true,
"firmware_update": true,
"sleep_start_at": "23:00:00",
"sleep_stop_at": "06:00:00"
"created_at": "2025-06-29T19:11:48+0000",
"updated_at": "2025-06-29T19:11:48+0000"
}
}PATCH Request
## Devices (patch)
curl -X "PATCH" "https://localhost:2443/api/devices/9" \
-H 'Content-Type: application/json' \
-H 'Cookie: BetterErrors-2.10.1-CSRF-Token=1e937fde-9d7f-43e5-b164-c29e328969f5' \
-d $'{
"device": {
"refresh_rate": 250
}
}'You you change a single attribute or multiple attributes at once.
PATCH Response
{
"data": {
"id": 9,
"model_id": 1,
"playlist_id": null,
"friendly_id": "DEMO11",
"label": "Demo",
"mac_address": "A1:B2:C3:D4:E5:F6",
"api_key": "OScdcN0kFbKjFcid9Kz6Cx",
"firmware_version": null,
"firmware_beta": false,
"wifi": 0,
"battery": 0.0,
"refresh_rate": 250,
"image_timeout": 0,
"width": 0,
"height": 0,
"proxy": false,
"firmware_update": false,
"sleep_start_at": "23:00:00",
"sleep_stop_at": "06:00:00"
"created_at": "2025-06-29T19:11:48+0000",
"updated_at": "2025-06-29T19:11:48+0000"
}
}DELETE Request
## Devices (delete)
curl -X "DELETE" "https://localhost:2443/api/devices/9" \
-H 'Content-Type: application/json' \
-d $'{}'DELETE Response
{
"data": {
"id": 9,
"model_id": 1,
"playlist_id": null,
"friendly_id": "DEMO11",
"label": "Demo",
"mac_address": "A1:B2:C3:D4:E5:F6",
"api_key": "OScdcN0kFbKjFcid9Kz6Cx",
"firmware_version": null,
"firmware_beta": false,
"wifi": 0,
"battery": 0.0,
"refresh_rate": 250,
"image_timeout": 0,
"width": 0,
"height": 0,
"proxy": false,
"firmware_update": false,
"sleep_start_at": "23:00:00",
"sleep_stop_at": "06:00:00"
"created_at": "2025-06-29T19:11:48+0000",
"updated_at": "2025-06-29T19:11:48+0000"
}
}You’ll get an empty hash when there is nothing to delete.
Provides details about the various TRMNL models in production. This information will soon be associated with device and screen management.
GET Request
# All models.
curl "https://localhost:2443/api/models" \
-H 'Content-Type: application/json'
# Single model.
curl "https://localhost:2443/api/models/1" \
-H 'Content-Type: application/json'GET Response
# All models.
{
"data": [
{
"id": 1,
"name": "t1",
"label": "T1",
"description": "The first production model.",
"width": 800,
"height": 480,
"published_at": "2024-06-25T00:00:00+0000"
}
]
}
# Single model.
{
"data": {
"id": 1,
"name": "t1",
"label": "T1",
"description": "The first production model.",
"width": 800,
"height": 480,
"published_at": "2024-06-25T00:00:00+0000"
}
}You’ll get an empty array when no models exist.
POST Request
curl -X "POST" "https://localhost:2443/api/models" \
-H 'Content-Type: application/json' \
-d $'{
"model": {
"name": "demo",
"label": "Demo",
"description": "A demonstration.",
"width": "800",
"height": "480",
"published_at": "2025-01-01T00:00:00+00:00"
}
}'POST Response
{
"data": {
"id": 3,
"name": "demo",
"label": "Demo",
"description": "A demonstration.",
"width": 800,
"height": 480,
"published_at": "2025-01-01T00:00:00+00:00"
}
}PATCH Request
curl -X "PUT" "https://localhost:2443/api/models/3" \
-H 'Content-Type: application/json' \
-d $'{
"model": {
"description": "A patch demonstration."
}
}'You you change a single attribute or multiple attributes at once.
PATCH Response
{
"data": {
"id": 3,
"name": "demo",
"label": "Demo",
"description": "A patch demonstration.",
"width": 800,
"height": 480,
"published_at": "2025-01-01T00:00:00+00:00"
}
}DELETE Request
curl -X "DELETE" "https://localhost:2443/api/models/3" \
-H 'Content-Type: application/json' \
-d $'{}'DELETE Response
{
"data": {
"id": 3,
"name": "demo",
"label": "Demo",
"description": "A delete demonstration.",
"width": 800,
"height": 480,
"published_at": "2025-01-01T00:00:00+00:00"
}
}You’ll get an empty hash when there is nothing to delete.
Used for generating new device screens by supplying HTML content for rendering, screenshotting, and grey scaling to render properly on your device. Both .png or .bmp extensions are supported for the file_name key. If you don’t supply a file_name, the server will generate one for you using a UUID for the file name. You can find all generated images in public/assets/screens.
When making requests, the Access-Token is your device’s API key. You can obtain this information from within the UI for your specific device.
Request (HTML Content)
curl -X "POST" "https://localhost:2443/api/screens" \
-H 'Access-Token: <redacted>' \
-H 'Content-Type: application/json' \
-d $'{
"image": {
"content": "<p>Test</p>",
"file_name": "demo.png"
}
}'Allows you to render custom HTML content as an image on your device. Full HTML is supported so you can supply CSS styles, full DOM, etc. At a minimum, you’ll want to use the following to prevent white borders showing up around your generated screens:
* {
margin: 0;
}Due to this being so flexible, this also means you can pull in and use our Design Framework when building custom screens by linking to the following:
-
Plugins
-
Components
đź’ˇ You can use the Designer within the UI to build custom screens in real-time for faster feedback. The result of your work can be supplied to this endpoint to create a new screen for display on your device.
Request (Preprocessed URI)
curl -X "POST" "https://localhost:2443/api/screens" \
-H 'Access-Token: <redacted>' \
-H 'Content-Type: application/json' \
-d $'{
"image": {
"uri": "https://demo.io/your_preprocessed_image.png",
"file_name": "demo.png",
"preprocessed": true
}
}'Allows you to render a preprocessed image — by you — on your device. The preprocessed value must be true when supplied. This assumes the URI you want have rendered on your device is fully compatible with the device in terms of greyscale, bit depth, color depth, and so forth. We do not process this image and only cache the image locally for display on your device. I you want want your image processed then see the Unprocessed URI API Request example.
Request (Unprocessed URI)
curl -X "POST" "https://localhost:2443/api/screens" \
-H 'Access-Token: <redacted>' \
-H 'Content-Type: application/json' \
-d $'{
"image": {
"uri": "https://git-scm.com/images/logos/downloads/Git-Icon-1788C.png",
"file_name": "demo.png",
"dimensions": "800x480!"
}
}'Allows you to render a unprocessed image on your device. We’ll automatically process the image for rendering on your device. The dimensions parameter is optional and defaults to 800x480 when not supplied. You can use the full ImageMagick Geometry syntax as the value.
Request (Base64 Encoded Data)
curl -X "POST" "https://localhost:2443/api/screens" \
-H 'Access-Token: <redacted>' \
-H 'Content-Type: application/json' \
-d $'{
"image": {
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAAXNSR0IArs4c6QAAAAtJREFUCFtjYGAAAAADAAHc7H1IAAAAAElFTkSuQmCC"
"file_name": "demo.png",
"dimensions": "800x480!"
}
}'Allows you to render a strictly Base64 encoded image on your device. The dimensions parameter is optional and defaults to 800x480 when not supplied. You can use the full ImageMagick Geometry syntax as the value.
Response
{
"data": {
"path": "$HOME/Engineering/terminus/public/assets/screens/A1B2C3D4E5F6/demo.png"
}
}No matter what parameters you use for this request, you’ll always get a path (unless an error is encountered).
To contribute, run:
git clone https://github.com/usetrmnl/byos_hanami terminus
cd terminus
bin/setupTo access the console with direct access to all objects, run:
bin/consoleOnce in the console, you can interact with all objects. A few examples:
# Use a repository.
repository = Hanami.app["repositories.device"]
repository.all # View all devices.
device = repository.find 1 # Find by Device ID.
# Fetch next device screen. Sorts in descending order by modified timestamp.
fetcher = Hanami.app["aspects.screens.fetcher"]
fetcher.call device.slugShould you want to create screens from the command line/console instead of using the Designer (UI) or Screens API, you can use the Creator. Please be aware of the following:
-
The output path must include your device’s MAC Address in collapsed form (i.e. colons removed). Example:
"A1B2C3D4E5F6". -
Use
.bmpor.pngas the file extension. This ensures your image is generated in the correct MIME Type and desired format. -
Use
%<name>sin your output path to generate a random name. This must included a supported file extension. Example:%<name>s.png. -
The
imageparameters used in the Screens API — exceptfile_name — are identical to the keyword arguments when calling this object. -
When using
urianddatakeys, you’ll need to supply dimensions which leverage the full ImageMagick Geometry syntax.
Here are a few examples:
HTML content with random name
creator = Terminus::Screens::Creator.new
output_path = Pathname(Hanami.app[:settings].screens_root).join("A1B2C3D4E5F6/%<name>s.png")
creator.call output_path, content: "<p>Test</p>"
# Success(
# #<Pathname:terminus/public/assets/screens/A1B2C3D4E5F6/31a55181-ef94-4397-89d9-bd576d89b404.png>
# )HTML content with specific name
creator = Terminus::Screens::Creator.new
output_path = Pathname(Hanami.app[:settings].screens_root).join("A1B2C3D4E5F6/demo.png")
creator.call output_path, content: "<p>Test</p>"
# Success(
# #<Pathname:terminus/public/assets/screens/A1B2C3D4E5F6/demo.png>
# )URI
creator = Terminus::Screens::Creator.new
output_path = Pathname(Hanami.app[:settings].screens_root).join("A1B2C3D4E5F6/demo.png")
creator.call output_path,
uri: "https://leonardo.ai/wp-content/uploads/2023/07/image-129.jpeg",
dimensions: "800x480"
# Success(
# #<Pathname:terminus/public/assets/screens/A1B2C3D4E5F6/demo.png>
# )Data (Base64)
creator = Terminus::Screens::Creator.new
output_path = Pathname(Hanami.app[:settings].screens_root).join("A1B2C3D4E5F6/demo.png")
creator.call output_path,
data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAAXNSR0IArs4c6QAAAAtJREFUCFtjYGAAAAADAAHc7H1IAAAAAElFTkSuQmCC",
dimensions: "800x480!"
# Success(
# #<Pathname:terminus/public/assets/screens/A1B2C3D4E5F6/demo.png>
# )When creating images, you might find this HTML template valuable as a starting point as this let’s you use the full capabilities of HTML to create new images for your device.
HTML Template
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no">
<title>Demo</title>
<meta charset="utf-8">
<style type="text/css">
* {
margin: 0;
}
</style>
<script type="text/javascript">
</script>
</head>
<body>
<img src="uri/to/image" alt="Image"/>
</body>
</html>Use of margin zero is important to prevent default browser styles from creating borders around your image which will show up when rendered on your device. Otherwise, you have full capabilities to render any kind of page you want using whatever HTML you like. Anything is possible because Terminus::Screens::Creator is designed to screenshot your rendered HTML as a 800x480 image to render on your device. If you put all this together, that means you can do this in the console:
Screen Creation
creator = Terminus::Screens::Creator.new
creator.call(<<~CONTENT, Pathname(Hanami.app[:settings].screens_root).join("A1B2C3D4E5F6/%<name>s.bmp"))
<!DOCTYPE html>
<html lang="en">
<head>
<meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no">
<title>Demo</title>
<meta charset="utf-8">
<style type="text/css">
* {
margin: 0;
}
</style>
<script type="text/javascript">
</script>
</head>
<body>
<h1>Hello, World!</h1>
</body>
</html>
CONTENTThe above will create a new image in the public/screens folder of this application which will eventually render on your device. 🎉
YJIT is enabled by default if detected which means you have built and installed Ruby with YJIT enabled. If you didn’t build Ruby with YJIT support, YJIT support will be ignored. That said, we recommend you enable YJIT support since the performance improvements are worth it.
đź’ˇ To enable YJIT globally, ensure the --yjit flag is added to your RUBYOPT environment variable. Example: export RUBYOPT="--yjit".
Pure CSS is used in order to avoid pulling in complicated frameworks. The following stylesheets allow you to customize the look and feel of this application as follows:
-
Settings: Use to customize site settings.
-
Colors: Use to customize site colors.
-
Keyframes: Use to customize keyframe behavior.
-
View Transitions: Use to customize view transitions.
-
Defaults: Use to customize HTML element defaults.
-
Layout: Use to customize the site layout.
-
Components: Use to customize general site components.
-
Dashboard: Use to customize the dashboard page.
-
Devices: Use to customize the devices page.
-
Designer: Use to customize the designer page.
For responsive resolutions, the following measurements are used:
-
Extra Small: 300px
-
Small: 500px
-
Medium: 825px
-
Large: 1000px
-
Extra Large: 1500px
The Santize gem is used to sanitize HTML/CSS when using the console, API, or UI. All of this configured via the Terminus::Sanitizer class which defaults to the Sanitize::Config::RELAXED style with additional support for style and source elements. If you find elements being stripped from your HTML/CSS content, this is why. Feel free to open an issue if you need additional support.
By default, all logging is set to INFO level but you can get more verbose information by using the DEBUG level. There are multiple ways to do this. First, you can export the desired debug level:
export LOG_LEVEL=debugYou can also specify the log level before launching the server:
LOG_LEVEL=debug overmind start --port-step 10 --procfile Procfile.dev --can-die assets,migrateFinally, you can configure the app to use a different log level via lib/terminus/lib_container.rb by adjusting log level of logger during registration:
register(:logger) { Cogger.new id: :terminus, level: :debug, formatter: :detail }đź’ˇ See the Cogger gem documentation for further details.
SimpleCov code coverage reports are generated with every Circle CI build. The badge at the top of this document isn’t updated in real-time, unfortunately, but fairly accurate since this project is configured to strive for 100% code coverage.
To view up-to-date details, follow these steps:
-
Visit the Circle CI build page.
-
Click on the latest "Success" build at the top of the page.
-
Click on
build. -
Click on ARTIFACTS.
-
Click on the
coverage/index.htmlfile.
At this point you can click through the tabs at the top of the page to inspect the various namespaces that make up this application.
Docker is supported both for production and development purposes. In most cases, you’ll want to use Docker Compose to manage the stack. Read on to learn more.
You can use Docker Compose to quickly launch the entire stack for development or production environments.
To start, you’ll want to customize your API_URI environment variable so the URI points to the server from where you are running the full stack. This is important because the API IP address shown via the Dashboard page will only show the URI of your Docker image/container which devices can’t connect to. You can fix by adding updating your HANAMI_PORT and API_URI in the environment section. Here’s a few examples:
# With specific IP address.
environment:
HANAMI_PORT=2300
API_URI: http://192.168.1.1:$HANAMI_PORT
# With hostname.
environment:
API_URI: https://terminus.demo.ioYou can also confirm the above changes are applied by running docker-compose up and viewing the Dashboard (look for the API IP address).
Further details can be found in the compose.yml or compose.dev.yml files at the root of this project.
To develop with Docker, you can use the following scripts:
-
bin/docker/up: Use to start up all services via Docker Compose. -
bin/docker/down: Use to shut down all services via Docker Compose. -
bin/docker/compose: Use to run any Docker Compose command. -
bin/docker/entrypoint-dev: Used bycompose.dev.ymlto ensure the web service is setup properly.
The following commands can be helpful when managing the stack locally:
-
docker-compose up: Builds and launches the entire stack. -
docker-compose build web: Rebuilds the web service. You’ll want to run this before runningupin order to pick up the latest changes whenever there is a new version release or pulling changes from themainbranch. -
docker-compose exec web bash: This’ll give you a Bash shell within root of the project. Usebin/consoleto launch a Hanami console. -
docker logs terminus-web-1: Use this to view the web service logs.
If you only care about the web image, then you can use the Dockerfile and bin/docker scripts. Here’s how each works:
-
bin/docker/build: This will build a production Docker image based on latest changes to this project. -
bin/docker/console: This will immediately give you a console for which to explore you Docker image from the command line. -
bin/docker/entrypoint: This is used by theDockerfilewhen building your Docker image.
If you don’t care about using Docker or Docker Compose locally, then you can use the prebuilt image since an image is built each time changes are applied to the main branch or a new tag is created. All images can be found in the Container Registry. Use as follows:
# Latest
docker pull ghcr.io/usetrmnl/terminus:latest
# Specific version.
docker pull ghcr.io/usetrmnl/terminus:<version>You can also update compose.yml to use the above image by replacing the following (should you not want to manually build the image):
build:
context: .…​with:
image: ghcr.io/usetrmnl/terminus:latestOnce this server is up and running, you’ll want to connect your TRMNL device(s). The following guides will help you get started but are written for connecting to our Core server, not this server. When the docs say to Connect, make sure you fill in the API Server details (i.e. the API_URI as mentioned in the Configuration section) before connecting.
-
When switching servers, you’ll need to reset the device to connect to the new server. Do this by pressing and holding the button the back of the device for five seconds and then releasing to cause the device to reconnect. Once you connect to the TRMNL Captive Portal, click on the Soft Reset button to force the device to reset. Once reset, connect to the TRMNL Captive Portal one last time to fill in your API Server details and then click the Connect button to finally connect to your server.
The following is additional tooling, developed by the Open Source community, that might be of interest for use with this application:
-
Terminus Publisher: Provides a way to generate and publish content to Terminus for display on your device.
While this project is distributed under the permissive MIT License, we strongly believe that technology should serve humanity’s best interests. We created this software with the intent that it be used to benefit people and communities, not to cause harm. We encourage individuals and organizations to consider the ethical implications and to use this project in ways that respect human rights, promote equity, and contribute positively to society. Though we cannot legally restrict usage under the MIT License, we ask that you join us in fostering a responsible technology ecosystem by avoiding applications that could cause harm, perpetuate discrimination, or undermine human dignity. Technology is best used to enrich lives, let’s ensure we build a better world together!
-
Built with Hanamismith.
-
Engineered by TRMNL.