Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: add implementation plan and update documentation

Browse Source 
- Add comprehensive implementation plan for universal sync system
- Update README with API reference and device setup guides
- Add KOBO_SETUP.md device configuration guide
This commit is contained in:
john-okeefe
2026-01-31 18:25:27 -05:00
parent ab8f4f5351
commit 33f26f3d7d
4 changed files with 3427 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
IMPLEMENTATION_PLAN.md
+1692
View File
File diff suppressed because it is too large Load Diff
README.md
+25 -4
View File
@@ -374,22 +374,43 @@ Complete API testing collection in `bruno/` directory:
```
bruno/
├── user/ # Authentication & profile endpoints
├── user/ # Authentication & profile endpoints
├── admin/ # Admin-only operations
├── library/ # Library management
├── media-items/ # Media content browsing
├── media-items/ # Media content browsing
├── ebooks/ # Ebook-specific operations
├── notes/ # Notes API testing
├── highlights/ # Highlights API testing
├── scanner/ # Background scanning & watch mode
├── progress/ # Reading progress tracking
└── collection.bru # Main dashboard
├── devices/ # Device management
├── conflicts/ # Sync conflict resolution
├── queue/ # Sync queue management
├── sync-koreader/ # KOReader sync protocol
├── sync-kobo/ # Kobo sync protocol
└── collection.bru # Main dashboard file
```
### Authentication Flow
1. **Register**: `POST /api/auth/register` → JWT token
2. **Login**: `POST /api/auth/login` → JWT token
2. **Login**: `POST /api/auth/login` → JWT token
3. **Protected Routes**: Use `Authorization: Bearer {token}` header
4. **Refresh Token**: `POST /api/auth/refresh` → JWT token
5. **Logout**: `POST /api/auth/logout` → Revoke refresh token
### API Reference Documentation
See [API_REFERENCE.md](API_REFERENCE.md) for complete API documentation including:
- All endpoints with request/response examples
- Bruno v3.0 test collections for all endpoints
- Error handling details
- Authentication & security features
### Device Setup Guides
- [KOBOREADER_SETUP.md](KOBOREADER_SETUP.md) - KOReader device configuration
- [KOBO_SETUP.md](KOBO_SETUP.md) - Kobo device configuration
### Universal Sync Documentation
- [UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md) - Complete sync architecture
### Error Handling
All API endpoints return standardized error responses:
docs/API_REFERENCE.md
+1308
View File
File diff suppressed because it is too large Load Diff
docs/devices/KOBO_SETUP.md
+402
View File
@@ -0,0 +1,402 @@
# Kobo Device Setup Guide
This guide will help you set up your Kobo e-reader to sync with Bookmann for seamless cross-device reading progress synchronization.
## What is Kobo Sync?
Bookmann 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
- Maintain device-specific metadata
## Prerequisites
Before you begin, make sure you have:
- ✅ A Kobo e-reader device (Clara, Aura, Nia, Libra, Sage, Elipsa, etc.)
- ✅ A Bookmann instance running and accessible on your network
- ✅ Your Bookmann credentials (username and password)
- ✅ USB cable to connect your Kobo to your computer
- ✅ Your Kobo connected to the same Wi-Fi network as your Bookmann instance
## Supported Kobo Devices
Bookmann 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
- **Kobo Forma**: All versions
- **Kobo Sage**: All versions
- **Kobo Elipsa**: All versions
- **Kobo Nia**: All versions
- **Kobo Touch**: Touch 2.0
- **Kobo Glo**: Glo, Glo HD
## Device Registration
### Step 1: Find Your Kobo Serial Number
1. Turn on your Kobo device
2. Go to **Settings** (gear icon)
3. Select **Device Information**
4. Note your **Device Serial Number** (e.g., N1234567890123)
- This is your device identifier for registration
### Step 2: Register Your Device in Bookmann
1. Log in to your Bookmann web interface
2. Navigate to **Device Management** → **Add New Device**
3. Fill in the device details:
- **Device Name**: A friendly name (e.g., "My Kobo Clara")
- **Device Type**: Select "Kobo"
- **Device Identifier**: Enter your Kobo serial number
4. Click **Register Device**
You'll receive:
- An **Auth URL** to approve the device
- Instructions for manual configuration
### Step 3: Approve Your Device
1. **Method A: QR Code**
- If displayed, scan the QR code with your phone's camera
- This will open the approval page in your browser
- Log in and click **Approve**
2. **Method B: Manual URL**
- Copy the Auth URL from the registration confirmation
- Open it in your web browser
- Log in to your Bookmann account
- Click **Approve Device**
Your device is now registered and ready for configuration!
## Configure Kobo Sync
### Step 1: Connect Kobo to Your Computer
1. Use your USB cable to connect Kobo to your computer
2. Your computer should recognize Kobo as a storage device
3. Kobo will show "Connected" and "Eject before disconnecting"
### 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
### Step 3: Add Bookmann Sync Configuration
Add the following section to the end of your `Kobo eReader.conf` file:
```ini
[FeatureSettings]
# Enable Kobo store replacement
KoboStoreSyncDisabled=true
[Sync]
# Bookmann Sync Configuration
ServerURL=http://YOUR_COMPUTER_IP:8765/api/sync/kobo
AutoSyncEnabled=true
SyncFrequency=5
# Authentication
Username=YOUR_BOOKMANN_USERNAME
Password=YOUR_BOOKMANN_PASSWORD
```
**Replace the following with your actual values**:
- `YOUR_COMPUTER_IP`: Your computer's local IP address (e.g., 192.168.1.100)
- `YOUR_BOOKMANN_USERNAME`: Your Bookmann email or username
- `YOUR_BOOKMANN_PASSWORD`: Your Bookmann password
**Example configuration:**
```ini
[Sync]
ServerURL=http://192.168.1.100:8765/api/sync/kobo
AutoSyncEnabled=true
SyncFrequency=5
Username=john@example.com
Password=securePassword123
```
### Step 4: Save and Eject
1. Save the `Kobo eReader.conf` file
2. Safely eject your Kobo device from your computer
3. Kobo will restart automatically
### Step 5: Verify Sync on Kobo
1. After Kobo restarts, go to **Settings** → **Sync & Backup**
2. You should see "Bookmann" listed as a sync provider
3. Tap **Sync Now** to test the connection
4. If successful, you'll see a "Sync Complete" message
## Sync Features
### Reading Progress Sync
Kobo syncs:
- **Percentage Read**: Overall book completion percentage
- **Page Number**: Current page in fixed-layout books
- **Time Spent**: Reading time statistics
- **Last Read**: Timestamp of last reading session
### Annotations Sync
Kobo syncs:
- **Bookmarks**: Page positions saved for quick access
- **Highlights**: Highlighted text passages
- **Notes**: Notes attached to highlights
- **Reading Statistics**: Pages read, time spent
### Shelf Management
Kobo syncs:
- **Book Collections**: Your organized shelves
- **Shelf Contents**: Books in each collection
- **Sync Metadata**: When shelves were last updated
## Sync Frequency Options
Configure how often Kobo syncs with Bookmann:
```ini
[Sync]
# Sync frequency in minutes
SyncFrequency=5 # Sync every 5 minutes (recommended)
SyncFrequency=15 # Sync every 15 minutes
SyncFrequency=60 # Sync every hour
SyncFrequency=0 # Manual sync only
```
**Recommended**: `SyncFrequency=5` for near real-time sync
**Battery Saving**: `SyncFrequency=15` or `30` to reduce Wi-Fi usage
**Manual Only**: `SyncFrequency=0` sync only when you press "Sync Now"
## Manual Sync
To manually trigger a sync on your Kobo:
1. Connect Kobo to Wi-Fi
2. Go to **Settings** → **Sync & Backup**
3. Tap **Sync Now**
4. Wait for "Sync Complete" message
## Advanced Configuration
### Disable Kobo Store
To prevent Kobo from trying to connect to the official Kobo store:
```ini
[FeatureSettings]
KoboStoreSyncDisabled=true
```
### Custom Sync URL
If you're running Bookmann with a custom domain or port:
```ini
[Sync]
# Custom domain
ServerURL=https://bookmann.example.com/api/sync/kobo
# Custom port
ServerURL=http://192.168.1.100:9000/api/sync/kobo
# Localhost (for testing)
ServerURL=http://localhost:8765/api/sync/kobo
```
### HTTPS Configuration
If you have SSL/TLS configured on Bookmann:
```ini
[Sync]
ServerURL=https://bookmann.yourdomain.com/api/sync/kobo
```
Kobo will automatically trust the certificate if properly configured.
## Troubleshooting
### Sync Not Working
**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
4. Test with manual sync first
5. Check Bookmann logs for connection attempts
### Connection Refused
**Problem**: "Connection refused" or "Server not reachable"
**Solutions**:
1. Verify Bookmann 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
4. Temporarily disable firewall to test
5. Try accessing Bookmann URL in your browser first
### Authentication Failed
**Problem**: "Authentication failed" or "Invalid credentials"
**Solutions**:
1. Verify username and password in config file
2. Check your account is active and not locked
3. Try logging in to Bookmann web interface
4. Ensure password doesn't contain special characters that need escaping
5. Reset password if needed
### Configuration File Not Saving
**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)
4. Backup the file before editing
5. On Mac, ensure you're not editing the package directly
### Sync Only Works Manually
**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
4. Some Kobo models require Wi-Fi to be manually connected
5. Check Bookmann device management page for connection errors
### Books Not Appearing in Kobo
**Problem**: Books added to Bookmann don't show on Kobo
**Solutions**:
1. Kobo needs books to be sideloaded (manually transferred via USB)
2. Bookmann syncs PROGRESS, not book files
3. Transfer book files to Kobo's `Documents` folder via USB
4. Kobo will then sync progress for those books with Bookmann
5. Check that book formats are supported by Kobo
### Conflicts Not Showing
**Problem**: Conflicts between devices aren't being detected
**Solutions**:
1. Check Bookmann Conflicts page
2. Ensure both devices have synced recently
3. Conflicts only detected when progress differs within 5 minutes
4. Manually sync both devices to trigger conflict detection
5. Review conflict resolution settings
## Security Best Practices
1. **Use HTTPS**: If deploying Bookmann publicly, configure SSL/TLS
2. **Strong Password**: Use a secure password for your Bookmann account
3. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3)
4. **Regular Updates**: Keep Kobo firmware updated
5. **Device Authorization**: Only approve devices you recognize
## Network Configuration
### Local Network (Recommended)
For home use, keep Kobo and Bookmann on the same local network:
```
Kobo Wi-Fi: 192.168.1.x
Bookmann: 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 Bookmann
3. Use a dynamic DNS service for constant hostname
4. Update Kobo config with public URL:
```ini
[Sync]
ServerURL=https://yourdomain.com/api/sync/kobo
```
## Performance Optimization
### 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
4. Keep Kobo in sleep mode when not reading
### Sync Speed
To improve sync speed:
1. Ensure strong Wi-Fi signal
2. Use local network (not remote access)
3. Keep Bookmann and Kobo on same network
4. Close other apps using Wi-Fi bandwidth
5. Reduce number of books syncing at once
## Additional Resources
- [Kobo Developer Documentation](https://help.kobo.com/hc/en-us)
- [Bookmann Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md)
- [KOReader Setup Guide](KOBOREADER_SETUP.md)
- [Bookmann API Reference](API_REFERENCE.md)
## FAQ
**Q: Can I sync books (files) between devices?**
A: No, Bookmann only syncs reading progress and annotations. You must sideload book files to each device manually.
**Q: Will Kobo update automatically when I add books in Bookmann?**
A: No, Kobo doesn't fetch book files from Bookmann. You must transfer books via USB.
**Q: Can I use both Kobo Sync and Calibre?**
A: Yes, but they may conflict. It's recommended to choose one sync method.
**Q: What happens if I read the same book on Kobo and KOReader?**
A: Bookmann will detect conflicts and you can resolve them in the Conflicts UI.
**Q: Does Kobo sync when in sleep mode?**
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 Bookmann sync queue and device management pages
4. Verify your configuration file is saved correctly
5. Open an issue on the Bookmann GitHub repository
---
**Last Updated**: 2026-01-31
**Bookmann Version**: 1.0
**Kobo Firmware**: 4.30.0+