TRMNL Display Plugin for KOReader

Display your personalized TRMNL dashboard on your e-ink device.

A spiritual successor to the TRMNL Kindle Script.

Table of Contents

• TRMNL Display Plugin for KOReader
  • Table of Contents
  • Prerequisites
  • Quick Start
    • 1. Register Device
    • 2. Configure API Key
    • 3. Configure WiFi (Recommended)
    • 4. Fetch
  • Usage
  • Configuration
  • Troubleshooting
  • Learn More

Prerequisites

• KOReader-compatible device with KOReader installed
  • Kindle requires jailbreaking: instructions
• TRMNL BYOD license or BYOD/S setup

Quick Start

1. Register Device

1. Log in to trmnl.com
2. Click gear icon (⚙️) → BYOD device settings
3. Select your device model and add MAC address (find in KOReader: Menu → Network → Info)

2. Configure API Key

Option A: Create apikey.txt in plugins/trmnl.koplugin/ with your API key, then restart KOReader

Option B: In KOReader: Tools → TRMNL Display → Configure TRMNL

3. Configure WiFi (Recommended)

Settings → Network and set:

• "Action when Wi-Fi is off: turn on"
• "Action when done with Wi-Fi: turn off"

4. Fetch

Tools → TRMNL Display → Fetch screen now

Usage

• Manual fetch: Tools → TRMNL Display → Fetch screen now
• Auto-refresh mode: Tools → TRMNL Display → Enable auto-refresh (prevents sleep, refreshes every 30 min by default)
• Tap screen to close displayed image

Configuration

Access via Tools → TRMNL Display → Configure TRMNL

• API Key - Your TRMNL auth token
• Refresh Interval - Seconds between fetches (default: 1800)
• Use Server Refresh Interval - Let TRMNL control timing
• E-ink Refresh Type - UI (balanced), Full (best quality), Flash UI, or Partial (fastest)
• Show Status Notifications - Toggle info messages (errors always shown)

Troubleshooting

"API request failed (401/403)"

• Verify API key in settings
• Ensure device is registered at trmnl.com
• Check BYOD license is active

"Failed to reach TRMNL API"

• Check WiFi connection

Device keeps sleeping

• Use Enable auto-refresh (not "Fetch screen now")
• Disable "Auto-suspend timeout" in Settings → Device
• Use KOReader's "keep awake" feature to prevent sleep during refresh (Tools > More Tools > Page 2 > Keep alive)

Ghosting/unclear image

• Change E-ink refresh type to Full for better quality

Learn More

• DEVELOPMENT.md - Architecture, API details, development setup
• CONTRIBUTING.md - Code style, contribution workflow
• main.lua - Plugin implementation
• TRMNL API Docs - Official API reference

---

Made with love by the TRMNL team