Data

Tools

Indexes

Applications

Experiments

Awesome

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

https://github.com/usetrmnl/byos_sinatra

DIY server in Ruby/Sinatra for self hosted screen generation
https://github.com/usetrmnl/byos_sinatra

trmnl

Last synced: 3 months ago
JSON representation

DIY server in Ruby/Sinatra for self hosted screen generation

Awesome Lists containing this project

README 

        
:toc: macro

:toclevels: 5

:figure-caption!:



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

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



= TRMNL BYOS (Ruby/Sinatra)



‼️ *This implementation has been eclipsed by our link:https://github.com/usetrmnl/byos_hanami[Terminus] (BYOS Hanami) implementation which is our flagship implementation. Terminus is where all of our active development is and provides a lot more features. Please use Terminus instead. Thanks and enjoy!*



This project allows you to point a {trmnl_link} device to your own server which can be running on your local network or in the cloud.



toc::[]



== Features



* Allows you to run your own server.

* Supports link:https://puma.io[Puma].

* Supports link:https://www.sqlite.org[SQLite].

* 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 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"]

|===

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



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

. {docker_link} (optional).

. A TRMNL device.



== Setup



To set up project, run:



[source,bash]

----

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

cd byos_sinatra

bin/setup

----



== Usage



To launch the server, run:



[source,bash]

----

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

----



💡 Install link:https://github.com/DarthSim/overmind[Overmind] and run `overmind start` to run with full access to all processes (including remote debugging).



To use the app, open `http://localhost:4567` in your browser to view the app and manage your device(s).



=== APIs



The following APIs are supported:



[source,bash]

----

## Display

curl "http://localhost:4567/api/display/" \

     -H 'ID: ' \

     -H 'Access-Token: ' \

     -H 'Accept: application/json' \

     -H 'Content-Type: application/json'



## Setup

curl "http://localhost:4567/api/setup/" \

    -H 'ID: ' \

    -H 'Access-Token: ' \

    -H 'Accept: application/json' \

    -H 'Content-Type: application/json'



## Logs

curl -X "POST" "http://localhost:4567/api/log" \

     -H 'ID: ' \

     -H 'Access-Token: ' \

     -H 'Accept: application/json' \

     -H 'Content-Type: application/json'



## Images

curl -X "POST" "http://localhost:4567/api/images" \

    -H 'ID: ' \

    -H 'Access-Token: ' \

    -H 'Accept: application/json' \

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

    -d $'{

 "image": {

   "content": "
Test
"

   "file_name": "test"

 }

}'

----



💡 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/byos_sinatra

cd byos_sinatra

bin/setup

----



You can also use the IRB console for direct access to all objects:



[source,bash]

----

bin/console

----



Once in the console, you can then do the following:



[source,ruby]

----

# View all devices.

Device.all



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

Images::Fetcher.new.call



# To generate default image.

Images::Creator.new.call "
Test.
"

#



# To generate image with custom path.

Images::Creator.new.call "
Test.
", Pathname.pwd.join("test.bmp")

#



# To generate image with custom path and dynamic name.

Images::Creator.new.call "
Test.
", Pathname.pwd.join("%s.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:



.Console Image Generation

[%collapsible]

====

[source,ruby]

----

creator = Images::Creator.new



creator.call(<<~CONTENT, Pathname("public/images/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

----



== Tests



To test, run:



[source,bash]

----

bin/rake

----



== Deployment



*Local*



. Configure `APP_URL` within `.env` to where your app is hosted (i.e. `http://192.168.x.x:4567`). 💡 Lack of trailing slash is important.

. Prefix `RACK_ENV=production` before launching the server to run in production mode.

. Retrieve your machine's local IP, ex 192.168.x.x (Mac: `ifconfig | grep "inet " | grep -Fv 127.0.0.1 | awk '{print $2}'`)

. Confirm the application works by visiting `http://192.168.x.x:4567/devices` from any device also on the network.

. Point your [forked firmware](https://github.com/usetrmnl/firmware) `API_BASE_URL` ([source](https://github.com/usetrmnl/firmware/blob/2ee0723c66a3468b969c83d7663ffb3f8322ad99/include/config.h#L56)) to same value as `APP_URL`.



*Hosted*



More details to be provided soon.



== Credits



* Built with link:https://alchemists.io/projects/rubysmith[Rubysmith].

* Engineered by {trmnl_link}.