bookhoard/docs/devices/KOREADER_SETUP.md

# KOReader Wireless Sync Setup Guide

## Overview

This guide will walk you through setting up KOReader to sync wirelessly with your Bookmann server.

---

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

---

## Quick Setup (5 Minutes)

### Step 1: Get Device Credentials

1. In Bookmann web interface, go to **Settings → Devices**
2. Find or register your KOReader device
3. Copy the **Sync URL**:
   ```
   https://bookmann.example.com/api/sync/koreader
   ```
4. Copy the **Auth Token** (if shown)

### Step 2: Configure KOReader

#### On Your Device

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

#### Enter Server Details

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

### Step 3: Test Connection

1. Tap **Test Connection** or **Verify**
2. Should see: "✓ Connection successful"
3. Tap **Save**

### Step 4: Enable Auto-Sync

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**

---

## Detailed Configuration

### Creating a Custom Sync Profile

For advanced users, you can create a custom sync profile:

**File Location**: `config/calibre.lua` on your device's SD card

```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",
    },
}
```

### Sync Mode Configuration

**Immediate Mode** (Recommended for daily reading):
```lua
sync_mode = "immediate"
page_turn_sync = true
```

**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

---

## Advanced Configuration

### Custom Timeout Settings

**File**: `config/calibre.lua`

```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)
}
```

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

### Debug Mode

**Enable sync logging**:

```lua
log_level = "DEBUG"
log_sync = true
log_file = "/mnt/onboard/sync.log"
```

**View logs**:
```
Tools → Statistics → Sync log
Or: Connect via SSH and view log file
```

---

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