:toc: macro
:toclevels: 5
:figure-caption!:

:trmnl_link: link:https://trmnl.com[TRMNL]
:trmnl_api_link: link:https://trmnl.com/api-docs/index.html[TRMNL API]
:dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads]

= TRMNL API

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

toc::[]

== Features

* Provides {trmnl_api_link} access.

== Requirements

. link:https://www.ruby-lang.org[Ruby].
. A {trmnl_link} device (physical or virtual).

== Setup

To install, run:

[source,bash]
----
gem install trmnl-api
----

You can also add the gem directly to your project:

[source,bash]
----
bundle add trmnl-api
----

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

[source,ruby]
----
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_link}) based on result of the API call. This allows you pattern match in your own code when using each endpoint. Example:

``` ruby
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 xref:_endpoints[Endpoints] for further details.

=== Configuration

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

[source,ruby]
----
client = TRMNL::API.new do |settings|
  settings.content_type = "application/json",
  settings.uri = "https://trmnl.app/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_URI`: Defines the API URI. Default: `"https://trmnl.app/api"`.

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

=== Endpoints

==== Categories

Allows you to obtain the list of approved plugin categories. Example:

[source,ruby]
----
client = TRMNL::API.new
client.categories

# Success(
#   [
#     "analytics",
#     "art",
#     "calendar"
#   ]
# )
----

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

[source,ruby]
----
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 xref:_current_screen[Current Screen] endpoint. You must supply your device's API token as the `token`. Example:

[source,ruby]
----
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
#   >
# )
----

==== Firmware

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

[source,ruby]
----
client = TRMNL::API.new
client.firmware

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

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

[source,ruby]
----
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>
#     ]
#   >
# )
----

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

[source,ruby]
----
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:

[source,ruby]
----
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:

[source,ruby]
----
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 link:https://trmnl.com/recipes[Recipes]. Example:

[source,ruby]
----
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_link} 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:

[source,ruby]
----
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:

[source,bash]
----
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:

[source,bash]
----
bin/console
----

== Tests

To test, run:

[source,bash]
----
bin/rake
----

== Credits

* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].
* Engineered by link:https://trmnl.com/developers[TRMNL].