File: README — Documentation by YARD 0.9.38

A monadic TRMNL API client. You can use this client in your own code to interact with our APIs for any/all devices that you own.

Table of Contents

Features

Provides TRMNL API access.

Requirements

Ruby.
A TRMNL device (physical or virtual).

Setup

To install, run:

gem install trmnl-api

You can also add the gem directly to your project:

bundle add trmnl-api

Once the gem is installed, you only need to require it:

require "trmnl/api"

Usage

This client provides access to multiple endpoints. Each endpoint will answer either a Success or Failure (as provided by Dry Monads) based on result of the API call. This allows you pattern match in your own code when using each endpoint. Example:

client = TRMNL::API.new

case client.display token: "secret"
  in Success(payload) then puts payload
  in Failure(response) then puts response
  else puts "Unknown response."
end

See Endpoints for further details.

Configuration

By default, you shouldn’t need to change the default configuration but you can use a block to adjust settings as desired. If you don’t configure the client, then the following defaults will be used:

client = TRMNL::API.new do |settings|
  settings.content_type = "application/json",
  settings.timeout_connect = 2
  settings.timeout_read = 10
  settings.timeout_write = 10
  settings.uri = "https://trmnl.app/api"
  settings.user_agent = "TRMNL API"
end

Environment

You can configure the client via the following environment variables:

TRMNL_API_CONTENT_TYPE: Defines the HTTP Content-Type header. You shouldn’t need to change this but is here if you need it. Default: "application/json".
TRMNL_API_TIMEOUT_CONNECT: Defines the time, in seconds, for establishing a connection. Default: 2.
TRMNL_API_TIMEOUT_READ: Defines the time, in seconds, for reading content. Default: 10.
TRMNL_API_TIMEOUT_WRITE: Defines the time, in seconds, for writing content. Default: 10.
TRMNL_API_URI: Defines the API URI. Default: "https://trmnl.app/api".
TRMNL_API_USER_AGENT: Defines the HTTP User-Agent header. You shouldn’t need to change this but is here if you need need to customize this for upstream application identification. Default: "TRMNL API". The fully computed user agent ends up being: "http.rb/6.0.0 (TRMNL API)" (only the value in parenthesis is configurable).

Any/all environment changes will be applied unless you override these settings via the client configuration block shown above.

Endpoints

Current Screen

Allows you to obtain current screen being displayed for your device. You must supply your device’s API token as the token. Example:

client = TRMNL::API.new
client.current_screen token: "secret"

# Success(
#   #<data TRMNL::API::Models::CurrentScreen
#      refresh_rate=1773,
#      image_url="https://trmnl.com/plugin-2025-04-10T11-34-38Z-380c77",
#      filename="plugin-2025-04-10T11-34-38Z-380c77"
#   >
# )

Display

Allows you to obtain current screen being displayed for your device with additional information not provided by the Current Screen endpoint. You must supply your device’s API token as the token. Example:

client = TRMNL::API.new
client.display token: "secret"

# Success(
#   #<struct TRMNL::API::Models::Display
#     filename="plugin-1745348489",
#     firmware_url="https://trmnl-fw.s3.us-east-2.amazonaws.com/FW1.4.8.bin",
#     firmware_version="1.4.8",
#     image_url="https://trmnl.s3.us-east-2.amazonaws.com/plugin-1745348489",
#     image_url_timeout=0,
#     refresh_rate=1771,
#     reset_firmware=false,
#     special_function="restart_playlist",
#     update_firmware=true
#   >
# )

IP Addresses

Allows you obtain a list of public IP addresses for all TRMNL core servers because plugin poll requests will only originate from these IPs. Example:

client = TRMNL::API.new
client.ip_addresses

# Success(
#   #<data TRMNL::API::Models::IPAddress
#     version_4=[
#       #<IPAddr: IPv4:111.230.59.36/255.255.255.255>,
#       #<IPAddr: IPv4:222.9.106.45/255.255.255.255>
#     ],
#     version_6=[
#       #<IPAddr: IPv6:1:2:0400:00d0:0000:0000:1874:e001/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff>,
#       #<IPAddr: IPv6:1:2:0400:00d1:0000:0001:705e:1001/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff>
#     ]
#   >
# )

Latest Firmware

Allows you to obtain the latest stable firmware version. Example:

client = TRMNL::API.new
client.latest_firmware

# Success(
#   #<data TRMNL::API::Models::LatestFirmware
#          url="https://trmnl-fw.s3.us-east-2.amazonaws.com/FW1.4.8.bin",
#          version="1.4.8">
# )

Log

Allows you to create a log entry (which is what the device reports when it captures an error). You must supply your device’s API token as the token. Example:

client = TRMNL::API.new
client.log token: "secret",
            log: {
              logs_array: [
                {
                  log_id: 1,
                  creation_timestamp: 1742022124,
                  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"
                }
              ]
            }

# Success(#<HTTP::Response/1.1 204 No Content...)

You’ll either get a 204 No Content or 200 OK response depending on if the device exists or not.

Models

Allows you to obtain the model information for all devices and screens. Example:

client = TRMNL::API.new
client.models

# Success(
#  [
#    #<Struct:TRMNL::API::Models::Model:0x00003c20
#      bit_depth = 4,
#      colors = 16,
#      css = {
#          classes: {
#          density: "screen--density-2x",
#           device: "screen--v2",
#             size: "screen--lg"
#        },
#        variables: [
#          [
#            "--screen-w",
#            "1040px"
#          ],
#          [
#            "--screen-h",
#            "780px"
#          ],
#          [
#            "--pixel-ratio",
#            "1.8"
#          ],
#          [
#            "--dither-pixel-ratio",
#            "2.0"
#          ],
#          [
#            "--ui-scale",
#            "1.0"
#          ],
#          [
#            "--gap-scale",
#            "1.0"
#          ]
#        ]
#      },
#      description = "TRMNL X",
#      height = 1404,
#      kind = "trmnl",
#      label = "TRMNL X",
#      mime_type = "image/png",
#      name = "v2",
#      offset_x = 0,
#      offset_y = 0,
#      palette_names = [
#        "gray-16",
#        "gray-4",
#        "bw"
#      ],
#      rotation = 0,
#      scale_factor = 1.8,
#      width = 1872
#    >
#  ]
# )

ℹ️ The scale_factor can be an integer or float.

Palettes

Allows you to obtain palettes details. The names correlate to the palette_names as found in the Models API. Example:

client = TRMNL::API.new
client.palettes

Success(
  [
    #<Struct:TRMNL::API::Models::Palette
      name = "bw",
      label = "Black & White (1-bit)",
      grays = 2,
      colors = [],
      framework_class = "screen--1bit"
    >,
    #<Struct:TRMNL::API::Models::Palette
      name = "color-3bwr",
      label = "Color (3 colors)",
      grays = 2,
      colors = [
        "#000000",
        "#FF0000",
        "#FFFFFF"
      ],
      framework_class = nil
    >,
    #<Struct:TRMNL::API::Models::Palette
      name = "color-24bit",
      label = "Color (16777216 colors)",
      grays = 2,
      colors = [],
      framework_class = nil
    >
  ]
)

Recipes

Allows you to obtain information about Recipes. Example:

client = TRMNL::API.new { |settings| settings.uri = "https://trmnl.com" }

client.recipes                     # Answers first page.
client.recipes page: 10            # Answers page ten.
client.recipes search: "comic"     # Answers first page of comics.
client.recipes sort: "popularity"  # Answers first page sorted by popularity.

# Success(
#  #<data TRMNL::API::Models::Recipe
#    data = [
#      #<Struct:TRMNL::API::Models::Recipes::Data:0x00010fe0
#        author = #<Struct:TRMNL::API::Models::Recipes::Author:0x00010ff0
#          category = nil,
#          description = nil,
#          description_locales = {},
#          email_address = nil,
#          field_type = nil,
#          github_url = nil,
#          keyname = nil,
#          learn_more_url = nil,
#          name = nil,
#          youtube_url = nil
#        >,
#        custom_fields = [
#          {
#                "keyname" => "user_location",
#             "field_type" => "string",
#                   "name" => "Weather Location",
#            "placeholder" => "New York, NY",
#            "description" => "Choose a location",
#              "help_text" => "Please be precise...",
#               "required" => true
#          },
#          {
#                "keyname" => "metric",
#                   "name" => "Temperature Metric",
#            "description" => "Celsius or Fahrenheit?",
#             "field_type" => "select",
#                "options" => [
#              "Fahrenheit",
#              "Celsius"
#            ],
#                "default" => "Fahrenheit"
#          }
#        ],
#        icon_content_type = "image/png",
#        icon_url = "https://trmnl-public.s3.us-east-2.amazonaws.com/ajjlbek4cabcvhk3s1lxggn8cgon",
#        id = 49610,
#        name = "Weather Chum",
#        published_at = 2025-05-14 05:32:00 UTC,
#        screenshot_url = "https://trmnl.s3.us-east-2.amazonaws.com...",
#        statistics = #<data TRMNL::API::Models::Recipes::Statistics:0x00011170
#          forks = 1710,
#          installs = 1
#        >
#      >
#    ],
#    meta = #<data TRMNL::API::Models::Recipes::Meta:0x00016e20
#      current_page = 1,
#      from = 1,
#      next_page_url = "/recipes.json?page=2&sort_by=popularity",
#      per_page = 25,
#      prev_page_url = nil,
#      to = 25,
#      total = 678
#    >
#  >
# )

⚠️ This does not use the TRMNL API like every other endpoint documented here. Instead, you must customize the settings URI to point to the root of the TRMNL application (i.e. https://trmnl.com) instead of using the default API endpoint.

You’ll always get a data array which may or may not be filled and meta (metadata) for handling pagination information. You can also combine the page, search, and page parameters as you see fit.

Setup

Allows you to obtain the setup response for when a new device is setup. You must supply your device’s MAC Address as the id. Example:

client = TRMNL::API.new
client.setup id: "A1:B2:C3:D4:E5:F6"

# Success(
#   #<data TRMNL::API::Models::Setup
#     api_key="secret",
#     friendly_id="F51FDE",
#     image_url="https://trmnl.com/images/setup/setup-logo.bmp",
#     message="Register at usetrmnl.com/signup with Device ID 'F51FDE'"
#   >
# )

Development

To contribute, run:

git clone https://github.com/usetrmnl/trmnl-api
cd trmnl-api
bin/setup

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

bin/console

Tests

To test, run:

bin/rake

Credits

Built with Gemsmith.
Engineered by TRMNL.

Features

Requirements

Setup

Usage

Configuration

Environment

Endpoints

Categories

Current Screen

Display

IP Addresses

Latest Firmware

Log

Models

Palettes

Recipes

Setup

Development

Tests

Credits