diff --git a/docs/user/devices/koreader-setup.md b/docs/user/devices/koreader-setup.md index 8245d3b..6961ddd 100644 --- a/docs/user/devices/koreader-setup.md +++ b/docs/user/devices/koreader-setup.md @@ -9,18 +9,19 @@ KOReader is an open-source e-reader application that supports a wide range of e- - Kindle devices (Paperwhite, Oasis, Voyage, etc.) - Kobo devices (Clara, Aura, Nia, etc.) - PocketBook devices -- Android tablets and phones + +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 -- ✅ Your Bookhoard credentials (username and password) +- ✅ 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 -## Installation +## Installing KOReader ### Kindle Devices @@ -64,469 +65,132 @@ Before you begin, make sure you have: - Open KOReader from your apps menu - Enable Wi-Fi in the network settings -## Device Registration +## Connecting KOReader to Bookhoard -### Step 1: Get Your Bookhoard Instance URL +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. -Find your Bookhoard instance URL. This will typically be one of: +### Step 1: Install the Bookhoard Plugin -- **Local Network**: `http://YOUR_COMPUTER_IP:8765` -- **Localhost (if testing)**: `http://localhost:8765` -- **Domain (if configured)**: `https://bookhoard.yourdomain.com` +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: Register Your Device in Bookhoard +### Step 2: Point the Plugin at Your Server -1. Log in to your Bookhoard web interface -2. Navigate to **Device Management** → **Add New Device** -3. Fill in the device details: - - **Device Name**: A friendly name (e.g., "My Kindle Paperwhite") - - **Device Type**: Select "KOReader" - - **Device Identifier**: Enter your device's hardware ID or serial number - - On Kindle: Settings → Device Options → Device Info → Serial Number - - On Kobo: Settings → Device Information → Serial Number -4. Click **Register Device** - -You'll receive: - -- An **Auth URL** to approve the device -- A **Device Token** (automatically generated after approval) - -### Step 3: Approve Your Device - -1. **Method A: QR Code** - - If displayed, scan the QR code with your phone's camera - - This will open the approval page in your browser - - Log in and click **Approve** - -2. **Method B: Manual URL** - - Copy the Auth URL from the registration confirmation - - Open it in your web browser - - Log in to your Bookhoard account - - Click **Approve Device** - -Your device is now registered and ready to sync! - -## Configure KOReader Sync - -### Step 1: Access KOReader Settings - -1. Open KOReader on your device -2. Tap the menu icon (≡) in the top-left corner -3. Select **Tools** → **Calibre** - -### Step 2: Configure Wireless Connection - -1. **Enable Calibre Wireless Connection**: Toggle ON -2. **Server Address**: Enter your Bookhoard instance URL +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/api/sync/koreader + http://YOUR_COMPUTER_IP:8765 ``` - Replace `YOUR_COMPUTER_IP` with your actual IP address + Use your server's LAN IP (or domain if you have one configured). -3. **Set Custom Port** (if needed): Keep default or enter `8765` +### Step 3: Approve the Device in Bookhoard -### Step 3: Configure Authentication +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 -1. **Authentication Method**: Select "Basic Auth" -2. **Username**: Your Bookhoard email or username -3. **Password**: Your Bookhoard password +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. -### Step 4: Configure Sync Settings +> **Note:** Pending registrations expire after 5 minutes. If yours expires, just re-run the sync from the plugin menu and approve again. -1. **Auto Sync**: Enable for automatic sync -2. **Sync Frequency**: Choose from: - - Every page turn (recommended for real-time sync) - - Every bookmark save - - Every highlight - - Manual only (sync when you press the sync button) +### Auth Token (Advanced) -3. **What to Sync**: Enable: - - ✅ Reading progress - - ✅ Bookmarks - - ✅ Highlights - - ✅ Notes +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. -### Step 5: Test Connection +## What Syncs -1. Tap **Test Connection** in the Calibre settings -2. You should see a success message if configured correctly -3. If it fails: - - Verify your device is connected to Wi-Fi - - Check the server URL is correct - - Ensure your Bookhoard instance is running - - Verify username and password are correct +Once connected, the following sync automatically in both directions between KOReader and Bookhoard (web and other devices): -## Using Sync Features +- **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 -### Initial Sync - -When you first enable sync, KOReader will: - -1. Connect to Bookhoard -2. Upload your current reading progress -3. Download any annotations from the server -4. Set up bidirectional sync for future changes - -### Reading Progress Sync - -As you read: - -- Progress updates automatically sync based on your sync frequency -- Page turns, chapter changes, and bookmark saves all trigger sync -- Sync occurs in the background without interrupting reading - -### Annotations Sync - -- **Bookmarks**: Sync when created or deleted -- **Highlights**: Sync when created, edited, or deleted -- **Notes**: Sync when created, edited, or deleted -- **Linked Notes**: Notes attached to highlights sync together - -### Manual Sync - -To manually trigger a sync: - -1. Open the KOReader menu (≡) -2. Select **Tools** → **Calibre** -3. Tap **Sync Now** - -The sync status will display: - -- 🟢 **Synced** - All changes uploaded -- 🟡 **Syncing...** - In progress -- 🔴 **Failed** - Check your network connection - -## Advanced Configuration - -### Offline Mode - -KOReader automatically handles offline scenarios: - -1. Changes are queued locally when offline -2. Auto-sync resumes when connected -3. Queue processes all pending changes in priority order - -### Checkpoint Sync - -For better battery life, use checkpoint mode: - -1. In KOReader Calibre settings -2. Set **Sync Mode** to "Checkpoint" -3. Set **Checkpoint Interval** (e.g., every 5 minutes) -4. Syncs occur in batches instead of every action - -### Debug Mode - -Enable debug logging if sync isn't working: - -1. KOReader menu → Tools → Calibre -2. Enable **Debug Logging** -3. Sync and check logs at `/mnt/us/koreader/calibre.log` +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 -### What is OPDS? - -OPDS (Open Publication Distribution System) allows your KOReader device to **wirelessly download books** from Bookhoard - no USB cable needed! - -### OPDS Benefits - -- **Wireless Downloads**: Browse and download books over Wi-Fi -- **On-Demand Access**: Your entire library at your fingertips -- **Collection Support**: Browse and download from specific collections -- **Automatic Progress Sync**: Downloaded books sync progress instantly -- **Format Support**: EPUB, KEPUB, PDF, and more - -### Enable OPDS in KOReader - -#### Step 1: Get Your OPDS URL - -1. Log in to Bookhoard web interface -2. Go to **Device Management** -3. Find your registered KOReader device -4. Click **Show OPDS URL** -5. Copy the URL (format: `http://YOUR_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog`) - -#### Step 2: Add OPDS Catalog in KOReader - -1. Open KOReader on your device -2. Tap the **+** (plus) button on the home screen -3. Select **OPDS Catalog** -4. Enter catalog details: - - **Name**: Bookhoard (or any name you prefer) - - **URL**: Paste your OPDS URL from Step 1 -5. Tap **Save** - -Your Bookhoard library now appears in KOReader's home screen! +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 -#### Browse Your Library +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 -1. Tap **Bookhoard** on KOReader home screen -2. You'll see: - - **All Books**: Complete library view - - **Collections**: Books organized by collections - - **Recent**: Latest additions -3. Tap any category to browse - -#### Download a Book - -1. Browse to find a book -2. Tap the book to see details -3. Tap **Download** -4. Progress bar shows download status -5. Book opens automatically when complete - -#### Download Entire Collections - -1. In Bookhoard catalog, tap **Collections** -2. Select a collection -3. Tap **Download All** to get all books -4. Downloads queue and process in background - -### OPDS Features - -#### Supported Formats - -KOReader OPDS supports: +### Supported Formats - **EPUB**: Standard ebook format -- **KEPUB**: Kobo-optimized format (KOReader handles this well) +- **KEPUB**: Kobo-optimized format - **PDF**: Fixed-layout documents - **CBZ**: Comic book archives -- **TXT**: Plain text files -- **RTF**: Rich text format -#### Automatic Book Matching - -Books downloaded via OPDS are automatically matched: - -- Uses SHA-256 hashes for precise matching -- Falls back to title/author matching -- Links to your existing Bookhoard library -- Progress syncs automatically - -#### Collection Integration - -Your Bookhoard collections appear in KOReader: - -- Collection **"To Read"** → KOReader category -- Collection **"Science Fiction"** → Browseable section -- Custom collections → Preserved organization - -### KOReader OPDS Settings - -#### Update Interval - -Configure how often KOReader checks for new books: - -1. KOReader menu → Tools → OPDS -2. Set **Update Interval**: 5min, 15min, 1hr, manual -3. **Recommended**: 15min for balance - -#### Download Location - -Choose where to store downloaded books: - -1. KOReader menu → File Browser -2. Set **Default Download Folder** -3. **Recommended**: `/mnt/us/Documents/` (Kindle) or `/mnt/onboard/Documents/` (Kobo) - -#### Auto-Download - -Automatically download new books from collections: - -1. KOReader menu → Tools → OPDS -2. Enable **Auto-Download New Books** -3. Select collections to monitor -4. New books download automatically when connected to Wi-Fi - -### OPDS Troubleshooting - -#### Catalog Not Loading - -**Problem**: Bookhoard catalog shows error or won't load - -**Solutions**: - -1. Verify device is connected to Wi-Fi -2. Check OPDS URL is correct in settings -3. Try accessing OPDS URL in your browser -4. Ensure Bookhoard server is running -5. Check Bookhoard device is approved - -#### Download Fails - -**Problem**: Book download starts but fails - -**Solutions**: - -1. Check Wi-Fi signal strength -2. Ensure sufficient storage on device -3. Try downloading a smaller book -4. Check Bookhoard has the book file -5. Review Bookhoard logs for errors - -#### Book Opens But Progress Doesn't Sync - -**Problem**: Downloaded book doesn't sync progress - -**Solutions**: - -1. Verify book is matched to Bookhoard library -2. Check device sync settings are enabled -3. Try manual sync from device -4. Ensure book exists in Bookhoard with same hash -5. Check Bookhoard Progress page - -#### Slow Downloads - -**Problem**: Books take too long to download - -**Solutions**: - -1. Stay close to Wi-Fi router -2. Use 5GHz Wi-Fi if available -3. Close other apps using bandwidth -4. Download smaller books first -5. Consider USB for large books (100MB+) - -### Advanced OPDS Configuration - -#### Custom User-Agent - -Some OPDS catalogs require specific user agent: - -```lua --- In KOReader settings -OPDSUserAgent = "KOReader/2024.01" -``` - -#### Authentication Token - -If Bookhoard requires token authentication: - -1. Get token from Bookhoard device settings -2. Add to OPDS URL: `?token=YOUR_TOKEN` -3. KOReader includes token in all requests - -#### Compression - -Enable compression for faster downloads: - -```lua --- In KOReader settings -OPDSCompressionEnabled = true -``` - -### OPDS vs USB Transfer - -| Feature | OPDS (Wireless) | USB Transfer | -| ----------------- | ----------------------------- | ----------------------- | -| **Convenience** | ⭐⭐⭐⭐⭐ No cable needed | ⭐⭐ Requires cable | -| **Speed** | ⭐⭐⭐ Fast (Wi-Fi dependent) | ⭐⭐⭐⭐⭐ Very fast | -| **Bulk Transfer** | ⭐⭐⭐ One at a time | ⭐⭐⭐⭐⭐ Many at once | -| **Progress Sync** | ⭐⭐⭐⭐⭐ Instant | ⭐⭐⭐⭐ After transfer | -| **Accessibility** | ⭐⭐⭐⭐⭐ Anywhere | ⭐⭐ At computer only | -| **Reliability** | ⭐⭐⭐⭐ Very good | ⭐⭐⭐⭐⭐ Excellent | - -**Recommendation**: Use OPDS for daily reading (convenience), USB for bulk library transfers. - -### OPDS Tips and Tricks - -1. **Favorite Collections**: Pin frequently-used collections to home screen -2. **Batch Downloads**: Start multiple downloads before leaving Wi-Fi -3. **Download Queue**: Downloads continue in background while reading -4. **Storage Management**: Check free space before downloading large collections -5. **Network Speed**: Use 5GHz Wi-Fi for faster downloads if available +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 +**Problem**: "Connection refused" error on the device **Solutions**: -- Verify Bookhoard is running on your computer -- Check the server URL and port (8765) -- Ensure device is on same Wi-Fi network -- Try using your computer's IP address instead of "localhost" +- 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` -### Authentication Failed +### Sync Not Working After Approval -**Problem**: "Authentication failed" error +**Problem**: Device shows as approved but changes don't appear in Bookhoard **Solutions**: -- Verify username and password -- Check your account is active and not locked -- Try logging in to Bookhoard web interface first -- Reset password if needed - -### Sync Not Working - -**Problem**: Changes not appearing in Bookhoard - -**Solutions**: - -- Enable debug logging in KOReader -- Check Bookhoard Device Management page for errors -- Verify sync is enabled in KOReader settings -- Try manual sync to trigger immediate update -- Check Bookhoard logs for sync errors +- 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 on multiple devices +**Problem**: Sync conflicts when reading the same book on multiple devices **Solutions**: -1. Go to Bookhoard **Conflicts** page -2. Review conflicting progress from each device +1. Go to Bookhoard's **Conflicts** page +2. Review the progress reported by each device 3. Choose which device's progress to keep -4. Set auto-resolution preference for future conflicts - -### Large Files Not Syncing - -**Problem**: Large annotations or highlights fail to sync - -**Solutions**: - -- Check Bookhoard sync queue for stuck items -- Increase sync timeout in KOReader settings -- Break up large highlights into smaller segments -- Verify network bandwidth is sufficient ## Security Best Practices -1. **Use HTTPS**: If deploying Bookhoard publicly, configure SSL/TLS -2. **Strong Password**: Use a secure password for your Bookhoard account -3. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3) -4. **Device Authorization**: Only approve devices you recognize -5. **Regular Updates**: Keep KOReader updated to the latest version +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) -- [Kobo Setup Guide](kobo-setup.md) - -## Support - -If you encounter issues: - -1. Check the troubleshooting section above -2. Enable debug logging and review KOReader logs -3. Check Bookhoard sync queue and device management pages -4. Open an issue on the Bookhoard GitHub repository +- [Bookhoard KOReader Plugin](https://git.linuxhg.com/Bookhoard/bookhoard.koplugin) --- -**Last Updated**: 2026-01-31 -**Bookhoard Version**: 1.0 -**KOReader Version**: 2024.01+ +**Last Updated**: August 2026 +**Bookhoard Version**: 1.0