docs: update comprehensive API documentation and project guides
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
This commit is contained in:
@@ -3,6 +3,7 @@
|
||||
**Coming Soon**
|
||||
|
||||
This guide will cover:
|
||||
|
||||
- User management
|
||||
- Library management
|
||||
- System monitoring
|
||||
@@ -12,4 +13,4 @@ This guide will cover:
|
||||
|
||||
---
|
||||
|
||||
*In the meantime, check out our [Operations Portal](../operations/)*
|
||||
_In the meantime, check out our [Operations Portal](../operations/)_
|
||||
|
||||
@@ -19,6 +19,7 @@ Smart sections are automatically generated based on your reading activity:
|
||||
Any collection marked with "Show on Dashboard" will appear as a section on your dashboard.
|
||||
|
||||
To enable a collection:
|
||||
|
||||
1. Go to Collections
|
||||
2. Edit a collection
|
||||
3. Toggle "Show on Dashboard"
|
||||
|
||||
@@ -5,6 +5,7 @@ This guide will help you set up your Kobo e-reader to sync with Bookhoard for se
|
||||
## What is Kobo Sync?
|
||||
|
||||
Bookhoard implements a Kobo-compatible sync protocol that allows your Kobo device to:
|
||||
|
||||
- Sync reading progress across all your devices
|
||||
- Sync highlights and bookmarks
|
||||
- Sync reading statistics
|
||||
@@ -13,6 +14,7 @@ Bookhoard implements a Kobo-compatible sync protocol that allows your Kobo devic
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, make sure you have:
|
||||
|
||||
- ✅ A Kobo e-reader device (Clara, Aura, Nia, Libra, Sage, Elipsa, etc.)
|
||||
- ✅ A Bookhoard instance running and accessible on your network
|
||||
- ✅ Your Bookhoard credentials (username and password)
|
||||
@@ -22,6 +24,7 @@ Before you begin, make sure you have:
|
||||
## Supported Kobo Devices
|
||||
|
||||
Bookhoard supports all Kobo devices that use the standard Kobo sync protocol:
|
||||
|
||||
- **Kobo Clara**: Clara 2E, Clara HD
|
||||
- **Kobo Aura**: Aura, Aura H2O, Aura ONE, Aura Edition 2
|
||||
- **Kobo Libra**: Libra 2, Libra H2O
|
||||
@@ -53,6 +56,7 @@ Bookhoard supports all Kobo devices that use the standard Kobo sync protocol:
|
||||
4. Click **Register Device**
|
||||
|
||||
You'll receive:
|
||||
|
||||
- An **Auth URL** to approve the device
|
||||
- Instructions for manual configuration
|
||||
|
||||
@@ -82,17 +86,20 @@ Your device is now registered and ready for configuration!
|
||||
### Step 2: Edit Kobo Configuration File
|
||||
|
||||
#### Windows Users
|
||||
|
||||
1. Open **File Explorer** and navigate to your Kobo device
|
||||
2. Open the `.kobo` folder (hidden folder)
|
||||
3. Open `Kobo/Kobo eReader.conf` in a text editor (Notepad++, VS Code, etc.)
|
||||
|
||||
#### Mac Users
|
||||
|
||||
1. Kobo device appears on your Desktop
|
||||
2. Right-click the Kobo volume and select **Show Package Contents**
|
||||
3. Navigate to `.kobo/Kobo/Kobo eReader.conf`
|
||||
4. Open in a text editor (TextEdit, VS Code, etc.)
|
||||
|
||||
#### Linux Users
|
||||
|
||||
1. Kobo mounts at `/media/USERNAME/Kobo` or similar
|
||||
2. Navigate to `.kobo/Kobo/Kobo eReader.conf`
|
||||
3. Open in a text editor
|
||||
@@ -116,10 +123,12 @@ SyncFrequency=5
|
||||
```
|
||||
|
||||
**Where to find these values**:
|
||||
|
||||
- `YOUR_COMPUTER_IP`: Your Bookhoard server's IP address (e.g., 192.168.1.100)
|
||||
- `YOUR_API_KEY`: Copy from Bookhoard Device Management → Your Kobo Device → "Copy Sync URL"
|
||||
|
||||
**Example configuration**:
|
||||
|
||||
```ini
|
||||
[Sync]
|
||||
ServerURL=http://192.168.1.100:8765/api/sync/kobo/dev_abc123def456
|
||||
@@ -128,17 +137,20 @@ SyncFrequency=5
|
||||
```
|
||||
|
||||
**Important Notes**:
|
||||
|
||||
- The API key is generated during device registration
|
||||
- You can regenerate the API key anytime from Device Management if needed
|
||||
- Keep your API key confidential like a password
|
||||
- Bookhoard uses revocable API keys for security (not username/password)
|
||||
|
||||
**Replace the following with your actual values**:
|
||||
|
||||
- `YOUR_COMPUTER_IP`: Your computer's local IP address (e.g., 192.168.1.100)
|
||||
- `YOUR_BOOKHOARD_USERNAME`: Your Bookhoard email or username
|
||||
- `YOUR_BOOKHOARD_PASSWORD`: Your Bookhoard password
|
||||
|
||||
**Example configuration:**
|
||||
|
||||
```ini
|
||||
[Sync]
|
||||
ServerURL=http://192.168.1.100:8765/api/sync/kobo
|
||||
@@ -166,6 +178,7 @@ Password=securePassword123
|
||||
### Reading Progress Sync
|
||||
|
||||
Kobo syncs:
|
||||
|
||||
- **Percentage Read**: Overall book completion percentage
|
||||
- **Page Number**: Current page in fixed-layout books
|
||||
- **Time Spent**: Reading time statistics
|
||||
@@ -174,6 +187,7 @@ Kobo syncs:
|
||||
### Annotations Sync
|
||||
|
||||
Kobo syncs:
|
||||
|
||||
- **Bookmarks**: Page positions saved for quick access
|
||||
- **Highlights**: Highlighted text passages
|
||||
- **Notes**: Notes attached to highlights
|
||||
@@ -182,6 +196,7 @@ Kobo syncs:
|
||||
### Shelf Management
|
||||
|
||||
Kobo syncs:
|
||||
|
||||
- **Book Collections**: Your organized shelves
|
||||
- **Shelf Contents**: Books in each collection
|
||||
- **Sync Metadata**: When shelves were last updated
|
||||
@@ -272,6 +287,7 @@ OPDSCatalogURL=http://YOUR_COMPUTER_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog?
|
||||
#### Format Support
|
||||
|
||||
Kobo OPDS supports:
|
||||
|
||||
- **EPUB**: Standard ebook format (recommended)
|
||||
- **KEPUB**: Kobo-optimized EPUB (better page turns, fonts)
|
||||
- **PDF**: Fixed-layout documents
|
||||
@@ -281,6 +297,7 @@ Kobo OPDS supports:
|
||||
#### 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 Bookhoard automatically
|
||||
@@ -289,6 +306,7 @@ Books downloaded via OPDS automatically sync progress:
|
||||
#### Collection to Shelf Mapping
|
||||
|
||||
Bookhoard maps your collections to Kobo shelves:
|
||||
|
||||
- Collection **"Science Fiction"** → Kobo shelf **"Sci-Fi"**
|
||||
- Collection **"To Read"** → Kobo shelf **"To Read"**
|
||||
- Customizable in Bookhoard Device Management
|
||||
@@ -300,6 +318,7 @@ Bookhoard maps your collections to Kobo shelves:
|
||||
**Problem**: Bookhoard 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
|
||||
@@ -311,6 +330,7 @@ Bookhoard maps your collections to Kobo shelves:
|
||||
**Problem**: Book download starts but fails partway through
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check Wi-Fi signal strength
|
||||
2. Ensure Bookhoard server is running
|
||||
3. Verify book file exists in Bookhoard library
|
||||
@@ -322,6 +342,7 @@ Bookhoard maps your collections to Kobo shelves:
|
||||
**Problem**: Downloaded book shows error when opening
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Verify book format is supported (EPUB/KEPUB/PDF)
|
||||
2. Check file isn't corrupted in Bookhoard
|
||||
3. Try downloading via USB and opening
|
||||
@@ -333,6 +354,7 @@ Bookhoard maps your collections to Kobo shelves:
|
||||
**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
|
||||
@@ -341,14 +363,14 @@ Bookhoard maps your collections to Kobo shelves:
|
||||
|
||||
### 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 |
|
||||
| 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).
|
||||
|
||||
@@ -455,6 +477,7 @@ Kobo will automatically trust the certificate if properly configured.
|
||||
**Problem**: Sync doesn't happen automatically
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check Kobo is connected to Wi-Fi
|
||||
2. Verify `AutoSyncEnabled=true` in config
|
||||
3. Check `SyncFrequency` is not set to 0
|
||||
@@ -466,6 +489,7 @@ Kobo will automatically trust the certificate if properly configured.
|
||||
**Problem**: "Connection refused" or "Server not reachable"
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Verify Bookhoard is running on your computer
|
||||
2. Check the server URL and IP address are correct
|
||||
3. Ensure Kobo is on same Wi-Fi network as computer
|
||||
@@ -475,8 +499,9 @@ Kobo will automatically trust the certificate if properly configured.
|
||||
### Authentication Failed
|
||||
|
||||
**Problem**: "Authentication failed" or "Invalid API key"
|
||||
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Verify the API key in your sync URL matches the one in Bookhoard Device Management
|
||||
2. Check that device is approved in Bookhoard (not pending)
|
||||
3. Try regenerating the API key from Device Management page
|
||||
@@ -488,6 +513,7 @@ Kobo will automatically trust the certificate if properly configured.
|
||||
**Problem**: Changes to `Kobo eReader.conf` are lost
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Make sure Kobo is ejected safely after editing
|
||||
2. Check file permissions (should be writable)
|
||||
3. Try a different text editor (Notepad++, VS Code, Sublime Text)
|
||||
@@ -499,6 +525,7 @@ Kobo will automatically trust the certificate if properly configured.
|
||||
**Problem**: Manual sync works, but auto-sync doesn't
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Verify `AutoSyncEnabled=true` in config
|
||||
2. Check `SyncFrequency` is not 0
|
||||
3. Kobo only syncs when connected to Wi-Fi
|
||||
@@ -510,6 +537,7 @@ Kobo will automatically trust the certificate if properly configured.
|
||||
**Problem**: Books added to Bookhoard don't show on Kobo
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Kobo needs books to be sideloaded (manually transferred via USB)
|
||||
2. Bookhoard syncs PROGRESS, not book files
|
||||
3. Transfer book files to Kobo's `Documents` folder via USB
|
||||
@@ -521,6 +549,7 @@ Kobo will automatically trust the certificate if properly configured.
|
||||
**Problem**: Conflicts between devices aren't being detected
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check Bookhoard Conflicts page
|
||||
2. Ensure both devices have synced recently
|
||||
3. Conflicts only detected when progress differs within 5 minutes
|
||||
@@ -540,6 +569,7 @@ Kobo will automatically trust the certificate if properly configured.
|
||||
### Local Network (Recommended)
|
||||
|
||||
For home use, keep Kobo and Bookhoard on the same local network:
|
||||
|
||||
```
|
||||
Kobo Wi-Fi: 192.168.1.x
|
||||
Bookhoard: 192.168.1.x
|
||||
@@ -548,6 +578,7 @@ Bookhoard: 192.168.1.x
|
||||
### Remote Access
|
||||
|
||||
For access outside your home network:
|
||||
|
||||
1. Set up port forwarding on your router (port 8765)
|
||||
2. Configure SSL/TLS on Bookhoard
|
||||
3. Use a dynamic DNS service for constant hostname
|
||||
@@ -562,6 +593,7 @@ For access outside your home network:
|
||||
### Battery Life
|
||||
|
||||
To extend Kobo battery life:
|
||||
|
||||
1. Use longer sync intervals (15-30 minutes)
|
||||
2. Sync only on Wi-Fi (not cellular if your Kobo has it)
|
||||
3. Disable unnecessary Kobo features
|
||||
@@ -570,6 +602,7 @@ To extend Kobo battery life:
|
||||
### Sync Speed
|
||||
|
||||
To improve sync speed:
|
||||
|
||||
1. Ensure strong Wi-Fi signal
|
||||
2. Use local network (not remote access)
|
||||
3. Keep Bookhoard and Kobo on same network
|
||||
@@ -603,6 +636,7 @@ A: Only if Wi-Fi is enabled and configured to stay active during sleep.
|
||||
## Support
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. Check the troubleshooting section above
|
||||
2. Review Kobo sync logs in device settings
|
||||
3. Check Bookhoard sync queue and device management pages
|
||||
|
||||
@@ -5,6 +5,7 @@ This guide will help you set up KOReader on your e-reader device to sync with Bo
|
||||
## 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
|
||||
@@ -13,6 +14,7 @@ KOReader is an open-source e-reader application that supports a wide range of e-
|
||||
## 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
|
||||
@@ -67,6 +69,7 @@ Before you begin, make sure you have:
|
||||
### 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`
|
||||
@@ -84,6 +87,7 @@ Find your Bookhoard instance URL. This will typically be one of:
|
||||
4. Click **Register Device**
|
||||
|
||||
You'll receive:
|
||||
|
||||
- An **Auth URL** to approve the device
|
||||
- A **Device Token** (automatically generated after approval)
|
||||
|
||||
@@ -114,9 +118,11 @@ Your device is now registered and ready to sync!
|
||||
|
||||
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`
|
||||
@@ -157,6 +163,7 @@ Your device is now registered and ready to sync!
|
||||
### 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
|
||||
@@ -165,6 +172,7 @@ When you first enable sync, KOReader will:
|
||||
### 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
|
||||
@@ -179,11 +187,13 @@ As you read:
|
||||
### 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
|
||||
@@ -193,6 +203,7 @@ The sync status will display:
|
||||
### 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
|
||||
@@ -200,6 +211,7 @@ KOReader automatically handles offline scenarios:
|
||||
### 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)
|
||||
@@ -208,6 +220,7 @@ For better battery life, use checkpoint mode:
|
||||
### 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`
|
||||
@@ -279,6 +292,7 @@ Your Bookhoard library now appears in KOReader's home screen!
|
||||
#### Supported Formats
|
||||
|
||||
KOReader OPDS supports:
|
||||
|
||||
- **EPUB**: Standard ebook format
|
||||
- **KEPUB**: Kobo-optimized format (KOReader handles this well)
|
||||
- **PDF**: Fixed-layout documents
|
||||
@@ -289,6 +303,7 @@ KOReader OPDS supports:
|
||||
#### 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
|
||||
@@ -297,6 +312,7 @@ Books downloaded via OPDS are automatically matched:
|
||||
#### Collection Integration
|
||||
|
||||
Your Bookhoard collections appear in KOReader:
|
||||
|
||||
- Collection **"To Read"** → KOReader category
|
||||
- Collection **"Science Fiction"** → Browseable section
|
||||
- Custom collections → Preserved organization
|
||||
@@ -306,6 +322,7 @@ Your Bookhoard collections appear in KOReader:
|
||||
#### 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
|
||||
@@ -313,6 +330,7 @@ Configure how often KOReader checks for new books:
|
||||
#### 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)
|
||||
@@ -320,6 +338,7 @@ Choose where to store downloaded books:
|
||||
#### Auto-Download
|
||||
|
||||
Automatically download new books from collections:
|
||||
|
||||
1. KOReader menu → Tools → OPDS
|
||||
2. Enable **Auto-Download New Books**
|
||||
3. Select collections to monitor
|
||||
@@ -332,6 +351,7 @@ Automatically download new books from collections:
|
||||
**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
|
||||
@@ -343,6 +363,7 @@ Automatically download new books from collections:
|
||||
**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
|
||||
@@ -354,6 +375,7 @@ Automatically download new books from collections:
|
||||
**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
|
||||
@@ -365,6 +387,7 @@ Automatically download new books from collections:
|
||||
**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
|
||||
@@ -401,14 +424,14 @@ 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 |
|
||||
| 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.
|
||||
|
||||
@@ -427,6 +450,7 @@ OPDSCompressionEnabled = true
|
||||
**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
|
||||
@@ -437,6 +461,7 @@ OPDSCompressionEnabled = true
|
||||
**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
|
||||
@@ -447,6 +472,7 @@ OPDSCompressionEnabled = true
|
||||
**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
|
||||
@@ -458,6 +484,7 @@ OPDSCompressionEnabled = true
|
||||
**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
|
||||
@@ -468,6 +495,7 @@ OPDSCompressionEnabled = true
|
||||
**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
|
||||
@@ -491,6 +519,7 @@ OPDSCompressionEnabled = true
|
||||
## 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
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
**Coming Soon**
|
||||
|
||||
This guide will cover:
|
||||
|
||||
- Navigating the Bookhoard web interface
|
||||
- Browsing and searching your library
|
||||
- Managing collections
|
||||
@@ -12,4 +13,4 @@ This guide will cover:
|
||||
|
||||
---
|
||||
|
||||
*In the meantime, check out our [Device Setup Guides](devices/)*
|
||||
_In the meantime, check out our [Device Setup Guides](devices/)_
|
||||
|
||||
@@ -47,6 +47,7 @@ Regular password changes are recommended for account security.
|
||||
### What Gets Deleted
|
||||
|
||||
When you delete your account:
|
||||
|
||||
- Your profile information
|
||||
- Reading progress and history
|
||||
- Device connections
|
||||
@@ -88,7 +89,7 @@ Personalize your reading experience with different color themes.
|
||||
- **One Dark Pro** - Atom editor inspired
|
||||
- **Material Dark** - Google Material Design
|
||||
- **Wood Light** - Light wood texture
|
||||
- **Wood Dark** - Dark wood texture
|
||||
- **Wood Dark** - Dark wood texture
|
||||
- **Wood Mahogany** - Reddish-brown wood
|
||||
|
||||
## For Admin Users
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
**Coming Soon**
|
||||
|
||||
This guide will cover:
|
||||
|
||||
- Account settings
|
||||
- Display preferences (themes, fonts)
|
||||
- Sync configuration
|
||||
@@ -11,4 +12,4 @@ This guide will cover:
|
||||
|
||||
---
|
||||
|
||||
*In the meantime, check out our [Device Setup Guides](devices/)*
|
||||
_In the meantime, check out our [Device Setup Guides](devices/)_
|
||||
|
||||
+53
-10
@@ -1,6 +1,7 @@
|
||||
# Bookhoard Universal Sync - User Guide
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [What is Universal Sync?](#what-is-universal-sync)
|
||||
2. [Supported Devices](#supported-devices)
|
||||
3. [Getting Started](#getting-started)
|
||||
@@ -36,19 +37,19 @@
|
||||
|
||||
### Currently Supported ✅
|
||||
|
||||
| Platform | Status | Sync Method | Notes |
|
||||
|----------|--------|-------------|-------|
|
||||
| **Web Browser** | ✅ Fully Supported | Real-time WebSocket | Any modern browser |
|
||||
| **KOReader** | ✅ Fully Supported | Wi-Fi (Calibre-compatible) | Kindle, Kobo, PocketBook, etc. |
|
||||
| **Kobo Devices** | ✅ Fully Supported | Wi-Fi (Kobo API-compatible) | Clara, Libra, Sage, etc. |
|
||||
| Platform | Status | Sync Method | Notes |
|
||||
| ---------------- | ------------------ | --------------------------- | ------------------------------ |
|
||||
| **Web Browser** | ✅ Fully Supported | Real-time WebSocket | Any modern browser |
|
||||
| **KOReader** | ✅ Fully Supported | Wi-Fi (Calibre-compatible) | Kindle, Kobo, PocketBook, etc. |
|
||||
| **Kobo Devices** | ✅ Fully Supported | Wi-Fi (Kobo API-compatible) | Clara, Libra, Sage, etc. |
|
||||
|
||||
### Coming Soon 🚧
|
||||
|
||||
| Platform | Expected Release |
|
||||
|----------|------------------|
|
||||
| **Mobile Apps** | Q2 2026 |
|
||||
| **Kindle Devices** | Q3 2026 |
|
||||
| **Remarkable Tablet** | Q4 2026 |
|
||||
| Platform | Expected Release |
|
||||
| --------------------- | ---------------- |
|
||||
| **Mobile Apps** | Q2 2026 |
|
||||
| **Kindle Devices** | Q3 2026 |
|
||||
| **Remarkable Tablet** | Q4 2026 |
|
||||
|
||||
---
|
||||
|
||||
@@ -79,17 +80,20 @@ For detailed device configuration instructions, see the appropriate setup guide:
|
||||
### Quick Overview
|
||||
|
||||
**Registration Process**:
|
||||
|
||||
1. Register device in Bookhoard web interface (Settings → Devices)
|
||||
2. Approve device via QR code or approval URL
|
||||
3. Configure sync settings on your device
|
||||
4. Start reading - progress syncs automatically!
|
||||
|
||||
**Device Management**:
|
||||
|
||||
```
|
||||
Settings → Devices
|
||||
```
|
||||
|
||||
You can:
|
||||
|
||||
- View all your registered devices
|
||||
- See last sync time and status
|
||||
- Disable or remove devices
|
||||
@@ -103,6 +107,7 @@ You can:
|
||||
### What is Book Matching?
|
||||
|
||||
When devices sync books, Bookhoard tries to automatically match them using:
|
||||
|
||||
- **SHA-256 hash** (most reliable) - Content-based fingerprint
|
||||
- **ISBN** - Standard book identifier
|
||||
- **UUID** - Unique identifier from EPUB metadata
|
||||
@@ -111,6 +116,7 @@ When devices sync books, Bookhoard tries to automatically match them using:
|
||||
### Unlinked Books
|
||||
|
||||
Sometimes a book on your device can't be automatically matched to your library. This happens when:
|
||||
|
||||
- The book was side-loaded (not downloaded via Bookhoard)
|
||||
- The file format was converted (EPUB → KEPUB)
|
||||
- The metadata doesn't match exactly
|
||||
@@ -143,6 +149,7 @@ Settings → Devices → Select Device → View Unlinked Books
|
||||
### Reading Progress
|
||||
|
||||
**What Syncs**:
|
||||
|
||||
- Current page number
|
||||
- Reading percentage
|
||||
- Chapter progress
|
||||
@@ -151,6 +158,7 @@ Settings → Devices → Select Device → View Unlinked Books
|
||||
- Reading position (viewport, zoom, scroll)
|
||||
|
||||
**How It Works**:
|
||||
|
||||
```
|
||||
You turn page → Device sends progress → Server updates database
|
||||
↓
|
||||
@@ -160,6 +168,7 @@ You turn page → Device sends progress → Server updates database
|
||||
```
|
||||
|
||||
**Supported Progress Types**:
|
||||
|
||||
- **EPUB/MOBI**: Percentage + EPUB CFI + Chapter
|
||||
- **PDF/DJVU**: Page number + Viewport position
|
||||
- **CBZ/CBR**: Page number + Panel coordinates
|
||||
@@ -167,6 +176,7 @@ You turn page → Device sends progress → Server updates database
|
||||
### Highlights & Notes
|
||||
|
||||
**What Syncs**:
|
||||
|
||||
- Highlighted text
|
||||
- Notes and annotations
|
||||
- Bookmark locations
|
||||
@@ -175,6 +185,7 @@ You turn page → Device sends progress → Server updates database
|
||||
|
||||
**Universal Location References**:
|
||||
All highlights are stored with multiple location types:
|
||||
|
||||
- Page:offset (traditional)
|
||||
- EPUB CFI (EPUB files)
|
||||
- Percentage (0-100%)
|
||||
@@ -186,6 +197,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
### Bookmarks
|
||||
|
||||
**What Syncs**:
|
||||
|
||||
- Bookmark locations
|
||||
- Bookmark titles
|
||||
- Date created
|
||||
@@ -200,12 +212,14 @@ This ensures your highlights work across all devices, even with different page c
|
||||
**Best For**: Normal reading, page turns
|
||||
|
||||
**Behavior**:
|
||||
|
||||
- Syncs every page turn
|
||||
- Real-time updates
|
||||
- Low latency
|
||||
- Higher bandwidth usage
|
||||
|
||||
**Recommended Settings**:
|
||||
|
||||
- Auto-sync: ON
|
||||
- Sync frequency: Every page turn
|
||||
|
||||
@@ -214,12 +228,14 @@ This ensures your highlights work across all devices, even with different page c
|
||||
**Best For**: Slow connections, battery saving
|
||||
|
||||
**Behavior**:
|
||||
|
||||
- Batches changes
|
||||
- Syncs every 5 minutes or when connection allows
|
||||
- Lower bandwidth
|
||||
- Better for offline reading
|
||||
|
||||
**Recommended Settings**:
|
||||
|
||||
- Auto-sync: ON
|
||||
- Sync frequency: Checkpoint mode
|
||||
|
||||
@@ -247,11 +263,13 @@ This ensures your highlights work across all devices, even with different page c
|
||||
### Offline Indicators
|
||||
|
||||
**In Web Interface**:
|
||||
|
||||
- Yellow status icon: Device offline
|
||||
- Last seen timestamp
|
||||
- "Pending sync" badge on books
|
||||
|
||||
**On Devices**:
|
||||
|
||||
- Sync icon: Gray = offline
|
||||
- Sync icon: Blue = syncing
|
||||
- Sync icon: Green = synced
|
||||
@@ -265,6 +283,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
**Symptoms**: Progress not updating across devices
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check device is online: `Settings → Devices`
|
||||
2. Verify sync is enabled for the device
|
||||
3. Check sync URL is correct
|
||||
@@ -276,6 +295,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
**Cause**: Device not registered or authorization revoked
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Re-register the device
|
||||
2. Check device hasn't been removed
|
||||
3. Verify correct device type selected
|
||||
@@ -285,6 +305,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
**Cause**: Too many sync requests
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Wait a few seconds
|
||||
2. Switch to checkpoint mode
|
||||
3. Contact admin to increase limits
|
||||
@@ -296,6 +317,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
**Cause**: Same book being read on multiple devices simultaneously
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Go to `Settings → Conflicts`
|
||||
2. Review both device progress
|
||||
3. Choose which device's progress to keep
|
||||
@@ -306,6 +328,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
**Cause**: Immediate sync mode with frequent page turns
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Switch to checkpoint mode
|
||||
2. Increase sync interval
|
||||
3. Use Wi-Fi instead of cellular (for mobile)
|
||||
@@ -317,6 +340,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
### For Optimal Performance
|
||||
|
||||
✅ **DO**:
|
||||
|
||||
- Use checkpoint mode when on cellular data
|
||||
- Keep device firmware updated
|
||||
- Use Wi-Fi when available
|
||||
@@ -324,6 +348,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
- Regularly check conflict resolution
|
||||
|
||||
❌ **DON'T**:
|
||||
|
||||
- Read same book on multiple devices simultaneously
|
||||
- Ignore conflict notifications
|
||||
- Register public/shared devices
|
||||
@@ -332,6 +357,7 @@ This ensures your highlights work across all devices, even with different page c
|
||||
### Organizing Your Library
|
||||
|
||||
**For Best Sync Experience**:
|
||||
|
||||
- Use consistent metadata (titles, authors)
|
||||
- Avoid duplicate books in library
|
||||
- Match files by ISBN when possible
|
||||
@@ -340,11 +366,13 @@ This ensures your highlights work across all devices, even with different page c
|
||||
### Managing Multiple Devices
|
||||
|
||||
**Recommended Setup**:
|
||||
|
||||
- **Primary Device**: KOReader on e-reader
|
||||
- **Secondary Device**: Web browser (work/home)
|
||||
- **Mobile Device**: Phone app (commute)
|
||||
|
||||
**Sync Strategy**:
|
||||
|
||||
1. Read mainly on primary device
|
||||
2. Check progress on web/secondary devices
|
||||
3. Let auto-sync handle updates
|
||||
@@ -357,16 +385,19 @@ This ensures your highlights work across all devices, even with different page c
|
||||
### Conflict Resolution
|
||||
|
||||
**Automatic Resolution**:
|
||||
|
||||
- Most recent progress wins
|
||||
- Timestamp-based comparison
|
||||
- 5-minute window for conflict detection
|
||||
|
||||
**Manual Resolution**:
|
||||
|
||||
```
|
||||
Settings → Conflicts → Select conflict → Choose winner
|
||||
```
|
||||
|
||||
**Options**:
|
||||
|
||||
- **Keep Device A**: Use this device's progress
|
||||
- **Keep Device B**: Use other device's progress
|
||||
- **Merge**: Keep furthest progress (combination)
|
||||
@@ -375,17 +406,20 @@ Settings → Conflicts → Select conflict → Choose winner
|
||||
### Sync Queue Management
|
||||
|
||||
**View Queue Status**:
|
||||
|
||||
```
|
||||
Settings → Devices → Select Device → View Queue
|
||||
```
|
||||
|
||||
**Queue Stats**:
|
||||
|
||||
- Pending: Waiting to sync
|
||||
- Processing: Currently syncing
|
||||
- Failed: Retry scheduled
|
||||
- Completed: Successfully synced
|
||||
|
||||
**Manual Actions**:
|
||||
|
||||
- **Retry All**: Retry all failed items
|
||||
- **Clear Queue**: Remove all pending items
|
||||
- **Priority Sync**: Sync specific book immediately
|
||||
@@ -393,17 +427,20 @@ Settings → Devices → Select Device → View Queue
|
||||
### Reading History
|
||||
|
||||
**Automatic Tracking**:
|
||||
|
||||
- Every sync session logged
|
||||
- Time spent reading calculated
|
||||
- Pages read tracked
|
||||
- Device used recorded
|
||||
|
||||
**View History**:
|
||||
|
||||
```
|
||||
Book → Reading History
|
||||
```
|
||||
|
||||
**Privacy**:
|
||||
|
||||
- Only you can see your history
|
||||
- History kept for 365 days
|
||||
- Exportable for backup
|
||||
@@ -415,6 +452,7 @@ Book → Reading History
|
||||
### Device Authentication
|
||||
|
||||
**Secure by Design**:
|
||||
|
||||
- ✅ No passwords stored on devices
|
||||
- ✅ Web-based approval required
|
||||
- ✅ Unique tokens per device
|
||||
@@ -424,12 +462,14 @@ Book → Reading History
|
||||
### Data Protection
|
||||
|
||||
**What We Store**:
|
||||
|
||||
- Reading progress (page, percentage)
|
||||
- Highlights and notes
|
||||
- Device identifiers
|
||||
- Sync timestamps
|
||||
|
||||
**What We DON'T Store**:
|
||||
|
||||
- Passwords on devices
|
||||
- Reading content (your books)
|
||||
- Unencrypted personal data
|
||||
@@ -438,11 +478,13 @@ Book → Reading History
|
||||
### Access Control
|
||||
|
||||
**Your Data**:
|
||||
|
||||
- Only you can see your progress
|
||||
- Admins cannot read your annotations
|
||||
- Shared only with devices you approve
|
||||
|
||||
**Device Access**:
|
||||
|
||||
- Each device sees only your libraries
|
||||
- Devices cannot access other users
|
||||
- Revoking removes all access
|
||||
@@ -530,6 +572,7 @@ A: Yes, HTTPS/TLS 1.3 for all sync traffic.
|
||||
## Changelog
|
||||
|
||||
### Version 1.0.0 (January 2026)
|
||||
|
||||
- ✅ Initial release
|
||||
- ✅ KOReader sync support
|
||||
- ✅ Kobo device support
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
**Coming Soon**
|
||||
|
||||
This guide will cover:
|
||||
|
||||
- Managing your personal library
|
||||
- Uploading and organizing books
|
||||
- Creating and managing collections
|
||||
@@ -11,4 +12,4 @@ This guide will cover:
|
||||
|
||||
---
|
||||
|
||||
*In the meantime, check out our [Sync Guide](sync-guide.md)*
|
||||
_In the meantime, check out our [Sync Guide](sync-guide.md)_
|
||||
|
||||
@@ -30,22 +30,26 @@ Learn how to configure your e-reader devices to sync with Bookhoard:
|
||||
## 🎨 Frontend Guide
|
||||
|
||||
**[Frontend Guide](frontend-guide.md)** - Learn how to use the Bookhoard web interface
|
||||
- *Coming Soon*
|
||||
|
||||
- _Coming Soon_
|
||||
|
||||
## 👤 User Areas
|
||||
|
||||
**[User Areas Guide](user-areas.md)** - Managing your personal library and settings
|
||||
- *Coming Soon*
|
||||
|
||||
- _Coming Soon_
|
||||
|
||||
## ⚙️ Settings
|
||||
|
||||
**[Settings Guide](settings-guide.md)** - Configuring your Bookhoard preferences
|
||||
- *Coming Soon*
|
||||
|
||||
- _Coming Soon_
|
||||
|
||||
## 🔐 Admin Features
|
||||
|
||||
**[Admin Guide](admin-guide.md)** - Administrative functions and management
|
||||
- *Coming Soon*
|
||||
|
||||
- _Coming Soon_
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user