docs: refactor KOReader setup guide
- Simplify and condense KOReader configuration documentation - Remove redundant sections and improve clarity
This commit is contained in:
+251
-509
@@ -1,553 +1,295 @@
|
|||||||
# KOReader Wireless Sync Setup Guide
|
# KOReader Device Setup Guide
|
||||||
|
|
||||||
## Overview
|
This guide will help you set up KOReader on your e-reader device to sync with Bookmann.
|
||||||
|
|
||||||
This guide will walk you through setting up KOReader to sync wirelessly with your Bookmann server.
|
## 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
|
## Prerequisites
|
||||||
|
|
||||||
- ✅ KOReader installed on your device (Kindle, Kobo, PocketBook, Android, etc.)
|
Before you begin, make sure you have:
|
||||||
- ✅ Bookmann server running and accessible
|
- ✅ A Bookmann instance running and accessible on your network
|
||||||
- ✅ Wi-Fi connection (device and server on same network, or server accessible via internet)
|
- ✅ Your Bookmann credentials (username and password)
|
||||||
- ✅ Device registered in Bookmann (see [User Guide](../SYNC_USER_GUIDE.md#device-registration))
|
- ✅ A KOReader-compatible e-reader device
|
||||||
|
- ✅ Your device connected to the same Wi-Fi network as your Bookmann instance
|
||||||
|
|
||||||
---
|
## Installation
|
||||||
|
|
||||||
## Quick Setup (5 Minutes)
|
### Kindle Devices
|
||||||
|
|
||||||
### Step 1: Get Device Credentials
|
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
|
||||||
|
|
||||||
1. In Bookmann web interface, go to **Settings → Devices**
|
2. **Launch KOReader**
|
||||||
2. Find or register your KOReader device
|
- On your Kindle, go to Home → Settings → Device Options → Personalize Your Kindle
|
||||||
3. Copy the **Sync URL**:
|
- 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
|
||||||
|
|
||||||
|
## 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
|
||||||
```
|
```
|
||||||
https://bookmann.example.com/api/sync/koreader
|
http://YOUR_COMPUTER_IP:8765/api/sync/koreader
|
||||||
```
|
```
|
||||||
4. Copy the **Auth Token** (if shown)
|
Replace `YOUR_COMPUTER_IP` with your actual IP address
|
||||||
|
|
||||||
### Step 2: Configure KOReader
|
3. **Set Custom Port** (if needed): Keep default or enter `8765`
|
||||||
|
|
||||||
#### On Your Device
|
### Step 3: Configure Authentication
|
||||||
|
|
||||||
1. Open KOReader
|
1. **Authentication Method**: Select "Basic Auth"
|
||||||
2. Tap the menu icon (≡)
|
2. **Username**: Your Bookmann email or username
|
||||||
3. Navigate to **Tools → More plugins**
|
3. **Password**: Your Bookmann password
|
||||||
4. Find **Calibre Sync** (or **Wireless Sync**)
|
|
||||||
5. Tap to configure
|
|
||||||
|
|
||||||
#### Enter Server Details
|
### Step 4: Configure Sync Settings
|
||||||
|
|
||||||
```
|
1. **Auto Sync**: Enable for automatic sync
|
||||||
Server Type: Calibre (compatible)
|
2. **Sync Frequency**: Choose from:
|
||||||
Server URL: https://bookmann.example.com
|
- Every page turn (recommended for real-time sync)
|
||||||
Port: 8765 (or leave blank for default)
|
- Every bookmark save
|
||||||
Username: (leave blank)
|
- Every highlight
|
||||||
Password: [Paste your device auth token]
|
- Manual only (sync when you press the sync button)
|
||||||
```
|
|
||||||
|
|
||||||
### Step 3: Test Connection
|
3. **What to Sync**: Enable:
|
||||||
|
- ✅ Reading progress
|
||||||
|
- ✅ Bookmarks
|
||||||
|
- ✅ Highlights
|
||||||
|
- ✅ Notes
|
||||||
|
|
||||||
1. Tap **Test Connection** or **Verify**
|
### Step 5: Test Connection
|
||||||
2. Should see: "✓ Connection successful"
|
|
||||||
3. Tap **Save**
|
|
||||||
|
|
||||||
### Step 4: Enable Auto-Sync
|
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
|
||||||
|
|
||||||
1. In sync settings, enable **Auto-sync**
|
## Using Sync Features
|
||||||
2. Set sync frequency: **Every page turn** (recommended)
|
|
||||||
3. Enable **Wireless connection** must be on
|
|
||||||
4. Tap **Save**
|
|
||||||
|
|
||||||
---
|
### Initial Sync
|
||||||
|
|
||||||
## Detailed Configuration
|
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
|
||||||
|
|
||||||
### Creating a Custom Sync Profile
|
### Reading Progress Sync
|
||||||
|
|
||||||
For advanced users, you can create a custom sync profile:
|
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
|
||||||
|
|
||||||
**File Location**: `config/calibre.lua` on your device's SD card
|
### Annotations Sync
|
||||||
|
|
||||||
```lua
|
- **Bookmarks**: Sync when created or deleted
|
||||||
return {
|
- **Highlights**: Sync when created, edited, or deleted
|
||||||
-- Bookmann server details
|
- **Notes**: Sync when created, edited, or deleted
|
||||||
calibre_opds = {
|
- **Linked Notes**: Notes attached to highlights sync together
|
||||||
["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
|
### Manual Sync
|
||||||
|
|
||||||
**Immediate Mode** (Recommended for daily reading):
|
To manually trigger a sync:
|
||||||
```lua
|
1. Open the KOReader menu (≡)
|
||||||
sync_mode = "immediate"
|
2. Select **Tools** → **Calibre**
|
||||||
page_turn_sync = true
|
3. Tap **Sync Now**
|
||||||
```
|
|
||||||
|
|
||||||
**Checkpoint Mode** (Better for battery):
|
The sync status will display:
|
||||||
```lua
|
- 🟢 **Synced** - All changes uploaded
|
||||||
sync_mode = "checkpoint"
|
- 🟡 **Syncing...** - In progress
|
||||||
checkpoint_interval = 300 -- 5 minutes
|
- 🔴 **Failed** - Check your network connection
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
## Advanced Configuration
|
||||||
|
|
||||||
### Custom Timeout Settings
|
### Offline Mode
|
||||||
|
|
||||||
**File**: `config/calibre.lua`
|
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
|
||||||
|
|
||||||
```lua
|
### Checkpoint Sync
|
||||||
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 better battery life, use checkpoint mode:
|
||||||
|
1. In KOReader Calibre settings
|
||||||
**For processing multiple books**:
|
2. Set **Sync Mode** to "Checkpoint"
|
||||||
|
3. Set **Checkpoint Interval** (e.g., every 5 minutes)
|
||||||
```lua
|
4. Syncs occur in batches instead of every action
|
||||||
batch_size = 10, -- Books per batch
|
|
||||||
batch_delay = 1, -- Delay between batches (seconds)
|
|
||||||
concurrent_uploads = 2, -- Parallel uploads
|
|
||||||
```
|
|
||||||
|
|
||||||
### Debug Mode
|
### Debug Mode
|
||||||
|
|
||||||
**Enable sync logging**:
|
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`
|
||||||
|
|
||||||
```lua
|
## Troubleshooting
|
||||||
log_level = "DEBUG"
|
|
||||||
log_sync = true
|
|
||||||
log_file = "/mnt/onboard/sync.log"
|
|
||||||
```
|
|
||||||
|
|
||||||
**View logs**:
|
### Connection Refused
|
||||||
```
|
|
||||||
Tools → Statistics → Sync log
|
**Problem**: "Connection refused" error
|
||||||
Or: Connect via SSH and view log file
|
|
||||||
```
|
**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](https://github.com/koreader/koreader)
|
||||||
|
- [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271)
|
||||||
|
- [Bookmann Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_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 Bookmann sync queue and device management pages
|
||||||
|
4. Open an issue on the Bookmann GitHub repository
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Uninstalling / Disabling
|
**Last Updated**: 2026-01-31
|
||||||
|
**Bookmann Version**: 1.0
|
||||||
### Temporary Disable
|
**KOReader Version**: 2024.01+
|
||||||
|
|
||||||
**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+
|
|
||||||
|
|||||||
Reference in New Issue
Block a user