Crate trmnl 

trmnl

A BYOS (Bring Your Own Server) framework for TRMNL e-ink displays.

TRMNL devices can operate in two modes:

• Cloud mode: Device polls TRMNL’s servers, which poll your webhook
• BYOS mode: Device polls your server directly (this crate’s focus)

This crate provides everything you need to build a BYOS server:

• Protocol types that match firmware expectations
• Device info extraction from HTTP headers
• Optional axum integration for quick setup
• Optional HTML-to-PNG rendering via Chrome headless

Quick Start (axum)

use axum::{Router, routing::get};
use trmnl::{DisplayResponse, DeviceInfo};

async fn display(device: DeviceInfo) -> axum::Json<DisplayResponse> {
    println!("Request from device: {}", device.mac_address);

    axum::Json(DisplayResponse::new(
        "https://example.com/screen.png",
        "screen.png",
    ))
}

let app = Router::new()
    .route("/api/display", get(display));

Display Dimensions

TRMNL displays are 800x480 pixels. Images must be:

• Exactly 800x480 PNG
• Under 90KB (firmware rejects larger files)
• 16 colors or less for optimal e-ink rendering

BYOS Protocol

Your server must implement these endpoints:

Endpoint	Method	Purpose
/api/setup	GET	Device registration (optional)
/api/display	GET	Returns image URL and metadata
/api/log	POST	Receives device telemetry (optional)

The device sends these headers:

• ID: Device MAC address
• Battery-Voltage: Battery voltage (e.g., “4.2”)
• FW-Version: Firmware version
• RSSI: WiFi signal strength
• Refresh-Rate: Current refresh rate

Feature Flags

• axum - Axum extractors and handlers
• render - HTML to PNG rendering via Chrome headless
• schedule - Time-based refresh rate scheduling (YAML config)
• full - All features

Re-exports

pub use auth::TokenAuth;

pub use render::render_html_to_png;

pub use render::timestamped_filename;

pub use render::RenderConfig;

pub use schedule::get_global_refresh_rate;

pub use schedule::init_global_schedule;

pub use schedule::DaySelector;

pub use schedule::RefreshSchedule;

pub use schedule::ScheduleRule;

Modules

auth

Optional authentication for BYOS endpoints.

axum_ext

Axum integration for TRMNL BYOS servers.

render

HTML to PNG rendering for TRMNL displays.

schedule

Refresh rate scheduling based on time of day and day of week.

Structs

DeviceInfo

Device information extracted from HTTP headers.

DeviceStatusStamp

Device status snapshot in log entries.

DisplayResponse

Response for GET /api/display endpoint.

LogEntry

Log entry from device (POST /api/log).

LogResponse

Response for POST /api/log endpoint.

SetupResponse

Response for GET /api/setup endpoint.

Enums

Error

Errors that can occur when working with TRMNL.

Constants

BATTERY_MAX_MV

LiPo battery maximum voltage (100%)

BATTERY_MIN_MV

LiPo battery minimum voltage (0%)

DISPLAY_HEIGHT

TRMNL display height in pixels

DISPLAY_WIDTH

TRMNL display width in pixels

MAX_IMAGE_SIZE

Maximum image size in bytes (firmware rejects larger)

Functions

battery_percentage

Convert battery voltage (in millivolts) to percentage.