john-okeefe
54d0550dec
Replace the outdated Calibre-wireless/Basic-Auth instructions with the actual current flow: install the bookhoard.koplugin plugin, enter the server URL in the plugin menu, then approve the pending registration from Settings → Devices. Registration tokens are delivered to the plugin automatically after approval (5-minute expiry), so no credentials are ever typed on the device. Also document bidirectional sync of position, bookmarks, highlights (colors mapped between web and KOReader palettes), and notes, plus format-aware SHA-256 book matching, OPDS delivery, and trimmed troubleshooting sections covering the new registration flow.
197 lines
7.1 KiB
Markdown
197 lines
7.1 KiB
Markdown
# KOReader Device Setup Guide
|
|
|
|
This guide will help you set up KOReader on your e-reader device to sync with Bookhoard.
|
|
|
|
## 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, although Bookhoard's dedicated mobile apps (coming later) will be the better option there.
|
|
|
|
## 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 (for device approval)
|
|
- ✅ A KOReader-compatible e-reader device
|
|
- ✅ Your device connected to the same Wi-Fi network as your Bookhoard instance
|
|
|
|
## Installing KOReader
|
|
|
|
### Kindle Devices
|
|
|
|
1. **Install KOReader**
|
|
- Download the latest KOReader release from [koreader.rocks](https://koreader.rocks/)
|
|
- Extract the `koreader` folder to your Kindle's root directory
|
|
- Safely eject your Kindle from your computer
|
|
|
|
2. **Launch KOReader**
|
|
- On your Kindle, go to Home → Settings → Device Options → Personalize Your Kindle
|
|
- Select `koreader` from the launcher options
|
|
- Alternatively, you can use the `linkjail` method to access KOReader directly
|
|
|
|
3. **Enable Wi-Fi**
|
|
- In KOReader, tap the network icon in the top menu
|
|
- Connect to your Wi-Fi network
|
|
|
|
### Kobo Devices
|
|
|
|
1. **Install KOReader**
|
|
- Download the latest KOReader Kobo package from [koreader.rocks](https://koreader.rocks/)
|
|
- Copy the `koreader` folder to your Kobo's `.adds/` directory
|
|
- Safely eject your Kobo from your computer
|
|
|
|
2. **Launch KOReader**
|
|
- Eject and disconnect your Kobo
|
|
- Kobo will restart and you'll see KOReader as an option
|
|
- Alternatively, create a shortcut on your home screen
|
|
|
|
3. **Enable Wi-Fi**
|
|
- In KOReader, tap the network icon
|
|
- Connect to your Wi-Fi network
|
|
|
|
### PocketBook Devices
|
|
|
|
1. **Install KOReader**
|
|
- Download the PocketBook version from [koreader.rocks](https://koreader.rocks/)
|
|
- Copy to your device and install via the package manager
|
|
|
|
2. **Launch KOReader**
|
|
- Open KOReader from your apps menu
|
|
- Enable Wi-Fi in the network settings
|
|
|
|
## 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.
|
|
|
|
### Step 1: Install the Bookhoard Plugin
|
|
|
|
1. Clone the [Bookhoard KOReader plugin](https://git.linuxhg.com/Bookhoard/bookhoard.koplugin)
|
|
2. Copy it to your KOReader `plugins/` directory
|
|
3. Restart KOReader
|
|
|
|
### Step 2: Point the Plugin at Your Server
|
|
|
|
1. Open KOReader, tap the **wrench icon** at the top
|
|
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: Approve the Device in Bookhoard
|
|
|
|
1. On your computer or phone, open Bookhoard and go to **Settings → Devices**
|
|
2. Refresh the page — you'll see a **pending registration** for your device
|
|
3. Click **Approve** to connect the device
|
|
|
|
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.
|
|
|
|
> **Note:** Pending registrations expire after 5 minutes. If yours expires, just re-run the sync from the plugin menu and approve again.
|
|
|
|
### 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.
|
|
|
|
## What Syncs
|
|
|
|
Once connected, the following sync automatically in both directions between KOReader and Bookhoard (web and other devices):
|
|
|
|
- **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
|
|
|
|
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.
|
|
|
|
### 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 pending registration shows in Bookhoard
|
|
|
|
**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 — re-run the sync and approve quickly
|
|
|
|
### 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 Approval
|
|
|
|
**Problem**: Device shows as approved but changes don't appear in Bookhoard
|
|
|
|
**Solutions**:
|
|
|
|
- Trigger a manual sync from the plugin menu
|
|
- Check the device shows as enabled in **Settings → Devices**
|
|
- Verify the book appears in the device's Unlinked Books and link it if needed
|
|
- Check Bookhoard server logs for errors
|
|
|
|
### Conflicts Detected
|
|
|
|
**Problem**: Sync conflicts when reading the same book on multiple devices
|
|
|
|
**Solutions**:
|
|
|
|
1. Go to Bookhoard's **Conflicts** page
|
|
2. Review the progress reported by each device
|
|
3. Choose which device's progress to keep
|
|
|
|
## 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. **Device Authorization**: Only approve pending registrations you initiated
|
|
4. **Revoke lost devices**: Remove devices you no longer use from the Devices page
|
|
|
|
## Additional Resources
|
|
|
|
- [KOReader Documentation](https://github.com/koreader/koreader)
|
|
- [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
|