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.
5.7 KiB
Universal Sync — how your devices stay in step
Sync is the promise that makes Bookhoard more than a web page: read on whatever is in your hands, and every other device catches up. One server holds the truth for each book — your position, bookmarks, highlights, and notes — and every registered device pushes and pulls against it.
Supported devices today
| Platform | Status | How it syncs |
|---|---|---|
| Web browser | ✅ Fully supported | Live, as you read — the reader saves position and annotations continuously |
| Android app | ✅ Fully supported | The native client: progress, highlights, bookmarks, notes; reads offline and queues changes until you are back online |
| KOReader (Kindle, Kobo, PocketBook) | ✅ Fully supported | The Bookhoard KOReader plugin, over Wi-Fi |
| Kobo, stock firmware | 🚧 Server support complete | The native Kobo protocol is implemented and documented server-side; device-side enablement is the remaining piece — Kobo Setup has the details |
Getting a device into the circle
- Connect the device to your server (each guide above walks its own path)
- Pair it on the Devices page — the Android app registers itself on first login; KOReader shows a 6-digit pairing code that you type into Pair a Device on the page
- Done. Sync starts as soon as a device is paired
Only the person holding the device can read its pairing code, so a device always lands in the account of whoever registered it — even on a family server where more than one person is logged in.
The Devices page is mission control: see every registered device and when it was last seen, remove a device (revoking its access instantly), and work through unlinked books — device files that could not be matched to a library book yet.
Book matching
When a device reports a book, Bookhoard tries to match it to your library by fingerprint, strongest first:
- Bookhoard UUID — 100% confidence
- OPF UUID — 95%
- SHA-256 hash — 90%
- OPF identifier — 85%
- ISBN / ASIN — 80%
- Title + Author + file size — 50%
- Title only — 30% (last resort, only tried when nothing else matched)
Books that match automatically never bother you. The ones that can't (side-loaded files, converted formats like EPUB → KEPUB, mismatched metadata) land in the device's unlinked books list, where you can:
- Auto-link everything above a confidence threshold
- Review suggestions first, then link
- Link by hand — pick the right library book yourself
What syncs
Reading progress — page, percentage, chapter position, EPUB CFI, last read time. EPUBs sync by percentage and CFI, PDFs and comics by page, so the same book lines up on devices with different page counts.
Highlights and notes — the highlighted text, your note, its color, and where it sits. Locations are stored in several forms at once (page, EPUB CFI, percentage, character offset), which is why a highlight made on your phone lands in the right place on an e-reader with different pagination.
Bookmarks — location, title, and when you made them.
Everything above is per-user and private: your devices see your data because you paired them, other users see theirs, and revoking a device ends its access on the spot.
Conflicts
If the same book is read on two devices close together, Bookhoard does not silently pick a winner — it records a sync conflict and shows it to you:
- The book's detail page grows a Sync Progress button (with a "Progress conflict detected" notice)
- The Conflicts page (
/conflicts) lists everything unresolved
Resolving means choosing a strategy: keep one side's progress, keep the server's current value, or let the furthest progress win. Until you resolve, the conflict stays listed — nothing is lost, it just waits for your call.
Offline reading
Devices keep working without the server. The Android app reads fully offline and queues your changes, draining the queue when you reconnect. E-readers push their progress on the next connection. The server holds a per-device queue for inbound work and retries failures automatically; if items pile up (a device offline for weeks), an admin can retry or clear a device's queue from the server side.
Reading history
Every reading session is logged — when, how long, on which device — and feeds your dashboard and stats. Your history is visible on the Progress page and on each book's detail page, and it is yours alone.
Troubleshooting
Progress not updating Check the device is still on the Devices page and was paired; check the server URL in the device's settings; confirm the device can reach the server (open the server URL in the device's browser as a test).
"Device not found" The device was removed or its token revoked — register it again and enter the fresh pairing code.
A conflict keeps coming back Two devices are genuinely fighting over the same book. Decide which device is the reader for that book, resolve with a strategy above, and avoid simultaneous reading of the same title.
High battery or data use That is the cost of continuous sync on a chatty device; e-reader plugins let you space out their sync checks from the plugin's own settings.
Device limits
Each account has a device limit — 10 by default, and administrators can raise or lower it per user. Removing a device you no longer use frees a slot.
More detail on any device lives in its guide: Android · KOReader · Kobo · Calibre import · and the filter rules that power matching-adjacent shelves like smart collections.