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](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`

## OPDS Wireless Book Delivery

### What is OPDS?

OPDS (Open Publication Distribution System) allows your KOReader device to **wirelessly download books** from Bookmann - no USB cable needed!

### OPDS Benefits

- **Wireless Downloads**: Browse and download books over Wi-Fi
- **On-Demand Access**: Your entire library at your fingertips
- **Collection Support**: Browse and download from specific collections
- **Automatic Progress Sync**: Downloaded books sync progress instantly
- **Format Support**: EPUB, KEPUB, PDF, and more

### Enable OPDS in KOReader

#### Step 1: Get Your OPDS URL

1. Log in to Bookmann web interface
2. Go to **Device Management**
3. Find your registered KOReader device
4. Click **Show OPDS URL**
5. Copy the URL (format: `http://YOUR_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog`)

#### Step 2: Add OPDS Catalog in KOReader

1. Open KOReader on your device
2. Tap the **+** (plus) button on the home screen
3. Select **OPDS Catalog**
4. Enter catalog details:
   - **Name**: Bookmann (or any name you prefer)
   - **URL**: Paste your OPDS URL from Step 1
5. Tap **Save**

Your Bookmann library now appears in KOReader's home screen!

### Browse and Download Books

#### Browse Your Library

1. Tap **Bookmann** on KOReader home screen
2. You'll see:
   - **All Books**: Complete library view
   - **Collections**: Books organized by collections
   - **Recent**: Latest additions
3. Tap any category to browse

#### Download a Book

1. Browse to find a book
2. Tap the book to see details
3. Tap **Download**
4. Progress bar shows download status
5. Book opens automatically when complete

#### Download Entire Collections

1. In Bookmann catalog, tap **Collections**
2. Select a collection
3. Tap **Download All** to get all books
4. Downloads queue and process in background

### OPDS Features

#### Supported Formats

KOReader OPDS supports:
- **EPUB**: Standard ebook format
- **KEPUB**: Kobo-optimized format (KOReader handles this well)
- **PDF**: Fixed-layout documents
- **CBZ**: Comic book archives
- **TXT**: Plain text files
- **RTF**: Rich text format

#### Automatic Book Matching

Books downloaded via OPDS are automatically matched:
- Uses SHA-256 hashes for precise matching
- Falls back to title/author matching
- Links to your existing Bookmann library
- Progress syncs automatically

#### Collection Integration

Your Bookmann collections appear in KOReader:
- Collection **"To Read"** → KOReader category
- Collection **"Science Fiction"** → Browseable section
- Custom collections → Preserved organization

### KOReader OPDS Settings

#### Update Interval

Configure how often KOReader checks for new books:
1. KOReader menu → Tools → OPDS
2. Set **Update Interval**: 5min, 15min, 1hr, manual
3. **Recommended**: 15min for balance

#### Download Location

Choose where to store downloaded books:
1. KOReader menu → File Browser
2. Set **Default Download Folder**
3. **Recommended**: `/mnt/us/Documents/` (Kindle) or `/mnt/onboard/Documents/` (Kobo)

#### Auto-Download

Automatically download new books from collections:
1. KOReader menu → Tools → OPDS
2. Enable **Auto-Download New Books**
3. Select collections to monitor
4. New books download automatically when connected to Wi-Fi

### OPDS Troubleshooting

#### Catalog Not Loading

**Problem**: Bookmann catalog shows error or won't load

**Solutions**:
1. Verify device is connected to Wi-Fi
2. Check OPDS URL is correct in settings
3. Try accessing OPDS URL in your browser
4. Ensure Bookmann server is running
5. Check Bookmann device is approved

#### Download Fails

**Problem**: Book download starts but fails

**Solutions**:
1. Check Wi-Fi signal strength
2. Ensure sufficient storage on device
3. Try downloading a smaller book
4. Check Bookmann has the book file
5. Review Bookmann logs for errors

#### Book Opens But Progress Doesn't Sync

**Problem**: Downloaded book doesn't sync progress

**Solutions**:
1. Verify book is matched to Bookmann library
2. Check device sync settings are enabled
3. Try manual sync from device
4. Ensure book exists in Bookmann with same hash
5. Check Bookmann Progress page

#### Slow Downloads

**Problem**: Books take too long to download

**Solutions**:
1. Stay close to Wi-Fi router
2. Use 5GHz Wi-Fi if available
3. Close other apps using bandwidth
4. Download smaller books first
5. Consider USB for large books (100MB+)

### Advanced OPDS Configuration

#### Custom User-Agent

Some OPDS catalogs require specific user agent:

```lua
-- In KOReader settings
OPDSUserAgent = "KOReader/2024.01"
```

#### Authentication Token

If Bookmann requires token authentication:

1. Get token from Bookmann device settings
2. Add to OPDS URL: `?token=YOUR_TOKEN`
3. KOReader includes token in all requests

#### Compression

Enable compression for faster downloads:

```lua
-- In KOReader settings
OPDSCompressionEnabled = true
```

### OPDS vs USB Transfer

| Feature | OPDS (Wireless) | USB Transfer |
|---------|----------------|--------------|
| **Convenience** | ⭐⭐⭐⭐⭐ No cable needed | ⭐⭐ Requires cable |
| **Speed** | ⭐⭐⭐ Fast (Wi-Fi dependent) | ⭐⭐⭐⭐⭐ Very fast |
| **Bulk Transfer** | ⭐⭐⭐ One at a time | ⭐⭐⭐⭐⭐ Many at once |
| **Progress Sync** | ⭐⭐⭐⭐⭐ Instant | ⭐⭐⭐⭐ After transfer |
| **Accessibility** | ⭐⭐⭐⭐⭐ Anywhere | ⭐⭐ At computer only |
| **Reliability** | ⭐⭐⭐⭐ Very good | ⭐⭐⭐⭐⭐ Excellent |

**Recommendation**: Use OPDS for daily reading (convenience), USB for bulk library transfers.

### OPDS Tips and Tricks

1. **Favorite Collections**: Pin frequently-used collections to home screen
2. **Batch Downloads**: Start multiple downloads before leaving Wi-Fi
3. **Download Queue**: Downloads continue in background while reading
4. **Storage Management**: Check free space before downloading large collections
5. **Network Speed**: Use 5GHz Wi-Fi for faster downloads if available

## 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+