Terminus

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.

Table of Contents

Features
Screencasts
Requirements
Setup
Usage
- Configuration
- APIs
  - Display
  - Setup
  - Logs
  - Images
Development
- Console
- YJIT
- CSS
Tests
Deployment
Credits

Features

Allows you to run your own server.
Built atop Ruby and Hanami.
Provides automatic detection of your server’s IP address.
Uses PostgreSQL.
Uses Puma.
Uses htmx.
Supports YJIT.
Supports Overmind.
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	🟢	🟢
Plugins	⚪️	🟢
Playlists	🟡	🟢
Playlist Previews	⚪️	🟢
Recipes	🔴	🟢
Devices	🟢	🟢
Account	🔴	🟢
JSON Data API	🟢	🟢
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. 🎉

Screencasts

Requirements

Ruby.
PostgreSQL.
Hanami.
Overmind (optional).
Docker (optional).
A TRMNL device.

Setup

To set up project, run:

git clone https://github.com/usetrmnl/byos_hanami terminus
cd terminus
bin/setup

Usage

To launch the server, run:

bin/hanami assets compile
bundle exec puma --config ./config/puma.rb

💡 Install Overmind and run overmind start to run with full access to all processes (including remote debugging).

To view the app, use either of the following:

Secure: https://localhost:2443
Insecure: http://localhost:2300

Configuration

There are a few environment variables you can use to customize behavior:

API_URI: Needed for connecting your device to this server. Defaults to your wired IP address.
DATABASE_URL: Necessary to connect to your PostgreSQL database. Can be customized by changing the value in the .env.development or .env.test file created when you ran bin/setup.
GENERATED_ROOT: The root location for all generated images. Defaults to public/assets/generated.

APIs

The following APIs are supported. Each uses HTTPS which requires accepting your locally generated SSL certificate. If you don’t want this behavior, you can switch to using HTTP (see above).

Display

Used for displaying new content to your device. Your device’s refresh determines how often this occurs.

Request

Without Base64 Encryption

curl "https://localhost:2443/api/display/" \
     -H 'ID: <redacted>' \
     -H 'Access-Token: <redacted>' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json'

With Base64 Encryption via HTTP Header

curl "https://localhost:2443/api/display/" \
     -H 'ID: <redacted>' \
     -H 'Access-Token: <redacted>' \
     -H 'Accept: application/json' \
     -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 'Access-Token: <redacted>' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json'

Both the ID and Access-Token HTTP headers are required for all of these API calls but these optional headers can be supplied as well which mimics what each device includes each request:

HTTP_BATTERY_VOLTAGE: Must a a float (usually 0.0 to 4.1).
HTTP_FW_VERSION: The firmware version (i.e. 1.2.3).
HTTP_HOST: The host (usually the IP address).
HTTP_REFRESH_RATE: The refresh rate as saved on the device. Example: 100.
HTTP_RSSI: The signal strength (usually -100 to 100).
HTTP_USER_AGENT: The device name.
HTTP_WIDTH: The device width. Example: 800.
HTTP_HEIGHT: :The device height. Example: 480.

Response

Without Base64 Encryption

{
  "filename": "demo.bmp",
  "firmware_url": null,
  "image_url": "https://localhost:2443/assets/generated/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": null,
  "image_url": "data:image/bmp;base64,<truncated>",
  "image_url_timeout": 0,
  "refresh_rate": 200,
  "reset_firmware": false,
  "special_function": "sleep",
  "update_firmware": false
}

Setup

Uses for new device setup and then never used after.

Request

curl "https://localhost:2443/api/setup/" \
     -H 'ID: <redacted>' \
     -H 'Accept: application/json' \
     -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"
}

Logs

Uses for logging information about your server and/or device. Mostly used for debugging purposes.

Request

## Logs
curl -X "POST" "https://localhost:2443/api/log" \
     -H 'ID: <redacted>' \
     -H 'Access-Token: <redacted>' \
     -H 'Accept: application/json' \
     -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.4.7",
          "free_heap_size": 160656,
          "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.

Images

Used for generating new images by supplying HTML content for rendering, screenshotting, and grey scaling to render properly on your device.

Request

curl -X "POST" "https://localhost:2443/api/images" \
    -H 'ID: <redacted>' \
    -H 'Access-Token: <redacted>' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d $'{
 "image": {
   "content": "<p>Test</p>"
   "file_name": "test"
 }
}'

The ID header is your device’s MAC address. You can obtain this information from the UI.

Response

{
  "path": "$HOME/Engineering/terminus/public/assets/generated/test.bmp"
}

💡 The images API supports full HTML 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 images:

* {
  margin: 0;
}

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/generated.

💡 The ID is your device’s MAC and the Access-Token is your device API Key.

Development

To contribute, run:

git clone https://github.com/usetrmnl/terminus
cd terminus
bin/setup

Console

To access the console with direct access to all objects, run:

bin/console

Once in the console, you can do the following:

# Use a repository.
repository = Hanami.app["repositories.device"]

repository.all     # View all devices.
repository.find 1  # Find by Device ID.

# Fetch next image. Sorts in descending order by created timestamp.
fetcher = Hanami.app["aspects.images.fetcher"]
fetcher.call images_uri: "https://localhost:2443/assets"

# To generate image with random name.
creator = Terminus::Images::Creator.new
creator.call "<p>Test</p>",
             Pathname(Hanami.app[:settings].generated_root).join("%<name>s.bmp")
#<Pathname:terminus/public/assets/generated/f5af3f06-775f-4ae9-8bb1-246d9a5200c9.bmp>

# To generate image with specific name.
creator.call "<p>Test.</p>", Pathname(Hanami.app[:settings].generated_root).join("demo.bmp")
#<Pathname:terminus/public/assets/generated/demo.bmp>

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 Images::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:

Image Generation

creator = Terminus::Images::Creator.new

creator.call(<<~CONTENT, Pathname(Hanami.app[:settings].generated_root).join("generated/%<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>
CONTENT

The above will create a new image in the public/generated folder of this application which will eventually render on your device. 🎉

To build a Docker image, run:

bin/docker/build

To work within your Docker image, run:

bin/docker/console

YJIT

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".

CSS

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:

Colors: Use to customize site colors.
Defaults: Use to customize HTML element defaults.
Settings: Use to customize site settings.
Layout: Use to customize the site layout.
Components: Use to customize general site components.
View Transitions: Use to customize view transitions.
Dashboard: Use to customize the dashboard page.
Devices: Use to customize the devices page.

For responsive resolutions, the following measurements are used:

Extra Small: 300px
Small: 500px
Medium: 825px
Large: 1000px
Extra Large: 1500px

Tests

To test, run:

bin/rake

Deployment

More details to be provided soon.

Credits

Built with Hanamismith.
Engineered by TRMNL.

Name		Name	Last commit message	Last commit date
Latest commit History 218 Commits
.circleci		.circleci
.config		.config
.devcontainer		.devcontainer
.github		.github
app		app
bin		bin
config		config
lib/terminus		lib/terminus
public		public
slices/health		slices/health
spec		spec
.dockerignore		.dockerignore
.gitignore		.gitignore
.node-version		.node-version
.reek.yml		.reek.yml
.ruby-version		.ruby-version
Dockerfile		Dockerfile
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE.adoc		LICENSE.adoc
Procfile		Procfile
README.adoc		README.adoc
Rakefile		Rakefile
config.ru		config.ru
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Terminus

Features

Screencasts

Requirements

Setup

Usage

Configuration

APIs

Display

Setup

Logs

Images

Development

Console

YJIT

CSS

Tests

Deployment

Credits

About

Releases

Languages

License

usetrmnl/byos_hanami

Folders and files

Latest commit

History

Repository files navigation

Terminus

Features

Screencasts

Requirements

Setup

Usage

Configuration

APIs

Display

Setup

Logs

Images

Development

Console

YJIT

CSS

Tests

Deployment

Credits

About

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Releases

Languages