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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user