https://github.com/usetrmnl/trmnl-api
A monadic TRMNL API client.
https://github.com/usetrmnl/trmnl-api
api client trmnl
Last synced: about 1 year ago
JSON representation
A monadic TRMNL API client.
- Host: GitHub
- URL: https://github.com/usetrmnl/trmnl-api
- Owner: usetrmnl
- License: mit
- Created: 2025-04-22T21:05:17.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-28T23:09:57.000Z (about 1 year ago)
- Last Synced: 2025-06-14T17:02:47.914Z (about 1 year ago)
- Topics: api, client, trmnl
- Language: Ruby
- Homepage: https://usetrmnl.com/developers
- Size: 69.3 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
: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(
# #
# )
----
==== 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(
# #
# )
----
==== Firmware
Allows you to obtain the current stable firmware version. Example:
[source,ruby]
----
client = TRMNL::API::Client.new
client.firmware
# Success(#)
----
==== 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.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(#
# )
----
== 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].