bookhoard/docs/devices/KOREADER_SETUP.md

KOReader Device Setup Guide

This guide will help you set up KOReader on your e-reader device to sync with Bookmann.

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
• Android tablets and phones

Prerequisites

Before you begin, make sure you have:

• ✅ A Bookmann instance running and accessible on your network
• ✅ Your Bookmann credentials (username and password)
• ✅ A KOReader-compatible e-reader device
• ✅ Your device connected to the same Wi-Fi network as your Bookmann instance

Installation

Kindle Devices

1. Install KOReader

   • Download the latest KOReader release from 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
   • 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
   • 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

Device Registration

Step 1: Get Your Bookmann Instance URL

Find your Bookmann instance URL. This will typically be one of:

• Local Network: http://YOUR_COMPUTER_IP:8765
• Localhost (if testing): http://localhost:8765
• Domain (if configured): https://bookmann.yourdomain.com

Step 2: Register Your Device in Bookmann

1. Log in to your Bookmann 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 Bookmann 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 Bookmann instance URL

   http://YOUR_COMPUTER_IP:8765/api/sync/koreader
   

   Replace YOUR_COMPUTER_IP with your actual IP address

3. Set Custom Port (if needed): Keep default or enter 8765

Step 3: Configure Authentication

1. Authentication Method: Select "Basic Auth"
2. Username: Your Bookmann email or username
3. Password: Your Bookmann password

Step 4: Configure Sync Settings

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)

3. What to Sync: Enable:

   • ✅ Reading progress
   • ✅ Bookmarks
   • ✅ Highlights
   • ✅ Notes

Step 5: Test Connection

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 Bookmann instance is running
   • Verify username and password are correct

Using Sync Features

Initial Sync

When you first enable sync, KOReader will:

1. Connect to Bookmann
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

OPDS Wireless Book Delivery

What is OPDS?

OPDS (Open Publication Distribution System) allows your KOReader device to wirelessly download books from Bookmann - 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 Bookmann 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: Bookmann (or any name you prefer)
   • URL: Paste your OPDS URL from Step 1
5. Tap Save

Your Bookmann library now appears in KOReader's home screen!

Browse and Download Books

Browse Your Library

1. Tap Bookmann 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 Bookmann 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:

• EPUB: Standard ebook format
• KEPUB: Kobo-optimized format (KOReader handles this well)
• 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 Bookmann library
• Progress syncs automatically

Collection Integration

Your Bookmann 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: Bookmann 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 Bookmann server is running
5. Check Bookmann 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 Bookmann has the book file
5. Review Bookmann logs for errors

Book Opens But Progress Doesn't Sync

Problem: Downloaded book doesn't sync progress

Solutions:

1. Verify book is matched to Bookmann library
2. Check device sync settings are enabled
3. Try manual sync from device
4. Ensure book exists in Bookmann with same hash
5. Check Bookmann 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:

-- In KOReader settings
OPDSUserAgent = "KOReader/2024.01"

Authentication Token

If Bookmann requires token authentication:

1. Get token from Bookmann device settings
2. Add to OPDS URL: ?token=YOUR_TOKEN
3. KOReader includes token in all requests

Compression

Enable compression for faster downloads:

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

Troubleshooting

Connection Refused

Problem: "Connection refused" error

Solutions:

• Verify Bookmann 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"

Authentication Failed

Problem: "Authentication failed" error

Solutions:

• Verify username and password
• Check your account is active and not locked
• Try logging in to Bookmann web interface first
• Reset password if needed

Sync Not Working

Problem: Changes not appearing in Bookmann

Solutions:

• Enable debug logging in KOReader
• Check Bookmann Device Management page for errors
• Verify sync is enabled in KOReader settings
• Try manual sync to trigger immediate update
• Check Bookmann logs for sync errors

Conflicts Detected

Problem: Sync conflicts when reading on multiple devices

Solutions:

1. Go to Bookmann Conflicts page
2. Review conflicting progress from 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 Bookmann 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 Bookmann publicly, configure SSL/TLS
2. Strong Password: Use a secure password for your Bookmann 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

Additional Resources

• KOReader Documentation
• KOReader Forum
• Bookmann Universal Sync Guide
• Kobo Setup Guide

Support

If you encounter issues:

1. Check the troubleshooting section above
2. Enable debug logging and review KOReader logs
3. Check Bookmann sync queue and device management pages
4. Open an issue on the Bookmann GitHub repository

---

Last Updated: 2026-01-31
Bookmann Version: 1.0
KOReader Version: 2024.01+