diff --git a/docs/devices/KOBO_SETUP.md b/docs/devices/KOBO_SETUP.md index ddbd616..b03fa52 100644 --- a/docs/devices/KOBO_SETUP.md +++ b/docs/devices/KOBO_SETUP.md @@ -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: diff --git a/docs/devices/KOREADER_SETUP.md b/docs/devices/KOREADER_SETUP.md index 23902b0..9aef6c0 100644 --- a/docs/devices/KOREADER_SETUP.md +++ b/docs/devices/KOREADER_SETUP.md @@ -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