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