TRMNL API

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
• Requirements
• Setup
• Usage
  • Configuration
  • Environment
  • Endpoints
    • Current Screen
    • Display
    • Firmware
    • Log
    • Setup
• Development
• Tests
• Credits

Features

• Provides TRMNL API access.

Requirements

1. Ruby.

2. 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::Client.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 always 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::Client.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

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::Client.new
client.current_screen token: "secret"

# Success(
#   #<data TRMNL::API::Models::CurrentScreen
#      refresh_rate=1773,
#      image_url="https://usetrmnl.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::Client.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",
#     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:

client = TRMNL::API::Client.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">)

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::Client.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.

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::Client.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://usetrmnl.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.