TRMNL BYOS - Python / Django

This is a fork of TRMNL's Django BYOS app. This fork adds Nix-based packaging and deployment of the application.

Original: This is an implementation of the TRMNL API in Python, which you can use your TRMNL device with.

Development

This app uses direnv and nix to provide all dependencies. Please install and use those.

Django App

python ./manage.py migrate
python ./manage.py createsuperuser
python ./manage.py collectstatic
daphne -b 0.0.0.0 -p 8000 byos_django.asgi:application

# your app is now up on http://localhost:8000

TRMNL Screens

Access http://localhost:8000/preview where you can test the rendering output of TRML screens.

Deployment

This is intended to be deployed as a NixOS module referenced by a flake; these instructions follow that approach:

1. Add this repo as a flake input in flake.nix:

   {
     inputs = {
       # ...
       mathieu-trmnl.url = "git+ssh://[email protected]/mfenniak/mathieu-trmnl.git?ref=main";
     }
   }
   

2. Install the package overlay and nixos module in flake.nix:

   {
     outputs = { ...other-inputs..., mathieu-trmnl, ... } = {
       nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
         system = "x86_64-linux";
         modules = [
           # other modules, configurations, etc.
           { nixpkgs.overlays = [ mathieu-trmnl.overlays.default ]; }
           mathieu-trmnl.nixosModules.trmnl-django
         ];
       };
     }
   }
   

3. Enable the program in your system configuration:

   { config, ... }:
   
   let
     host = "trmnl.example.com";
   in {
     programs.trmnl-django = {
       enable = true;
       port = 8000;
       allowedHosts = "${host}";
     };
   
     services.nginx.virtualHosts."${host}" = {
       forceSSL = true;
       enableACME = true;
       locations."/" = {
         proxyPass = "http://localhost:${toString config.programs.trmnl-django.port}";
         proxyWebsockets = true;
       };
     };
   }
   

4. Add /var/lib/trmnl-django to your backups.

5. Rebuild NixOS and ensure that trmnl-django.service is running successfully.

6. Create an initial superuser:

   Find the trmnl-django package in /nix/store in order to run the createsuperuser binary within:

   DB_FILE=/var/lib/trmnl-django/trmnl-django.db sudo /nix/store/gky87fqcwzp6kphrpc8spnzmchkkdqgz-trmnl-django-0.1/bin/createsuperuser
   

Usage

• Point your TRMNL to your IP or Hostname http://your-ip-or-hostname:8000
• Open your browser to the same URL, you'll be redirected to the admin page.
• Once your start your TRMNL, you'll see a new device under the Devices section. To "pair" it, just assign it to your user.
• If you see the Rover image, your device is paired and ready to use!
• You can create a new Screen under the Screens section.
  • Use whatever HTML you want. I recommend using the boilerplate in temmplates/base.html to make use of the framework.
  • Click Save and wait a moment for the image to be generated.
  • On the next refresh (defaults to 900 seconds, can be configured on the Device edit page) your TRMNL will update to the new screen.

API

Generate a screen for a specific device by creating an API Key from Admin > API Keys > Add, then:

curl --location 'http://your.ip.address.here:8000/api/v1/generate_screen' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxx' \
--data '{
  "device": "XXXXXX", # friendly ID
  "html": "<p>Made via API</p>"
}'

An optional body parameter delete_other_device_screens can be set to true, which will cause the new screen to be the only screen displayed to the requested device, deleting all other screens for that device. This allows the API to be used to remotely update the TRMNL device to one specific rendered output.

Troubleshooting:

• After creating an API Key, it appears just once following Save > redirect
• For the API Key to be valid, your device must belong to a user before creating and it with that user