john-okeefe
74bf439e5e
- Simplify and condense KOReader configuration documentation - Remove redundant sections and improve clarity
296 lines
8.8 KiB
Markdown
296 lines
8.8 KiB
Markdown
# 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](https://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](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
|
|
```
|
|
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](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
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-01-31
|
|
**Bookmann Version**: 1.0
|
|
**KOReader Version**: 2024.01+
|