bookhoard/docs/devices/KOREADER_SETUP.md

KOReader Wireless Sync Setup Guide

Overview

This guide will walk you through setting up KOReader to sync wirelessly with your Bookmann server.

---

Prerequisites

• ✅ KOReader installed on your device (Kindle, Kobo, PocketBook, Android, etc.)
• ✅ Bookmann server running and accessible
• ✅ Wi-Fi connection (device and server on same network, or server accessible via internet)
• ✅ Device registered in Bookmann (see User Guide)

---

Quick Setup (5 Minutes)

Step 1: Get Device Credentials

1. In Bookmann web interface, go to Settings → Devices
2. Find or register your KOReader device
3. Copy the Sync URL:

   https://bookmann.example.com/api/sync/koreader
   

4. Copy the Auth Token (if shown)

Step 2: Configure KOReader

On Your Device

1. Open KOReader
2. Tap the menu icon (≡)
3. Navigate to Tools → More plugins
4. Find Calibre Sync (or Wireless Sync)
5. Tap to configure

Enter Server Details

Server Type: Calibre (compatible)
Server URL: https://bookmann.example.com
Port: 8765 (or leave blank for default)
Username: (leave blank)
Password: [Paste your device auth token]

Step 3: Test Connection

1. Tap Test Connection or Verify
2. Should see: "✓ Connection successful"
3. Tap Save

Step 4: Enable Auto-Sync

1. In sync settings, enable Auto-sync
2. Set sync frequency: Every page turn (recommended)
3. Enable Wireless connection must be on
4. Tap Save

---

Detailed Configuration

Creating a Custom Sync Profile

For advanced users, you can create a custom sync profile:

File Location: config/calibre.lua on your device's SD card

return {
    -- Bookmann server details
    calibre_opds = {
        ["https://bookmann.example.com"] = {
            protocol = "http",
            host = "bookmann.example.com",
            port = 8765,
        },
    },
    
    -- Sync settings
    wireless_sync = true,
    auto_sync = true,
    sync_frequency = "every_page_turn",
    
    -- Authentication
    username = "",
        password = "YOUR_DEVICE_TOKEN_HERE",
    },
}

Sync Mode Configuration

Immediate Mode (Recommended for daily reading):

sync_mode = "immediate"
page_turn_sync = true

Checkpoint Mode (Better for battery):

sync_mode = "checkpoint"
checkpoint_interval = 300 -- 5 minutes

---

Advanced Features

Custom Sync Intervals

You can configure when KOReader syncs:

Setting	Description	Battery Impact
Every page turn	Instant sync across devices	High
Every 5 minutes	Balance of speed and battery	Medium
Every chapter	Good for long chapters	Low
Manual only	Only when you tap "Sync"	Lowest

To Configure:

Tools → Wireless Sync → Sync Interval → Select option

Progress Tracking Options

KOReader can send multiple types of progress data:

For EPUB files:

• ✅ Percentage (0-100%)
• ✅ EPUB CFI (precise location)
• ✅ Chapter number
• ✅ Character offset

For PDF files:

• ✅ Page number
• ✅ Page position (X, Y coordinates)
• ✅ Zoom level

Configure:

Settings → Status Bar → Progress Indicator → Select type

Annotation Sync

What Syncs:

• ✅ Highlights (with colors)
• ✅ Bookmarks
• ✅ Notes
• ✅ Underlines
• ✅ Column/area selections

Configure:

Reader → Highlight → Store in: Device + Cloud (Bookmann)

---

Troubleshooting

"Connection Failed" Error

Causes:

1. Server URL incorrect
2. Network firewall blocking connection
3. Device token expired
4. Server not running

Solutions:

1. Verify Server URL:

   • Check for typos
   • Include https:// prefix
   • Use correct domain/IP

2. Test Network:

   • Open browser on device
   • Try accessing: https://bookmann.example.com/api/sync/koreader/
   • Should see JSON response or method not allowed

3. Check Token:

   • Go to Bookmann → Settings → Devices
   • Verify device is "Sync Enabled"
   • Regenerate token if needed

4. Verify Server:

   • Check Bookmann server is running
   • View server logs for errors
   • Test from web browser

"Authentication Failed" Error

Causes:

1. Wrong auth token
2. Device revoked
3. Token expired

Solutions:

1. Go to Bookmann → Settings → Devices
2. Find your device
3. Copy new auth token
4. Update in KOReader sync settings
5. Save and retry

Sync Not Working

Checklist:

• Wi-Fi is enabled on device
• Bookmann server is running
• Device is "Sync Enabled" in Bookmann
• Auto-sync is enabled in KOReader
• Same book exists in both libraries
• Network connection is stable

Steps:

1. Open a book in KOReader
2. Turn a page
3. Wait 5 seconds
4. Check Bookmann web interface
5. Progress should be updated

Battery Drain

If battery drains quickly:

1. Switch to checkpoint mode:

   • Open: Tools → Wireless Sync
   • Set: Sync mode to "Checkpoint"
   • Set: Interval to 5 minutes

2. Reduce sync frequency:

   • Set: Sync to "Manual only"
   • Tap sync button when needed

3. Use 2.4GHz Wi-Fi:

   • Uses less power than 5GHz
   • Better range through walls

Partial Sync

If some books sync but others don't:

1. Check file paths:

   • Bookmann and KOReader must have same file
   • File names must match exactly
   • Check library folders are configured

2. Match by metadata:

   • Ensure Title and Author match
   • Open book details on both sides
   • Check for typos in metadata

3. View sync logs:

   • KOReader: Tools → Statistics → Sync log
   • Look for "book not found" errors
   • Note the UUID or file path

---

File Matching

How KOReader Finds Books

Bookmann matches books in this order:

1. By UUID (most reliable)
2. By file path
3. By title + author

Ensuring Matches

Best Practices:

1. Use consistent file names:

   Good: The Great Gatsby.epub
   Bad: EBOOK_12345.epub
   

2. Include metadata:

   • Title: "The Great Gatsby"
   • Author: "F. Scott Fitzgerald"
   • ISBN: 9780743273565 (if available)

3. Use library folders:

   • Organize by author or series
   • Keep Bookmann and KOReader folders in sync

---

Performance Optimization

For Faster Sync

Network:

• Use 5GHz Wi-Fi (if close to router)
• Ensure good signal strength
• Use wired Ethernet for server

Device:

• Close unused apps
• Restart device weekly
• Keep KOReader updated

Server:

• Use SSD for database
• Ensure adequate bandwidth
• Monitor queue processing

For Better Battery

Settings:

Auto-sync: Checkpoint mode
Sync interval: Every 5 minutes
Wi-Fi: 2.4GHz only
Screen refresh: Lower frequency

Device Habits:

• Sleep device when not reading
• Disable Wi-Fi when reading offline
• Use airplane mode with Wi-Fi only

---

Security Considerations

Token Storage

Where Token is Stored:

• File: /mnt/onboard/addons/calibre.lua or similar
• Encrypted: No (plaintext)
• Accessible: Anyone with device access

Security Tips:

• 🔒 Keep device physically secure
• 🔒 Don't share auth tokens
• 🔒 Revoke device if lost/stolen
• 🔒 Use HTTPS only (never HTTP)

Network Security

Public Wi-Fi:

• ⚠️ Avoid public Wi-Fi if possible
• ✅ Use VPN if on public Wi-Fi
• ✅ Ensure HTTPS (TLS 1.3)
• ✅ Verify server certificate

Data Privacy

What Syncs:

• ✅ Reading progress
• ✅ Highlights and notes
• ✅ Bookmarks

What DOESN'T Sync:

• ❌ Book content (your books stay on device)
• ❌ Personal files
• ❌ System data
• ❌ Other apps' data

---

Advanced Configuration

Custom Timeout Settings

File: config/calibre.lua

return {
    timeout = 30,        -- Connection timeout (seconds)
    read_timeout = 60,   -- Read operation timeout
    max_retries = 3,      -- Retry failed requests
    retry_delay = 5,      -- Delay between retries (seconds)
}

Batch Sync Configuration

For processing multiple books:

batch_size = 10,          -- Books per batch
batch_delay = 1,          -- Delay between batches (seconds)
concurrent_uploads = 2,    -- Parallel uploads

Debug Mode

Enable sync logging:

log_level = "DEBUG"
log_sync = true
log_file = "/mnt/onboard/sync.log"

View logs:

Tools → Statistics → Sync log
Or: Connect via SSH and view log file

---

Uninstalling / Disabling

Temporary Disable

To temporarily stop syncing:

Tools → Wireless Sync → Disable Auto-sync

Permanent Disable

To remove sync configuration:

Tools → More plugins → Calibre Sync → Uninstall

To revoke device on server:

Web Interface → Settings → Devices → Select Device → Delete

---

FAQ

General Questions

Q: Does this work with all Kindle models? A: Most Kindles from 2012+ that can run KOReader.

Q: Can I sync with Calibre AND Bookmann? A: Yes! KOReader supports multiple sync servers.

Q: What happens if I edit metadata? A: Sync updates reading progress only, not metadata.

Q: Can I sync over cellular (3G/4G/5G)? A: Technically yes, but not recommended (high data usage).

Q: Does sync work with sideloaded books? A: Yes, if the file path/name matches in Bookmann library.

Technical Questions

Q: What protocol does it use? A: Calibre-compatible HTTP/JSON over HTTPS.

Q: Port requirements? A: Only port 443 (HTTPS) needed from device to server.

Q: Can I sync without Wi-Fi? A: Only via cellular or USB (not recommended).

Q: How much data per sync? A: ~1KB per page turn, ~50KB per annotation.

Q: Does sync work while device is sleeping? A: No, device must be awake and connected to Wi-Fi.

---

Device-Specific Notes

Kindle Paperwhite

File Location:

/mnt/us/addons/calibre.lua

Auto-Sync: Not supported, use manual sync

Wi-Fi: Only when device is awake

Kobo Clara/Libra

File Location:

/mnt/onboard/.adds/koreader/

Auto-Sync: Supported

Battery: Excellent with checkpoint mode

PocketBook

File Location:

/mnt/ext1/system/config/calibre.lua

Auto-Sync: Supported

Network: Supports both 2.4GHz and 5GHz

Android Tablets

File Location:

/storage/emulated/0/KOReader/config/

Auto-Sync: Supported

Background Sync: Yes (with restrictions)

---

Getting Help

Documentation

• Bookmann Docs: /docs/
• KOReader Docs: https://koreader.rocks/userguide/
• Sync API: /docs/api.md

Support

• Issues: GitHub Issues
• Forum: community.bookmann.example.com
• Email: support@bookmann.example.com

---

Changelog

v1.0.0 (January 2026)

• Initial KOReader sync support
• Calibre-compatible protocol
• Real-time progress sync
• Annotation sync
• Checkpoint mode
• Conflict resolution

---

Last Updated: January 31, 2026
Compatible With: KOReader 2024.01+
Bookmann Version: 1.0.0+