Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs(devices): add comprehensive OPDS wireless delivery documentation

Browse Source 
Update both Kobo and KOReader setup guides with OPDS workflow:

KOBO_SETUP.md Updates:
- New OPDS Wireless Book Delivery section
- Step-by-step OPDS configuration (automatic and manual)
- Browse and download books from Bookmann catalog
- Collection-based downloads
- Format support (EPUB, KEPUB, PDF)
- Automatic EPUB to KEPUB conversion
- Progress sync integration
- Collection to shelf mapping
- Troubleshooting section for OPDS issues
- OPDS vs USB transfer comparison table
- Advanced OPDS configuration options

KOREADER_SETUP.md Updates:
- OPDS catalog addition in KOReader
- Browse entire library wirelessly
- Download books and collections
- Automatic book matching
- Collection integration
- KOReader-specific OPDS settings
- Auto-download features
- Comprehensive troubleshooting
- OPDS tips and tricks
- Comparison table (OPDS vs USB)

Key Features Documented:
- Wireless book delivery (no USB cable needed)
- On-demand library browsing
- Collection-based organization
- Automatic progress sync for downloaded books
- Format conversion and optimization
- Device-specific configuration

Both guides now provide complete instructions for:
1. Setting up OPDS catalog on device
2. Browsing and downloading books
3. Troubleshooting common OPDS issues
4. Comparing wireless vs USB transfer methods
5. Advanced configuration options

This completes the OPDS documentation requirement for Phase 10.
This commit is contained in:
john-okeefe
2026-02-01 01:02:09 -05:00
parent 25c0f95d4a
commit 8ce6fa2011
2 changed files with 403 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/devices/KOREADER_SETUP.md
+208
View File
@@ -212,6 +212,214 @@ Enable debug logging if sync isn't working:
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