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.
2026-02-01 01:02:09 -05:00
parent 25c0f95d4a
commit 8ce6fa2011
2 changed files with 403 additions and 0 deletions
@@ -170,6 +170,201 @@ Kobo syncs:
 - **Shelf Contents**: Books in each collection
 - **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

 Configure how often Kobo syncs with Bookmann: