trmnl/trmnl-koreader
0
0
Fork 0
mirror of https://github.com/usetrmnl/trmnl-koreader.git synced 2026-08-13 23:18:14 -07:00
Code Issues Packages Projects Releases Wiki Activity

Updated readme to absorb the FAQ and document current settings

Browse Source 
The FAQ answered the questions new users actually ask - how to install,
how to point at a private server, how to keep the battery alive - while
the readme covered the same ground more thinly and disagreed with it in
places. Two files competing to be the starting point served neither.

The merged document is ordered by what a user needs first, and fills the
gaps both had: the MAC address settings, the dispatcher actions that make
corner-tap fetching possible, and the API key regeneration that makes a
working device stop working the moment its MAC changes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ikraam Ghoor
2026-08-03 11:14:57 +02:00
co-authored by Claude Opus 5
parent 41479a9764
commit 7c8255137a
2 changed files with 69 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+69 -57
View File
@@ -1,98 +1,110 @@
# TRMNL Display Plugin for KOReader
Display your personalized [TRMNL](https://trmnl.app) dashboard on your e-ink device.
Turn a Kindle, Kobo, or any KOReader-compatible e-reader into a [TRMNL](https://trmnl.com) dashboard.
A spiritual successor to the [TRMNL Kindle Script](https://github.com/usetrmnl/trmnl-kindle).
## Table of Contents
## What You Need
- [TRMNL Display Plugin for KOReader](#trmnl-display-plugin-for-koreader)
- [Table of Contents](#table-of-contents)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [1. Register Device](#1-register-device)
- [2. Configure API Key](#2-configure-api-key)
- [3. Configure WiFi (Recommended)](#3-configure-wifi-recommended)
- [4. Fetch](#4-fetch)
- [Usage](#usage)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
- [Learn More](#learn-more)
- A KOReader-compatible device with [KOReader](https://github.com/koreader/koreader) installed
- Kindles need jailbreaking first: [instructions](https://github.com/usetrmnl/trmnl-kindle)
- A TRMNL [BYOD license](https://shop.trmnl.com/products/byod), a [BYOD/S setup](https://docs.trmnl.com/go/diy/byod-s), or your own BYOS server
## Prerequisites
## Install
- KOReader-compatible device with [KOReader](https://github.com/koreader/koreader) installed
- Kindle requires jailbreaking: [instructions](https://github.com/usetrmnl/trmnl-kindle)
- TRMNL [BYOD license](https://shop.trmnl.com/products/byod) or [BYOD/S setup](https://docs.trmnl.com/go/diy/byod-s)
1. Register your device at [trmnl.com](https://trmnl.com): gear icon (⚙️) → BYOD device settings. Pick a device model and enter your MAC address, which KOReader shows under **Menu → Network → Info**.
2. Download this repository (green **Code** button → **Download ZIP**) and unzip it.
3. Open `trmnl.koplugin/apikey.txt` and replace its contents with your device API key.
4. Copy the whole `trmnl.koplugin` folder into KOReader's `plugins/` directory. On a Kindle: connect over USB, open the mounted drive, and drop the folder into `/koreader/plugins/`.
5. Restart KOReader.
6. Open **Tools → TRMNL Display** to confirm the plugin loaded, then choose **Fetch screen now**.
## Quick Start
If the screen appears, you are done. Tap it (or press a button on non-touch devices) to dismiss it.
### 1. Register Device
## Run It as a Dashboard
1. Log in to [trmnl.com](https://trmnl.com)
2. Click gear icon (⚙️) → BYOD device settings
3. Select your device model and add MAC address (find in KOReader: **Menu → Network → Info**)
For a device that sits on a desk and updates itself:
### 2. Configure API Key
1. Stop KOReader from sleeping:
- **Tools → More tools → Keep alive** — enable
- **Settings → Device → Auto suspend timeout** — disable
2. **Tools → TRMNL Display → Enable auto-refresh**. The first fetch happens immediately, then repeats on your refresh interval.
3. Leave KOReader on that screen.
**Option A:** Create `apikey.txt` in `plugins/trmnl.koplugin/` with your API key, then restart KOReader
Tap the display to stop. To start again later, use **Start TRMNL (interactive)**.
**Option B:** In KOReader: **Tools → TRMNL Display → Configure TRMNL**
## Make the Battery Last
### 3. Configure WiFi (Recommended)
This is the difference between a few days and a few weeks of runtime.
**Settings → Network** and set:
- **Settings → Frontlight** — set to zero
- **Settings → Network:**
- Uncheck **Wi-Fi connection** so Wi-Fi is not permanently on
- **Action when Wi-Fi is off**: `turn on`
- **Action when done with Wi-Fi**: `turn off`
- Use a longer refresh interval. Every fetch wakes the radio and repaints the screen.
- Keep **E-ink refresh type** on **UI (balanced)**. Only switch to **Full** when image quality matters more than power.
- "Action when Wi-Fi is off: `turn on`"
- "Action when done with Wi-Fi: `turn off`"
## Settings
### 4. Fetch
**Tools → TRMNL Display → Configure TRMNL**
**Tools → TRMNL Display → Fetch screen now**
| Setting | What it does |
|---|---|
| **API Key** | Your device API token |
| **Base URL** | Server to fetch from. Defaults to `https://trmnl.app`; change it for BYOS |
| **Refresh Interval** | Seconds between fetches (default 1800) |
| **MAC address header name** | Header the MAC is sent under. Defaults to `ID`, which is what TRMNL and most BYOS servers expect |
| **MAC address** | Leave blank to auto-detect. Set it manually if detection fails or you need to send a specific value |
## Usage
Also in the **TRMNL Display** menu:
- **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
- **Use server refresh interval** — let the server's `refresh_rate` override your local interval. Recommended, since you can then retune timing from the dashboard without touching the device.
- **E-ink refresh type** — UI (balanced), Full (best quality), Flash UI, or Partial (fastest)
- **Show status notifications** — errors are always shown regardless
## Configuration
## Gestures
Access via **Tools → TRMNL Display → Configure TRMNL**
The plugin registers two actions with KOReader's dispatcher, so you can bind them to gestures, corner taps, or hardware keys via **Settings → Taps and gestures → Gesture manager**:
- **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)
- **TRMNL: Fetch now** — pull the next screen without opening menus
- **TRMNL: Start (interactive)**
Binding *Fetch now* to a corner tap is a fast way to page through dashboards.
## Using Your Own Server
Set **Base URL** to your server, for example `https://your-server.com`. The plugin calls `GET <base_url>/api/display` and expects a JSON body containing `image_url`, optionally with `refresh_rate` and `filename`.
Requests include the device MAC under the header named in **MAC address header name** (`ID` by default). [Terminus](https://github.com/usetrmnl/terminus) and `byos_laravel` both read `id`, so the default works as-is. If your server expects something else, change the header name rather than patching the plugin.
## Troubleshooting
**"API request failed (401/403)"**
**"Device not found", or fetches that stopped working after you changed the MAC address**
- Verify API key in settings
- Ensure device is registered at trmnl.com
- Check BYOD license is active
Changing a device's MAC address on trmnl.com **regenerates its API key**. Official firmware re-registers itself and picks up the new key automatically, but this plugin cannot. Go back into the device settings, copy the API key again, and paste the new one into the plugin.
**Other errors mentioning the server**
The plugin shows whatever the server reported. The same text is written to `koreader/crash.log`, which is the first place to look when reporting a problem.
**"Failed to reach TRMNL API"**
- Check WiFi connection
The request never got out. Check Wi-Fi, and check **Base URL** if you are on BYOS.
**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)
Use **Enable auto-refresh** rather than **Fetch screen now**, and apply the two sleep settings under [Run It as a Dashboard](#run-it-as-a-dashboard).
**Ghosting/unclear image**
- Change E-ink refresh type to **Full** for better quality
**Ghosting or a muddy image**
Set **E-ink refresh type** to **Full**.
## Learn More
- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Architecture, API details, development setup
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Code style, contribution workflow
- **[main.lua](trmnl.koplugin/main.lua)** - Plugin implementation
- **[TRMNL API Docs](https://trmnl.com/developers)** - Official API reference
- **[DEVELOPMENT.md](DEVELOPMENT.md)** — architecture, API details, development setup
- **[CONTRIBUTING.md](CONTRIBUTING.md)** — code style and contribution workflow
- **[TRMNL API Docs](https://trmnl.com/developers)** — official API reference
---
faq.md
-58
View File
@@ -1,58 +0,0 @@
# Frequently Asked Questions
This FAQ answers four common questions. It describes how to:
1. Install the plugin
2. Configure the plugin
3. Run the plugin
4. Extend battery runtime
## How do I install this plugin in KOReader?
1. Replace the text in `trmnl.koplugin/apikey.txt` with your API key.
2. Copy the entire `trmnl.koplugin` folder (now containing your `apikey.txt`) into your KOReader `plugins/` directory. Typical Kindle workflow: connect the Kindle to your computer via USB, open the mounted Kindle drive, and drag and drop `trmnl.koplugin` into `/koreader/plugins/`.
3. Restart KOReader.
4. Open **Tools -> TRMNL Display** to verify the plugin loaded.
## How do I configure this plugin to work with my own server?
Use **Tools -> TRMNL Display -> Configure TRMNL** and set:
- **API Key**: your server token (change only if needed)
- **Base URL**: your server URL (for example: `https://your-server.com`)
- **Refresh Interval**: optional manual interval in seconds
The plugin calls `GET <base_url>/api/display`, so your server should expose a compatible endpoint.
Refresh interval precedence:
- By default, the manual **Refresh Interval** on the device is used.
- If **Use server refresh interval** is enabled and the server returns a valid `refresh_rate`, the server value overrides the manual one.
Recommended workflow: enable **Use server refresh interval** so you can adjust timing from your server or dashboard without changing Kindle settings.
## How do I run the plugin to turn my Kindle into a TRMNL?
In KOReader, make sure sleep prevention is enabled so the device stays awake while acting as a dashboard. I changed two settings:
1. **Tools -> More tools -> Keep alive** (enable it).
2. **Settings -> Device -> Auto suspend timeout** (disable it).
Once configured, open **Tools -> TRMNL Display** and:
1. Enable **Auto refresh**. The first time you enable it, the plugin automatically fetches and displays the current screen.
2. Leave KOReader open on that screen to use the Kindle as a passive dashboard.
To stop the plugin, tap the display. To restart it after auto-refresh has been enabled, use **Start TRMNL (interactive)**.
If **Use server refresh interval** is enabled, the server-provided `refresh_rate` controls update timing. Otherwise, the device's local **Refresh Interval** setting is used.
## What can I do to extend battery runtime?
- Set **Settings -> Frontlight** to zero.
- Set the following in KOReader under **Settings -> Network**:
- Uncheck **Wi-Fi connection** (do not keep Wi-Fi permanently on).
- **Action when Wi-Fi is off**: `turn on`
- **Action when done with Wi-Fi**: `turn off`
- Use a longer refresh interval to reduce Wi-Fi activity and screen updates. If you enable **Use server refresh interval**, make sure your server returns a sensible refresh rate (not too aggressive).
- Set **E-ink refresh type** to **UI (balanced)** for normal use; switch it to **Full** only when image quality is more important than power.