docs(devices): add comprehensive OPDS wireless delivery documentation
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:
@@ -170,6 +170,201 @@ Kobo syncs:
|
|||||||
- **Shelf Contents**: Books in each collection
|
- **Shelf Contents**: Books in each collection
|
||||||
- **Sync Metadata**: When shelves were last updated
|
- **Sync Metadata**: When shelves were last updated
|
||||||
|
|
||||||
|
## OPDS Wireless Book Delivery
|
||||||
|
|
||||||
|
### What is OPDS?
|
||||||
|
|
||||||
|
OPDS (Open Publication Distribution System) allows your Kobo to **wirelessly download books** from Bookmann - no USB cable needed!
|
||||||
|
|
||||||
|
### OPDS Benefits
|
||||||
|
|
||||||
|
- **No USB Required**: Download books directly to your Kobo over Wi-Fi
|
||||||
|
- **On-Demand Delivery**: Browse your Bookmann library from your Kobo
|
||||||
|
- **Collection Support**: Download books from specific collections
|
||||||
|
- **Progress Tracking**: Books downloaded via OPDS sync progress automatically
|
||||||
|
- **Format Conversion**: Automatic EPUB to KEPUB conversion for better Kobo support
|
||||||
|
|
||||||
|
### Enable OPDS on Your Kobo
|
||||||
|
|
||||||
|
#### Option 1: Automatic Configuration (Recommended)
|
||||||
|
|
||||||
|
1. After registering your Kobo device, a **Download Configuration** button appears
|
||||||
|
2. Click **Download Configuration** to get a `.kobo` configuration file
|
||||||
|
3. Copy this file to your Kobo's `.kobo/` directory via USB
|
||||||
|
4. Eject and restart your Kobo
|
||||||
|
5. OPDS catalog will automatically appear in your Kobo's store
|
||||||
|
|
||||||
|
#### Option 2: Manual Configuration
|
||||||
|
|
||||||
|
1. Connect your Kobo to your computer via USB
|
||||||
|
2. Navigate to `.kobo/Kobo/Kobo eReader.conf`
|
||||||
|
3. Add the following configuration:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[FeatureSettings]
|
||||||
|
# Enable OPDS catalog
|
||||||
|
OPDSCatalogEnabled=true
|
||||||
|
OPDSCatalogURL=http://YOUR_COMPUTER_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog
|
||||||
|
|
||||||
|
# Example:
|
||||||
|
# OPDSCatalogURL=http://192.168.1.100:8765/opds/devices/kobo-clara-123/catalog
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Replace:
|
||||||
|
- `YOUR_COMPUTER_IP`: Your Bookmann server IP
|
||||||
|
- `YOUR_DEVICE_ID`: Your Kobo's device ID from Bookmann Device Management
|
||||||
|
|
||||||
|
5. Save the file and safely eject your Kobo
|
||||||
|
|
||||||
|
### Access OPDS Catalog on Kobo
|
||||||
|
|
||||||
|
1. Wake your Kobo and connect to Wi-Fi
|
||||||
|
2. Go to **Home** → **Store** (or **Shop**)
|
||||||
|
3. You'll see **Bookmann** listed as a store
|
||||||
|
4. Tap to enter the Bookmann catalog
|
||||||
|
|
||||||
|
### Browse and Download Books
|
||||||
|
|
||||||
|
#### Browse All Books
|
||||||
|
|
||||||
|
1. In the Bookmann catalog, you'll see all books from your library
|
||||||
|
2. Browse by:
|
||||||
|
- **Recently Added**: Latest books in your library
|
||||||
|
- **Collections**: Books organized by collections
|
||||||
|
- **Authors**: Books grouped by author
|
||||||
|
- **Series**: Books in reading order
|
||||||
|
|
||||||
|
#### Download a Book
|
||||||
|
|
||||||
|
1. Tap on any book cover to see details
|
||||||
|
2. Tap **Download** or **Add to Library**
|
||||||
|
3. The book downloads wirelessly to your Kobo
|
||||||
|
4. Progress bar shows download status
|
||||||
|
5. Once downloaded, the book appears in your **Home** library
|
||||||
|
|
||||||
|
#### Download from Collections
|
||||||
|
|
||||||
|
1. In the Bookmann catalog, tap **Collections**
|
||||||
|
2. Select a collection (e.g., "Science Fiction")
|
||||||
|
3. Browse books in that collection
|
||||||
|
4. Tap to download individual books
|
||||||
|
5. Or tap **Download All** to get entire collection
|
||||||
|
|
||||||
|
### OPDS Features
|
||||||
|
|
||||||
|
#### Format Support
|
||||||
|
|
||||||
|
Kobo OPDS supports:
|
||||||
|
- **EPUB**: Standard ebook format (recommended)
|
||||||
|
- **KEPUB**: Kobo-optimized EPUB (better page turns, fonts)
|
||||||
|
- **PDF**: Fixed-layout documents
|
||||||
|
|
||||||
|
**Automatic Conversion**: Bookmann automatically converts EPUB to KEPUB on-the-fly for better Kobo experience.
|
||||||
|
|
||||||
|
#### Progress Sync
|
||||||
|
|
||||||
|
Books downloaded via OPDS automatically sync progress:
|
||||||
|
1. Download a book via OPDS
|
||||||
|
2. Start reading on your Kobo
|
||||||
|
3. Progress syncs to Bookmann automatically
|
||||||
|
4. Continue reading on any other device!
|
||||||
|
|
||||||
|
#### Collection to Shelf Mapping
|
||||||
|
|
||||||
|
Bookmann maps your collections to Kobo shelves:
|
||||||
|
- Collection **"Science Fiction"** → Kobo shelf **"Sci-Fi"**
|
||||||
|
- Collection **"To Read"** → Kobo shelf **"To Read"**
|
||||||
|
- Customizable in Bookmann Device Management
|
||||||
|
|
||||||
|
### OPDS Troubleshooting
|
||||||
|
|
||||||
|
#### Catalog Not Appearing
|
||||||
|
|
||||||
|
**Problem**: Bookmann catalog doesn't show in Kobo store
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Verify OPDS URL is correct in config file
|
||||||
|
2. Check Kobo is connected to Wi-Fi
|
||||||
|
3. Try accessing OPDS URL in your browser
|
||||||
|
4. Ensure device ID matches Bookmann device ID
|
||||||
|
5. Restart Kobo after editing config file
|
||||||
|
|
||||||
|
#### Download Fails
|
||||||
|
|
||||||
|
**Problem**: Book download starts but fails partway through
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Check Wi-Fi signal strength
|
||||||
|
2. Ensure Bookmann server is running
|
||||||
|
3. Verify book file exists in Bookmann library
|
||||||
|
4. Try downloading a smaller book first
|
||||||
|
5. Check Bookmann logs for errors
|
||||||
|
|
||||||
|
#### Book Downloads But Won't Open
|
||||||
|
|
||||||
|
**Problem**: Downloaded book shows error when opening
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Verify book format is supported (EPUB/KEPUB/PDF)
|
||||||
|
2. Check file isn't corrupted in Bookmann
|
||||||
|
3. Try downloading via USB and opening
|
||||||
|
4. Check Kobo has sufficient free storage
|
||||||
|
5. Restart your Kobo device
|
||||||
|
|
||||||
|
#### Slow Download Speed
|
||||||
|
|
||||||
|
**Problem**: Books take too long to download
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Ensure strong Wi-Fi signal (stay near router)
|
||||||
|
2. Use 5GHz Wi-Fi if your Kobo supports it
|
||||||
|
3. Close other apps using bandwidth
|
||||||
|
4. Download smaller books first
|
||||||
|
5. Consider using USB for large books
|
||||||
|
|
||||||
|
### 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** | ⭐⭐⭐⭐⭐ Automatic | ⭐⭐⭐⭐ After first sync |
|
||||||
|
| **Setup Complexity** | ⭐⭐⭐ Moderate | ⭐⭐⭐⭐⭐ Simple |
|
||||||
|
| **Reliability** | ⭐⭐⭐⭐ Good | ⭐⭐⭐⭐⭐ Excellent |
|
||||||
|
|
||||||
|
**Recommendation**: Use OPDS for convenience (1-5 books), use USB for bulk transfers (10+ books).
|
||||||
|
|
||||||
|
### Advanced OPDS Configuration
|
||||||
|
|
||||||
|
#### Custom Catalog Name
|
||||||
|
|
||||||
|
Change the name of the Bookmann catalog on your Kobo:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[OPDS]
|
||||||
|
CatalogName=My Library
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Auto-Download
|
||||||
|
|
||||||
|
Automatically download new books added to collections:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[OPDS]
|
||||||
|
AutoDownloadEnabled=true
|
||||||
|
AutoDownloadCollections=To Read,Recent
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Download Quality
|
||||||
|
|
||||||
|
Choose between original EPUB or converted KEPUB:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[OPDS]
|
||||||
|
PreferredFormat=kepub # Options: epub, kepub, auto
|
||||||
|
```
|
||||||
|
|
||||||
## Sync Frequency Options
|
## Sync Frequency Options
|
||||||
|
|
||||||
Configure how often Kobo syncs with Bookmann:
|
Configure how often Kobo syncs with Bookmann:
|
||||||
|
|||||||
@@ -212,6 +212,214 @@ Enable debug logging if sync isn't working:
|
|||||||
2. Enable **Debug Logging**
|
2. Enable **Debug Logging**
|
||||||
3. Sync and check logs at `/mnt/us/koreader/calibre.log`
|
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
|
## Troubleshooting
|
||||||
|
|
||||||
### Connection Refused
|
### Connection Refused
|
||||||
|
|||||||
Reference in New Issue
Block a user