{"id":27874132,"url":"https://github.com/usetrmnl/trmnl-api","last_synced_at":"2025-06-14T17:03:10.721Z","repository":{"id":289351701,"uuid":"970992279","full_name":"usetrmnl/trmnl-api","owner":"usetrmnl","description":"A monadic TRMNL API client.","archived":false,"fork":false,"pushed_at":"2025-05-28T23:09:57.000Z","size":71,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-14T17:02:47.914Z","etag":null,"topics":["api","client","trmnl"],"latest_commit_sha":null,"homepage":"https://usetrmnl.com/developers","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usetrmnl.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-22T21:05:17.000Z","updated_at":"2025-06-01T08:28:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"f3ee9599-7061-42e4-975f-0679eb8bbc83","html_url":"https://github.com/usetrmnl/trmnl-api","commit_stats":null,"previous_names":["usetrmnl/trmnl-api"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/usetrmnl/trmnl-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Ftrmnl-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Ftrmnl-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Ftrmnl-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Ftrmnl-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usetrmnl","download_url":"https://codeload.github.com/usetrmnl/trmnl-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Ftrmnl-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259851659,"owners_count":22921626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","trmnl"],"created_at":"2025-05-05T01:30:42.964Z","updated_at":"2025-06-14T17:03:10.714Z","avatar_url":"https://github.com/usetrmnl.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":":toc: macro\n:toclevels: 5\n:figure-caption!:\n\n:trmnl_link: link:https://usetrmnl.com[TRMNL]\n:dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads]\n\n= TRMNL API\n\nA 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.\n\ntoc::[]\n\n== Features\n\n* Provides {trmnl_link} API access.\n\n== Requirements\n\n. link:https://www.ruby-lang.org[Ruby].\n. A {trmnl_link} device (physical or virtual).\n\n== Setup\n\nTo install, run:\n\n[source,bash]\n----\ngem install trmnl-api\n----\n\nYou can also add the gem directly to your project:\n\n[source,bash]\n----\nbundle add trmnl-api\n----\n\nOnce the gem is installed, you only need to require it:\n\n[source,ruby]\n----\nrequire \"trmnl/api\"\n----\n\n== Usage\n\nThis 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:\n\n``` ruby\nclient = TRMNL::API::Client.new\n\ncase client.display token: \"secret\"\n  in Success(payload) then puts payload\n  in Failure(response) then puts response\n  else puts \"Unknown response.\"\nend\n```\n\nSee xref:_endpoints[Endpoints] for further details.\n\n=== Configuration\n\nBy 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:\n\n[source,ruby]\n----\nclient = TRMNL::API::Client.new do |settings|\n  settings.content_type = \"application/json\",\n  settings.uri = \"https://trmnl.app/api\"\nend\n----\n\n=== Environment\n\nYou can configure the client via the following environment variables:\n\n* `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\".\n* `TRMNL_API_URI`: Defines the API URI. Default: \"https://trmnl.app/api\".\n\nAny/all environment changes will be applied unless you override these settings via the client configuration block shown above.\n\n=== Endpoints\n\n==== Current Screen\n\nAllows you to obtain current screen being displayed for your device. You must supply your device's API token as the `token`. Example:\n\n[source,ruby]\n----\nclient = TRMNL::API::Client.new\nclient.current_screen token: \"secret\"\n\n# Success(\n#   #\u003cdata TRMNL::API::Models::CurrentScreen\n#      refresh_rate=1773,\n#      image_url=\"https://usetrmnl.com/plugin-2025-04-10T11-34-38Z-380c77\",\n#      filename=\"plugin-2025-04-10T11-34-38Z-380c77\"\n#   \u003e\n# )\n----\n\n==== Display\n\nAllows 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:\n\n[source,ruby]\n----\nclient = TRMNL::API::Client.new\nclient.display token: \"secret\"\n\n# Success(\n#   #\u003cstruct TRMNL::API::Models::Display\n#     filename=\"plugin-1745348489\",\n#     firmware_url=\"https://trmnl-fw.s3.us-east-2.amazonaws.com/FW1.4.8.bin\",\n#     image_url=\"https://trmnl.s3.us-east-2.amazonaws.com/plugin-1745348489\",\n#     image_url_timeout=0,\n#     refresh_rate=1771,\n#     reset_firmware=false,\n#     special_function=\"restart_playlist\",\n#     update_firmware=true\n#   \u003e\n# )\n----\n\n==== Firmware\n\nAllows you to obtain the current stable firmware version. Example:\n\n[source,ruby]\n----\nclient = TRMNL::API::Client.new\nclient.firmware\n\n# Success(#\u003cdata TRMNL::API::Models::Firmware url=\"https://trmnl-fw.s3.us-east-2.amazonaws.com/FW1.4.8.bin\", version=\"1.4.8\"\u003e)\n----\n\n==== Log\n\nAllows 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:\n\n[source,ruby]\n----\nclient = TRMNL::API::Client.new\nclient.log token: \"secret\",\n            log: {\n              logs_array: [\n                {\n                  log_id: 1,\n                  creation_timestamp: 1742022124,\n                  log_message: \"returned code is not OK: 404\",\n                  log_codeline: 597,\n                  device_status_stamp: {\n                    wifi_status: \"connected\",\n                    wakeup_reason: \"timer\",\n                    current_fw_version: \"1.4.7\",\n                    free_heap_size: 160656,\n                    special_function: \"none\",\n                    refresh_rate: 30,\n                    battery_voltage: 4.772,\n                    time_since_last_sleep_start: 31,\n                    wifi_rssi_level: -54\n                  },\n                  additional_info: {\n                    retry_attempt: 1\n                  },\n                  log_sourcefile: \"src/bl.cpp\"\n                }\n              ]\n            }\n\n# Success(#\u003cHTTP::Response/1.1 204 No Content...)\n----\n\nYou'll either get a 204 No Content or 200 OK response depending on if the device exists or not.\n\n==== Setup\n\nAllows 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:\n\n[source,ruby]\n----\nclient = TRMNL::API::Client.new\nclient.setup id: \"A1:B2:C3:D4:E5:F6\"\n\n# Success(\n#   #\u003cdata TRMNL::API::Models::Setup\n#     api_key=\"secret\",\n#     friendly_id=\"F51FDE\",\n#     image_url=\"https://usetrmnl.com/images/setup/setup-logo.bmp\",\n#     message=\"Register at usetrmnl.com/signup with Device ID 'F51FDE'\"\n#   \u003e\n# )\n----\n\n== Development\n\nTo contribute, run:\n\n[source,bash]\n----\ngit clone https://github.com/usetrmnl/trmnl-api\ncd trmnl-api\nbin/setup\n----\n\nYou can also use the IRB console for direct access to all objects:\n\n[source,bash]\n----\nbin/console\n----\n\n== Tests\n\nTo test, run:\n\n[source,bash]\n----\nbin/rake\n----\n\n== Credits\n\n* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].\n* Engineered by link:https://usetrmnl.com/developers[TRMNL].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusetrmnl%2Ftrmnl-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusetrmnl%2Ftrmnl-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusetrmnl%2Ftrmnl-api/lists"}