diff --git a/docs/user/devices/koreader-setup.md b/docs/user/devices/koreader-setup.md index dc996fb9..b20a64ee 100644 --- a/docs/user/devices/koreader-setup.md +++ b/docs/user/devices/koreader-setup.md @@ -1,16 +1,24 @@ + + # 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