# 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)