Bookhoard/bookhoard
0
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 69 Wiki Activity

docs(user): koreader-setup — document the actual plugin menu from source

Browse Source 
The guide documented setup and stopped. Everything after 'approved' was
undocumented: the real menu tree from bookhoard.koplugin main.lua is now
in the guide — one-tap actions (Push progress / Pull progress / Sync
rating, review & time now / Setup OPDS catalog / Device info /
Disconnect / Register device), Automatically push progress (DEFAULTS
OFF — the likely cause of 'sync not working after approval' reports),
Periodically sync every # pages (default 50), Sync mode
(Immediate/Checkpoint), Sync behavior (Sync to a newer state default
Prompt / to an older state default Never — the device-side side of
conflict handling), and the seven What to sync toggles (progress,
bookmarks, highlights, notes, ratings, review, reading time — all on by
default; the ratings/review/reading-time sync was entirely missing from
docs despite the six server endpoints).

Also fixed: Android 'coming later' line now points at the real app,
OPDS auto-registration verified in the approval poll (setupOPDS on
approved), expiry wording, and a troubleshooting entry for the
wifi-toggle permission message auto-sync can raise. Ground truth noted
in a source comment; verify against plugin source on plugin changes.
This commit is contained in:
John O'Keefe committed 2026-11-02 10:23:52 -05:00
1 parent 788e9463cf
commit 9b2d3da7e2
1 file changed
+122 -25
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/devices/koreader-setup.md
+122 -25
View File
@@ -1,16 +1,24 @@
<!-- Ground truth: bookhoard.koplugin main.lua (menu tree, defaults, approval
flow) + the server-side koreader endpoints. Re-verify against the plugin
source when the plugin changes. -->
# KOReader Device Setup Guide
This guide will help you set up KOReader on your e-reader device to sync with Bookhoard.
This guide will help you set up KOReader on your e-reader device to sync with
Bookhoard — reading position, bookmarks, highlights, notes, and even your
ratings, reviews, and reading time.
## What is KOReader?
KOReader is an open-source e-reader application that supports a wide range of e-reader devices including:
KOReader is an open-source e-reader application that supports a wide range of
e-reader devices including:
- Kindle devices (Paperwhite, Oasis, Voyage, etc.)
- Kobo devices (Clara, Aura, Nia, etc.)
- PocketBook devices
It also runs on Android tablets and phones, although Bookhoard's dedicated mobile apps (coming later) will be the better option there.
It also runs on Android tablets and phones — though on Android the dedicated
[Bookhoard app](android-app.md) is the better option.
## Prerequisites
@@ -67,7 +75,8 @@ Before you begin, make sure you have:
## Connecting KOReader to Bookhoard
Setup is done **on the server**: you approve the device from the Bookhoard web interface — no usernames, passwords, or tokens to type on the device.
Setup is done **on the server**: you approve the device from the Bookhoard
web interface — no usernames, passwords, or tokens to type on the device.
### Step 1: Install the Bookhoard Plugin
@@ -77,7 +86,7 @@ Setup is done **on the server**: you approve the device from the Bookhoard web i
### Step 2: Point the Plugin at Your Server
1. Open KOReader, tap the **wrench icon** at the top
1. Open KOReader, tap the **wrench icon** at the top (the tools menu)
2. Find and tap **Bookhoard sync**
3. Tap **Server URL**, enter your server address, then tap **OK**:
@@ -87,34 +96,116 @@ Setup is done **on the server**: you approve the device from the Bookhoard web i
Use your server's LAN IP (or domain if you have one configured).
### Step 3: Approve the Device in Bookhoard
### Step 3: Register the Device
1. On your computer or phone, open Bookhoard and go to the **Devices** page (sidebar navigation)
2. Refresh the page — your device appears under **Pending Device Registrations**
3. Click **Approve** to connect the device
1. In the same **Bookhoard sync** menu, tap **Register device**
2. On your computer or phone, open Bookhoard and go to the **Devices** page
(sidebar navigation)
3. Your device appears under **Pending Device Registrations** — click
**Approve** to connect it
Once approved, the plugin picks up its credentials automatically — reading progress sync and OPDS catalog access are set up automatically. No further configuration is needed.
The plugin waits on the device and finishes by itself the moment you
approve. Once approved, its credentials are stored automatically, sync
events are armed, and Bookhoard's OPDS catalog is added to your KOReader —
no further configuration is needed.
> **Note:** Pending registrations expire after 5 minutes. If yours expires, just re-run the sync from the plugin menu and approve again.
> **Note:** Pending registrations expire after 5 minutes. If yours expires
> ("Registration expired"), just tap **Register device** again and approve.
### Auth Token (Advanced)
The Devices page shows each KOReader device's **Auth Token**. You normally never need it (the plugin receives it automatically during approval), but it can be re-entered manually in the plugin settings if you're moving a setup between devices or debugging.
The Devices page shows each KOReader device's **Auth Token**. You normally
never need it (the plugin receives it automatically during approval), but it
can be re-entered manually in the plugin settings if you're moving a setup
between devices or debugging.
## The Bookhoard sync menu
Everything the plugin can do lives in one place: **wrench icon → Bookhoard
sync**. The menu changes shape depending on whether you are connected.
### Before you're connected
- **Server URL** — your server's address
- **Register device** — starts the approval flow above
### Once connected — one-tap actions
| Menu item | What it does |
| --- | --- |
| **Push progress from this device** | Force-push this device's position to the server |
| **Pull progress from server** | Force-pull the server's position onto this device |
| **Sync rating, review & time now** | Push your rating, review, and accumulated reading time for the current book immediately |
| **Setup OPDS catalog** | (Re-)adds Bookhoard's catalog to KOReader's OPDS list — normally done for you at approval |
| **Device info** | Shows this device's ID and the server it talks to |
| **Disconnect** | Forgets the device's credentials (after a confirmation) |
### Automatically push progress
This toggle is the on/off switch for background sync — **it starts off**, so
after approval, turn it on to get automatic syncing. With it on, progress
pushes as you read and on close/suspend; the plugin may prompt about turning
Wi-Fi on at those moments depending on your device.
Two related settings sit under it:
- **Periodically sync every # pages** — how many page turns between updates
(default 50; set 0 to disable periodic updates)
- **Sync mode** — **Immediate** pushes right away, **Checkpoint** batches
changes for slower connections or battery saving
### Sync behavior — who wins when states differ
These two settings decide what the device does when its progress and the
server's disagree, without you opening the Conflicts page:
- **Sync to a newer state** — the server has *newer* progress than this
device (default **Prompt**: the device asks before adopting it; alternatives
are **Silently** or **Never**)
- **Sync to an older state** — this device has *newer* progress than the
server (default **Never**: the device never rolls itself back)
Set both to **Silently** for hands-off syncing, or leave the defaults if you
want a say whenever progress would move.
### What to sync
Seven toggles, all on by default, each controlling one kind of data:
- **Reading progress**
- **Bookmarks**
- **Highlights**
- **Notes**
- **Ratings** — your book ratings made in KOReader
- **Book review** — your review text
- **Reading time** — time-spent statistics
Turn off anything you'd rather keep local; the rest keeps flowing both ways.
## What Syncs
Once connected, the following sync automatically in both directions between KOReader and Bookhoard (web and other devices):
Once connected and enabled, the following sync in both directions between
KOReader and Bookhoard (web, Android, and other devices), each governed by
its toggle above:
- **Reading position** — percentage, chapter, and EPUB CFI where available
- **Bookmarks**
- **Highlights** — including highlight colors, mapped between the web and KOReader palettes
- **Highlights** — including highlight colors, mapped between the web and
KOReader palettes
- **Notes** — standalone and attached to highlights
- **Ratings, review, and reading time** — pushed to the server (push any
time from the menu with **Sync rating, review & time now**)
Books are matched automatically using UUIDs, file hashes (SHA-256, format-aware so converted files still match), file aliases, and title/author fallback. If a book can't be matched, it shows up under the device's **Unlinked Books** in Bookhoard, where you can link it manually.
Books are matched automatically using UUIDs, file hashes (SHA-256,
format-aware so converted files still match), file aliases, and
title/author fallback. If a book can't be matched, it shows up under the
device's **Unlinked Books** in Bookhoard, where you can link it manually.
## OPDS Wireless Book Delivery
Once your device is approved, the plugin also registers Bookhoard's OPDS catalog, so you can browse and download books wirelessly — no USB cable needed.
At approval the plugin adds Bookhoard's OPDS catalog to KOReader (and
**Setup OPDS catalog** re-adds it any time), so you can browse and download
books wirelessly — no USB cable needed.
### Browse and Download Books
@@ -129,7 +220,8 @@ Once your device is approved, the plugin also registers Bookhoard's OPDS catalog
- **PDF**: Fixed-layout documents
- **CBZ**: Comic book archives
Books downloaded via OPDS are automatically matched to your library, so their progress syncs from the first page.
Books downloaded via OPDS are automatically matched to your library, so
their progress syncs from the first page.
## Troubleshooting
@@ -142,7 +234,7 @@ Books downloaded via OPDS are automatically matched to your library, so their pr
1. Verify the Server URL is correct (no trailing path — just the base address)
2. Make sure KOReader is connected to Wi-Fi
3. Check the Bookhoard server is reachable from the device's network
4. Registrations expire after 5 minutes — re-run the sync and approve quickly
4. Registrations expire after 5 minutes — tap **Register device** again and approve quickly
### Connection Refused
@@ -161,11 +253,18 @@ Books downloaded via OPDS are automatically matched to your library, so their pr
**Solutions**:
- Trigger a manual sync from the plugin menu
- **Automatically push progress** defaults to off — turn it on in the menu, or push once with **Push progress from this device**
- Check the device shows as enabled on the **Devices** page (open its settings from the icon next to the device)
- Verify the book appears as an unlinked book for the device and link it if needed
- Check Bookhoard server logs for errors
### Turning on auto-sync asks about Wi-Fi
If enabling **Automatically push progress** shows a message about
**"Action when Wi-Fi is off"**, open KOReader's Network settings and set
that action to **turn on** — auto-sync needs permission to bring Wi-Fi up by
itself.
### Conflicts Detected
**Problem**: Sync conflicts when reading the same book on multiple devices
@@ -174,7 +273,10 @@ Books downloaded via OPDS are automatically matched to your library, so their pr
1. Open the book's detail page and click **Sync Progress**, or open the Conflicts page (`/conflicts`)
2. Review the progress reported by each device
3. Choose which device's progress to keep
3. Choose a resolution: keep one side's progress, keep the server's, or let the furthest progress win
For day-to-day control of the same question on the device itself, use the
**Sync behavior** settings (newer state / older state).
## Security Best Practices
@@ -189,8 +291,3 @@ Books downloaded via OPDS are automatically matched to your library, so their pr
- [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271)
- [Bookhoard Universal Sync Guide](../sync-guide.md)
- [Bookhoard KOReader Plugin](https://git.linuxhg.com/Bookhoard/bookhoard.koplugin)
---
**Last Updated**: August 2026
**Bookhoard Version**: 1.0