John O'Keefe
5211edf264
The setup guides walked the retired broadcast-list approve ("your device
appears under Pending Device Registrations — click Approve"), which no
longer exists. Both now describe the pairing-code flow: the e-reader
displays a 6-digit code, you type it into Pair a Device on your own
account, and only whoever holds the device can read the code — the
family-server gap that motivated the change. Adds a Pairing Code Not
Accepted troubleshooting case, refreshes the security practices
(claim only codes you can see on a device you are holding), and aligns
the remaining approval/pending wording throughout.
302 lines
12 KiB
Markdown
302 lines
12 KiB
Markdown
<!-- Ground truth: bookhoard.koplugin main.lua (menu tree, defaults, pairing
|
|
flow) + the server-side koreader endpoints. Re-verify against the plugin
|
|
source when the plugin changes. KOReader ITSELF is out of scope: this
|
|
guide supports the plugin only, and installation is delegated to the
|
|
KOReader project's own documentation (README #installation, verified
|
|
2026-11-02 — per-device wiki pages for Android, Kindle, Kobo,
|
|
PocketBook, reMarkable, and more). -->
|
|
|
|
# KOReader Device Setup Guide
|
|
|
|
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. One scope note up front: this guide is
|
|
about the **Bookhoard sync plugin**. Installing KOReader itself is a
|
|
different project's documentation, covered below.
|
|
|
|
## What is KOReader?
|
|
|
|
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 — though on Android the dedicated
|
|
[Bookhoard app](android-app.md) is the better option.
|
|
|
|
## Prerequisites
|
|
|
|
Before you begin, make sure you have:
|
|
|
|
- ✅ A Bookhoard instance running and accessible on your network
|
|
- ✅ A web browser logged in to your Bookhoard account (to enter the pairing code)
|
|
- ✅ KOReader installed and running on your e-reader (see next section)
|
|
- ✅ Your device connected to the same Wi-Fi network as your Bookhoard instance
|
|
|
|
## Installing KOReader
|
|
|
|
One honest note first: **Bookhoard supports the Bookhoard sync plugin —
|
|
not KOReader itself.** Getting KOReader onto an e-reader usually involves
|
|
device-specific steps (jailbreaks, alternative launchers, one-click
|
|
packages) that vary by model and firmware. That's the KOReader project's
|
|
domain, not ours — we can't tell you how to modify your particular device,
|
|
and we won't pretend otherwise with half-remembered instructions.
|
|
|
|
The good news: KOReader documents this properly. Their installation guide
|
|
routes you to model-specific steps for Android, Kindle, Kobo, PocketBook,
|
|
reMarkable, and more:
|
|
|
|
**→ [KOReader installation guide](https://github.com/koreader/koreader#installation)**
|
|
|
|
Once KOReader itself is installed and running, everything below applies,
|
|
whatever device you're on.
|
|
|
|
## Connecting KOReader to Bookhoard
|
|
|
|
Setup is done **on the server**: your e-reader shows a pairing code, and you
|
|
type it into your own account's Devices page — no usernames, passwords, or
|
|
tokens to type on the device.
|
|
|
|
### Step 1: Install the Bookhoard Plugin
|
|
|
|
Installation is a git clone straight into your KOReader `plugins/` folder —
|
|
no download-and-copy step:
|
|
|
|
```bash
|
|
cd koreader/plugins # .adds/koreader/plugins on Kobo
|
|
git clone https://git.linuxhg.com/Bookhoard/bookhoard.koplugin
|
|
```
|
|
|
|
Then restart KOReader.
|
|
|
|
**Updating later** is the same, smaller: in the `bookhoard.koplugin` folder,
|
|
`git pull`, then restart KOReader.
|
|
|
|
### Step 2: Point the Plugin at Your Server
|
|
|
|
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**:
|
|
|
|
```
|
|
http://YOUR_COMPUTER_IP:8765
|
|
```
|
|
|
|
Use your server's LAN IP (or domain if you have one configured).
|
|
|
|
### Step 3: Register the Device
|
|
|
|
1. In the same **Bookhoard sync** menu, tap **Register device**
|
|
2. Your e-reader displays a **6-digit pairing code**
|
|
3. On your computer or phone, open Bookhoard — logged into **your** account —
|
|
and go to the **Devices** page (sidebar navigation)
|
|
4. Type the code into the **Pair a Device** field and click **Find device**,
|
|
then confirm on the card that appears
|
|
|
|
The code is the only way to claim the registration, and only someone holding
|
|
the device can read it — so the device always lands in the account of the
|
|
person who registered it. The plugin waits on the device and finishes by
|
|
itself the moment you confirm. Once paired, 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:** Pairing codes expire after 5 minutes. If yours expires
|
|
> ("Registration expired"), just tap **Register device** again for a fresh
|
|
> one. Dismissing the waiting dialog on the device cancels the attempt.
|
|
|
|
### Auth Token (Advanced)
|
|
|
|
The Devices page shows each KOReader device's **Auth Token**. You normally
|
|
never need it (the plugin receives it automatically during pairing), 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 pairing 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 pairing, 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 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
|
|
- **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.
|
|
|
|
## OPDS Wireless Book Delivery
|
|
|
|
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
|
|
|
|
1. In KOReader, open the OPDS catalog list and tap **Bookhoard**
|
|
2. Browse your library: all books, collections, and recent additions
|
|
3. Tap a book to see details and **Download** it
|
|
|
|
### Supported Formats
|
|
|
|
- **EPUB**: Standard ebook format
|
|
- **KEPUB**: Kobo-optimized format
|
|
- **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.
|
|
|
|
## Troubleshooting
|
|
|
|
### Pending Registration Never Appears
|
|
|
|
**Problem**: You entered the Server URL, but no pairing code shows on the device
|
|
|
|
**Solutions**:
|
|
|
|
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 — tap **Register device** again
|
|
|
|
### Pairing Code Not Accepted
|
|
|
|
**Problem**: The Devices page says "No waiting device matches that code"
|
|
|
|
**Solutions**:
|
|
|
|
1. Re-read the code on the device — it refreshes on every **Register device** tap
|
|
2. Check you typed all 6 digits (spacing doesn't matter)
|
|
3. Codes expire after 5 minutes — register again on the device and type the new code
|
|
4. "Pairing code already used" means the device already paired (check the device list); otherwise register again
|
|
5. Too many attempts lock new tries for a minute — wait and retry
|
|
|
|
### Connection Refused
|
|
|
|
**Problem**: "Connection refused" error on the device
|
|
|
|
**Solutions**:
|
|
|
|
- Verify Bookhoard is running
|
|
- Check the server address and port (default `8765`)
|
|
- Ensure the device is on the same Wi-Fi network as the server
|
|
- Use the server's LAN IP instead of `localhost`
|
|
|
|
### Sync Not Working After Pairing
|
|
|
|
**Problem**: Device shows as paired but changes don't appear in Bookhoard
|
|
|
|
**Solutions**:
|
|
|
|
- **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
|
|
|
|
**Solutions**:
|
|
|
|
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 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
|
|
|
|
1. **Use HTTPS**: If exposing Bookhoard beyond your LAN, configure SSL/TLS
|
|
2. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3)
|
|
3. **Claim only codes you can see**: a pairing code is readable only on the
|
|
registering device's screen — never claim a code someone merely told you
|
|
if you can't see the device showing it
|
|
4. **Revoke lost devices**: Remove devices you no longer use from the Devices page
|
|
|
|
## Additional Resources
|
|
|
|
- [KOReader](https://github.com/koreader/koreader) — [installation](https://github.com/koreader/koreader#installation) · [user guide](https://koreader.rocks/user_guide/)
|
|
- [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=276) — the project's official Mobileread subforum
|
|
- [Bookhoard Universal Sync Guide](../sync-guide.md)
|
|
- [Bookhoard KOReader Plugin](https://git.linuxhg.com/Bookhoard/bookhoard.koplugin)
|