diff --git a/.gitbook/assets/TRMNL-playlist-scheduler.png b/.gitbook/assets/TRMNL-playlist-scheduler.png new file mode 100644 index 0000000..eab7edc Binary files /dev/null and b/.gitbook/assets/TRMNL-playlist-scheduler.png differ diff --git a/SUMMARY.md b/SUMMARY.md index 33641f2..908e62b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -35,7 +35,7 @@ ## Private API * [Introduction](private-api/introduction.md) -* [Screens API](private-api/screens.md) +* [Display API](private-api/screens.md) * [Plugin Data API](private-api/plugin-data.md) * [Account API](private-api/account.md) * [More Endpoints](private-api/more-endpoints.md) diff --git a/diy/byod-s.md b/diy/byod-s.md index b70b010..361fc59 100644 --- a/diy/byod-s.md +++ b/diy/byod-s.md @@ -4,7 +4,7 @@ description: Bring your own device, and build your own server for the device to # BYOD/S -In the BYOD/S model, the only TRMNL IP is our [open source firmware](https://github.com/usetrmnl/firmware). Technically we don't owe you any explanation to get up and running, but we'll do it anyway. ;) +In the BYOD/S model, the only TRMNL IP is our [open source firmware](https://github.com/usetrmnl/firmware). Technically we don't owe you an explanation to get up and running, but we'll provide one anyway. ;) ### Device setup @@ -12,38 +12,36 @@ See our [BYOD guide](byod.md) for instructions to build a device that's compatib ### Server quickstart -The TRMNL web server generates bitmap images. When a device pings our web server, the next-in-queue image is shared as an absolute URL inside a JSON response like this: +The TRMNL web server generates PNG images. When a device pings our [Display API](../private-api/screens.md), the next-in-queue image is shared as an absolute URL inside a JSON response like this: ``` { - "image_url"=>"https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.bmp" + "image_url"=>"https://trmnl.s3.us-east-2.amazonaws.com/path-to-img.png" } ``` -You can demo this process from the command line by installing [ImageMagick](https://en.wikipedia.org/wiki/ImageMagick), then invoking `convert` command. Visit our [imagemagick guide](imagemagick-guide.md) +For several ready-made OSS server implementations, see [BYOS Implementations](https://docs.usetrmnl.com/go/diy/byos#implementations). To develop your own server that is TRMNL firmware compatible out of the box: -With this in mind, building your own server simply necessitates creating an endpoint that responds with links to firmware-compatible Bitmap images. - -Assuming you've set up a device, simply... - -1. change the base URL to your own server or local network from the WiFi Captive Portal -2. mimic the `api/setup` and `api/display` endpoints to respond per the [firmware readme](https://github.com/usetrmnl/firmware) -3. profit +1. [build a device](byod.md) +2. change the base URL to your own server or local network from the WiFi Captive Portal +3. mimic the `api/setup` and `api/display` endpoints per our [firmware README](https://github.com/usetrmnl/firmware) +4. follow our [ImageMagick guide](imagemagick-guide.md) to create TRMNL firmware compatible images +5. profit ### Other infrastructure -In the quickstarter above we glossed over a critical element: "next-in-queue" images. +In the quickstart above we glossed over a critical element: "next-in-queue" images. -At TRMNL we use a Playlists table to manage the ordering of plugin instances, so that users can drag/drop different screen content in any sequence they like. +At TRMNL we use a Playlists table to manage the ordering of plugin instances, letting users drag/drop different items in whatever sequence they prefer.

Drag/Drop Playlists UI

Each item in a device's Playlist is an instance\* of a Plugin, something we call a PluginSetting. -This keeps our Plugins table immutable, for example our Google Calendar record contains just name, icon, etc. But details about an actual connection to Google Calendar are stored inside a PluginSetting record. Keep this in mind as you build your own server -- do you want to allow multiple connections to the same parent plugin? +This keeps our Plugins table immutable, for example Google Calendar is just a name, icon, and form field parameters. Meanwhile details about a _connection_ to Google Calendar are stored inside a PluginSetting record. Keep this in mind as you build your own server -- do you want to allow multiple connections to the same parent plugin? -TRMNL also supports PlaylistGroups. These are parent objects to playlists, and they simply act as buckets to which playlist items should be rendered on a device during any given time period. +TRMNL also offers a [Scheduler](https://app.gitbook.com/u/m0dkWlfTUdWGp1iNjs5aX2kHq1F3). This makes it easy to dictate conditions for when and why a given plugin is displayed on your device. -

Playlist Groups in action

+
Scheduler in action

Playlist scheduler in action

-This is another feature to consider building on your own implementation, but does not need to be considered at the device or firmware level. +Following our architecture is unnecessary for a self-hosted e-ink dashboard, but we do encourage you to check out those which have already been implemented in [BYOS clients](byos.md).