Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/usetrmnl/byos_hanami

A TRMNL BYOS application.
https://github.com/usetrmnl/byos_hanami

byos hanami ruby server trmnl

Last synced: 2 months ago
JSON representation

A TRMNL BYOS application.

Awesome Lists containing this project

README 

        
:toc: macro

:toclevels: 5

:figure-caption!:



:docker_link: link:https://www.docker.com[Docker]

:hanami_link: link:https://hanamirb.org[Hanami]

:htmx_link: link:https://htmx.org[htmx]

:overmind_link: link:https://github.com/DarthSim/overmind[Overmind]

:puma_link: link:https://puma.io[Puma]

:ruby_link: link:https://www.ruby-lang.org[Ruby]

:sqlite_link: link:https://www.sqlite.org[SQLite]

:trmnl_link: link:https://usetrmnl.com[TRMNL]

:yjit_link: link:https://github.com/ruby/ruby/blob/master/doc/yjit/yjit.md[YJIT]



= Terminus



This is a {ruby_link}/{hanami_link} project that allows you to point a {trmnl_link} 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_link}.



toc::[]



== Features



* Allows you to run your own server.

* Built atop {ruby_link} and {hanami_link}.

* Provides automatic detection of your server's IP address.

* Uses {htmx_link}.

* Uses {puma_link}.

* Uses {sqlite_link}.

* Supports {yjit_link}.

* Supports {overmind_link}.

* Supports {docker_link}.

* Supports {trmnl_link} 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 link:https://usetrmnl.com[hosted] solution.



*Legend*



* ⚪️ Planned.

* 🟢 Supported.

* 🟡 Partially supported.

* 🔴 Not supported, not implemented, or isn't applicable.



*Matrix*



[options="header"]

|===

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



video::3xehPW-PCOM[youtube,role=video]



== Requirements



. {ruby_link}.

. {hanami_link}.

. {overmind_link} (optional).

. {docker_link} (optional).

. A TRMNL device.



== Setup



To set up project, run:



[source,bash]

----

git clone https://github.com/usetrmnl/byos_hanami terminus

cd terminus

bin/setup

----



== Usage



To launch the server, run:



[source,bash]

----

bundle exec hanami assets compile

bundle exec puma --config ./config/puma.rb

----



💡 Install {overmind_link} 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 SQLite database. Defaults to the `db` folder but can be customized by changing the value in the `.env.development` or `.env.test` file created when you ran `bin/setup`.

* `IMAGES_ROOT`: The root location for all generated images. Defaults to `public/assets/images`.



=== 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

[%collapsible]

====

*Without Base64 Encryption*



[source,bash]

----

curl "https://localhost:2443/api/display/" \

     -H 'ID: ' \

     -H 'Access-Token: ' \

     -H 'Accept: application/json' \

     -H 'Content-Type: application/json'

----



*With Base64 Encryption via HTTP Header*



[source,bash]

----

curl "https://localhost:2443/api/display/" \

     -H 'ID: ' \

     -H 'Access-Token: ' \

     -H 'Accept: application/json' \

     -H 'Content-Type: application/json' \

     -H 'BASE64: true'

----



*With Base64 Encryption via Parameter*



[source,bash]

----

curl "https://localhost:2443/api/display/?base_64=true" \

     -H 'ID: ' \

     -H 'Access-Token: ' \

     -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

[%collapsible]

====

*Without Base64 Encryption*

[source,json]

----

{

  "filename": "demo.bmp",

  "firmware_url": null,

  "image_url": "https://localhost:2443/assets/images/generated/demo.bmp",

  "refresh_rate": 130,

  "reset_firmware": false,

  "special_function": "sleep",

  "status": 0,

  "update_firmware": false

}

----



*With Base64 Encryption*



[source,json]

----

{

  "filename": "demo.bmp",

  "firmware_url": null,

  "image_url": "data:image/bmp;base64,",

  "refresh_rate": 200,

  "reset_firmware": false,

  "special_function": "sleep",

  "status": 0,

  "update_firmware": false

}

----

====



==== Setup



Uses for new device setup and then never used after.



.Request

[%collapsible]

====

[source,bash]

----

curl "https://localhost:2443/api/setup/" \

    -H 'ID: ' \

    -H 'Access-Token: ' \

    -H 'Accept: application/json' \

    -H 'Content-Type: application/json'

----

====



.Response

[%collapsible]

====

[source,json]

----

{

  "api_key": "",

  "friendly_id": "ABC123",

  "image_url": "https://localhost:2443/images/setup/logo.bmp",

  "message": "Welcome to TRMNL BYOS",

  "status": 200

}

----

====



==== Logs



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



.Request

[%collapsible]

====

[source,bash]

----

curl -X "POST" "https://localhost:2443/api/log" \

     -H 'ID: ' \

     -H 'Access-Token: ' \

     -H 'Accept: application/json' \

     -H 'Content-Type: application/json'

----

====



.Response

[%collapsible]

====

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

[%collapsible]

====

[source,bash]

----

curl -X "POST" "https://localhost:2443/api/images" \

    -H 'ID: ' \

    -H 'Access-Token: ' \

    -H 'Accept: application/json' \

    -H 'Content-Type: application/json' \

    -d $'{

 "image": {

   "content": "
Test
"

   "file_name": "test"

 }

}'

----

====



.Response

[%collapsible]

====

[source,json]

----

{

  "path": "$HOME/Engineering/terminus/public/assets/images/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:



[source,css]

----

* {

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



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



== Development



To contribute, run:



[source,bash]

----

git clone https://github.com/usetrmnl/terminus

cd terminus

bin/setup

----



=== Console



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



[source,bash]

----

bin/console

----



Once in the console, you can do the following:



[source,ruby]

----

# Use a repository.

repository = Terminus::Repositories::Device.new



repository.all     # View all devices.

repository.find 1  # Find by Device ID.



# Fetch upcoming render, sorts in descending order by created timestamp.

Terminus::Images::Fetcher.new.call images_uri: "https://localhost:2443/assets/images"



# To generate image with random name.

creator = Terminus::Images::Creator.new

creator.call "
Test
",

             Pathname(Hanami.app[:settings].images_root).join("generated/%s.bmp")

#



# To generate image with specific name.

creator.call "
Test.
", Pathname.pwd.join("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

[%collapsible]

====

[source,html]

----



  

    



    Demo



    



    

      * {

        margin: 0;

      }

    



    

    

  



  

    Image

  



----

====



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

[%collapsible]

====

[source,ruby]

----

creator = Terminus::Images::Creator.new



creator.call(<<~CONTENT, Pathname(Hanami.app[:settings].images_root).join("generated/%s.bmp"))

  



  

    

      



      Demo



      



      

        * {

          margin: 0;

        }

      



      

      

    



    

      
Hello, World!


    

  

CONTENT

----

====



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



To build a {docker_link} image, run:



[source,bash]

----

bin/docker/build

----



To work within your {docker_link} image, run:



[source,bash]

----

bin/docker/console

----



=== YJIT



{yjit_link} 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 since modern CSS is so powerful we don't need to reach for frameworks anymore which also reduces the complexity of this project. 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:



[source,bash]

----

bin/rake

----



== Deployment



More details to be provided soon.



== Credits



* Built with link:https://alchemists.io/projects/hanamismith[Hanamismith].

* Engineered by {trmnl_link}.