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

:trmnl_link: link:https://usetrmnl.com[TRMNL]
:dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads]

= TRMNL API

A monadic {trmnl_link} API 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_link} API 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::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 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::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:

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

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

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

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

[source,ruby]
----
client = TRMNL::API::Client.new
client.call 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:

[source,ruby]
----
client = TRMNL::API::Client.new
client.call 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:

[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://usetrmnl.com/developers[TRMNL].