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

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+