Tutorial

This tutorial series will teach you how to create custom screens for your TRMNL device using Byonk. You’ll learn:

1. Your First Screen - Create a simple “Hello World” screen
2. Lua Scripting - Fetch data from APIs and process it
3. SVG Templates - Design beautiful layouts
4. Advanced Topics - HTML scraping, dynamic refresh, error handling

Prerequisites

Before starting, make sure you have:

• Byonk installed and running
• A text editor for writing Lua and SVG files
• Basic familiarity with programming concepts

Example Screens

Byonk comes with several example screens you can learn from. Each screen is a folder containing three fixed-name files — meta.yaml (title, description, and its params: schema), script.lua (the data-fetch logic), and screen.svg (the Tera template). Those folders live inside a package, and each screen is referenced by its qualified handle/path. A minimal default + calibration/* set ships in the embedded byonk-builtin package; the worked examples below ship separately in the embedded examples package:

Default Screen

A simple clock display showing time and date. Referenced as byonk-builtin/default.

screens/builtin/default/
├── meta.yaml     - Title, description, params
├── script.lua    - Script
└── screen.svg    - Template

Transit Departures

Real-time public transport departures from Swiss OpenData. Referenced as examples/swiss-departure-board.

screens/examples/swiss-departure-board/
├── meta.yaml     - Title, description, params
├── script.lua    - Fetches from transport.opendata.ch API
└── screen.svg    - Displays departure list with colors

Room Booking (Web Scrape)

Scrapes a web page to show room availability. Referenced as examples/webscrape.

screens/examples/webscrape/
├── meta.yaml     - Title, description, params
├── script.lua    - HTML scraping example
└── screen.svg    - Shows current/upcoming bookings

Display Color Test

Demonstrates the display palette colors available on e-ink. Referenced as byonk-builtin/calibration/grey.

screens/builtin/calibration/grey/
├── meta.yaml     - Title, description, params
├── script.lua    - Adapts to device palette
└── screen.svg    - Shows palette color swatches and dithering test

Quick Reference

File Locations

Workflow

1. Create a screen folder (meta.yaml + script.lua + screen.svg) inside a package
2. Assign the screen to a device by its handle/path reference in config.yaml
3. Test by refreshing your device or checking /swagger-ui

Tip: script.lua and screen.svg are loaded fresh on every request. Just save your changes and refresh!

Ready to Start?

Head to Your First Screen to create your first custom display!