john-okeefe
4d321528b2
This commit updates all documentation files throughout the project: - Updated IMPLEMENTATION_PLAN.md with new implementation details - Updated PROJECT_GUIDELINES.md with coding standards and practices - Updated README.md with current project information - Updated SCREENSHOT_AUTOMATION.md with new automation details - Added TEST_DATA.md with test fixtures data - Updated cover_image_serving_plan.md with static URL patterns Documentation API updates: - Updated API reference documentation for all endpoints including: - Authentication (login, logout, register, refresh_token) - Book matching (auto_link, bulk_link, link_book, search) - Collections (CRUD operations, shelf mappings, auto-assign rules) - Conflicts (bulk operations, resolve/dismiss) - Devices (registration, approval, shelf management) - Highlights (create, update, delete, get) - Kobo sync (bookmark, markup, initialization, sync) - KOReader sync (library, metadata, bookmarks, progress) - Libraries (CRUD, folders, media items, stats) - Media items (bulk operations, CRUD) - Notes (CRUD operations) - OPDS (acquisition, feeds, publication) - Progress (reading progress tracking) - Queue (device queue management) - Ratings (star ratings) - Scanner (watch mode, scan operations) - Sync protocols (Kobo, KOReader) - Users (profile, password, admin operations) - WebSocket protocols - Updated user guides (admin, dashboard, settings, sync) - Updated device setup guides (Kobo, KOReader) - Updated developer guides (testing, contributing, operations) - Updated scripts/README.md
533 lines
15 KiB
Markdown
533 lines
15 KiB
Markdown
# KOReader Device Setup Guide
|
|
|
|
This guide will help you set up KOReader on your e-reader device to sync with Bookhoard.
|
|
|
|
## 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 Bookhoard instance running and accessible on your network
|
|
- ✅ Your Bookhoard credentials (username and password)
|
|
- ✅ A KOReader-compatible e-reader device
|
|
- ✅ Your device connected to the same Wi-Fi network as your Bookhoard 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 Bookhoard Instance URL
|
|
|
|
Find your Bookhoard 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://bookhoard.yourdomain.com`
|
|
|
|
### Step 2: Register Your Device in Bookhoard
|
|
|
|
1. Log in to your Bookhoard 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 Bookhoard 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 Bookhoard 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 Bookhoard email or username
|
|
3. **Password**: Your Bookhoard 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 Bookhoard instance is running
|
|
- Verify username and password are correct
|
|
|
|
## Using Sync Features
|
|
|
|
### Initial Sync
|
|
|
|
When you first enable sync, KOReader will:
|
|
|
|
1. Connect to Bookhoard
|
|
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 Bookhoard - 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 Bookhoard 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**: Bookhoard (or any name you prefer)
|
|
- **URL**: Paste your OPDS URL from Step 1
|
|
5. Tap **Save**
|
|
|
|
Your Bookhoard library now appears in KOReader's home screen!
|
|
|
|
### Browse and Download Books
|
|
|
|
#### Browse Your Library
|
|
|
|
1. Tap **Bookhoard** 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 Bookhoard 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 Bookhoard library
|
|
- Progress syncs automatically
|
|
|
|
#### Collection Integration
|
|
|
|
Your Bookhoard 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**: Bookhoard 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 Bookhoard server is running
|
|
5. Check Bookhoard 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 Bookhoard has the book file
|
|
5. Review Bookhoard logs for errors
|
|
|
|
#### Book Opens But Progress Doesn't Sync
|
|
|
|
**Problem**: Downloaded book doesn't sync progress
|
|
|
|
**Solutions**:
|
|
|
|
1. Verify book is matched to Bookhoard library
|
|
2. Check device sync settings are enabled
|
|
3. Try manual sync from device
|
|
4. Ensure book exists in Bookhoard with same hash
|
|
5. Check Bookhoard 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 Bookhoard requires token authentication:
|
|
|
|
1. Get token from Bookhoard 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 Bookhoard 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 Bookhoard web interface first
|
|
- Reset password if needed
|
|
|
|
### Sync Not Working
|
|
|
|
**Problem**: Changes not appearing in Bookhoard
|
|
|
|
**Solutions**:
|
|
|
|
- Enable debug logging in KOReader
|
|
- Check Bookhoard Device Management page for errors
|
|
- Verify sync is enabled in KOReader settings
|
|
- Try manual sync to trigger immediate update
|
|
- Check Bookhoard logs for sync errors
|
|
|
|
### Conflicts Detected
|
|
|
|
**Problem**: Sync conflicts when reading on multiple devices
|
|
|
|
**Solutions**:
|
|
|
|
1. Go to Bookhoard **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 Bookhoard 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 Bookhoard publicly, configure SSL/TLS
|
|
2. **Strong Password**: Use a secure password for your Bookhoard 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)
|
|
- [Bookhoard Universal Sync Guide](../sync-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 Bookhoard sync queue and device management pages
|
|
4. Open an issue on the Bookhoard GitHub repository
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-01-31
|
|
**Bookhoard Version**: 1.0
|
|
**KOReader Version**: 2024.01+
|