Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: refactor KOReader setup guide

Browse Source 
- Simplify and condense KOReader configuration documentation
- Remove redundant sections and improve clarity
This commit is contained in:
john-okeefe
2026-01-31 18:25:32 -05:00
parent 4d87beb540
commit 74bf439e5e
1 changed files with 251 additions and 509 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/devices/KOREADER_SETUP.md
+251 -509
View File
@@ -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
- ✅ 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](../SYNC_USER_GUIDE.md#device-registration))
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
## 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. Find or register your KOReader device
3. Copy the **Sync URL**:
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](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
2. Tap the menu icon (≡)
3. Navigate to **Tools → More plugins**
4. Find **Calibre Sync** (or **Wireless Sync**)
5. Tap to configure
1. **Authentication Method**: Select "Basic Auth"
2. **Username**: Your Bookmann email or username
3. **Password**: Your Bookmann password
#### Enter Server Details
### Step 4: Configure Sync Settings
```
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]
```
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)
### Step 3: Test Connection
3. **What to Sync**: Enable:
- ✅ Reading progress
- ✅ Bookmarks
- ✅ Highlights
- ✅ Notes
1. Tap **Test Connection** or **Verify**
2. Should see: "✓ Connection successful"
3. Tap **Save**
### Step 5: Test Connection
### 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**
2. Set sync frequency: **Every page turn** (recommended)
3. Enable **Wireless connection** must be on
4. Tap **Save**
## Using Sync Features
---
### 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
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",
},
}
```
- **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
### Sync Mode Configuration
### Manual Sync
**Immediate Mode** (Recommended for daily reading):
```lua
sync_mode = "immediate"
page_turn_sync = true
```
To manually trigger a sync:
1. Open the KOReader menu (≡)
2. Select **Tools** → **Calibre**
3. Tap **Sync Now**
**Checkpoint Mode** (Better for battery):
```lua
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
---
The sync status will display:
- 🟢 **Synced** - All changes uploaded
- 🟡 **Syncing...** - In progress
- 🔴 **Failed** - Check your network connection
## 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
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)
}
```
### Checkpoint Sync
### Batch Sync Configuration
**For processing multiple books**:
```lua
batch_size = 10, -- Books per batch
batch_delay = 1, -- Delay between batches (seconds)
concurrent_uploads = 2, -- Parallel uploads
```
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 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
log_level = "DEBUG"
log_sync = true
log_file = "/mnt/onboard/sync.log"
```
## Troubleshooting
**View logs**:
```
Tools → Statistics → Sync log
Or: Connect via SSH and view log file
```
### 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](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
### 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+
**Last Updated**: 2026-01-31
**Bookmann Version**: 1.0
**KOReader Version**: 2024.01+