bookhoard/docs/user/devices/kobo-setup.md

Kobo Device Setup Guide

This guide will help you set up your Kobo e-reader to sync with Bookhoard for seamless cross-device reading progress synchronization.

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
• 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 Bookhoard instance running and accessible on your network
• ✅ Your Bookhoard credentials (username and password)
• ✅ USB cable to connect your Kobo to your computer
• ✅ Your Kobo connected to the same Wi-Fi network as your Bookhoard instance

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
• 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 Bookhoard

1. Log in to your Bookhoard 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 Bookhoard 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 Bookhoard Sync Configuration

After device registration is complete, you'll receive an API key and sync URL from Bookhoard.

Add the following section to the end of your Kobo eReader.conf file:

[FeatureSettings]
# Enable Kobo store replacement
KoboStoreSyncDisabled=true

[Sync]
# Bookhoard Sync Configuration (from Device Management page)
ServerURL=http://YOUR_COMPUTER_IP:8765/api/sync/kobo/YOUR_API_KEY
AutoSyncEnabled=true
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:

[Sync]
ServerURL=http://192.168.1.100:8765/api/sync/kobo/dev_abc123def456
AutoSyncEnabled=true
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:

[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 "Bookhoard" 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

OPDS Wireless Book Delivery

What is OPDS?

OPDS (Open Publication Distribution System) allows your Kobo to wirelessly download books from Bookhoard - no USB cable needed!

OPDS Benefits

• No USB Required: Download books directly to your Kobo over Wi-Fi
• On-Demand Delivery: Browse your Bookhoard 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:

[FeatureSettings]
# Enable OPDS catalog
OPDSCatalogEnabled=true
OPDSCatalogURL=http://YOUR_COMPUTER_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog?token=YOUR_API_KEY

# Example:
# OPDSCatalogURL=http://192.168.1.100:8765/opds/devices/kobo-clara-123/catalog?token=dev_abc123def456

4. Replace:

   • YOUR_COMPUTER_IP: Your Bookhoard server IP
   • YOUR_DEVICE_ID: Your Kobo's device ID from Bookhoard Device Management
   • YOUR_API_KEY: Your Kobo device's API key (same as in sync URL)

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 Bookhoard listed as a store
4. Tap to enter the Bookhoard catalog

Browse and Download Books

Browse All Books

1. In the Bookhoard 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 Bookhoard 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: Bookhoard 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 Bookhoard automatically
4. Continue reading on any other device!

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

OPDS Troubleshooting

Catalog Not Appearing

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
4. Ensure device ID matches Bookhoard 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 Bookhoard server is running
3. Verify book file exists in Bookhoard library
4. Try downloading a smaller book first
5. Check Bookhoard 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 Bookhoard
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 Bookhoard catalog on your Kobo:

[OPDS]
CatalogName=My Library

Auto-Download

Automatically download new books added to collections:

[OPDS]
AutoDownloadEnabled=true
AutoDownloadCollections=To Read,Recent

Download Quality

Choose between original EPUB or converted KEPUB:

[OPDS]
PreferredFormat=kepub  # Options: epub, kepub, auto

Sync Frequency Options

Configure how often Kobo syncs with Bookhoard:

[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:

[FeatureSettings]
KoboStoreSyncDisabled=true

Custom Sync URL

If you're running Bookhoard with a custom domain or port:

[Sync]
# Custom domain
ServerURL=https://bookhoard.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 Bookhoard:

[Sync]
ServerURL=https://bookhoard.yourdomain.com/api/sync/kobo/YOUR_API_KEY

Replace YOUR_API_KEY with your device's API key from Bookhoard Device Management.

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 Bookhoard logs for connection attempts

Connection Refused

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
4. Temporarily disable firewall to test
5. Try accessing Bookhoard URL in your browser first

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
4. Ensure the sync URL is complete (includes the API key)
5. Copy the sync URL directly from Device Management → "Copy Sync URL" button

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 Bookhoard device management page for connection errors

Books Not Appearing in Kobo

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
4. Kobo will then sync progress for those books with Bookhoard
5. Check that book formats are supported by Kobo

Conflicts Not Showing

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
4. Manually sync both devices to trigger conflict detection
5. Review conflict resolution settings

Security Best Practices

1. Use HTTPS: If deploying Bookhoard publicly, configure SSL/TLS
2. Strong Password: Use a secure password for your Bookhoard 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 Bookhoard on the same local network:

Kobo Wi-Fi: 192.168.1.x
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
4. Update Kobo config with public URL including API key:

   [Sync]
   ServerURL=https://yourdomain.com/api/sync/kobo/YOUR_API_KEY
   

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 Bookhoard 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
• Bookhoard Universal Sync Guide
• KOReader Setup Guide
• Bookhoard API Reference

FAQ

Q: Can I sync books (files) between devices?
A: No, Bookhoard 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 Bookhoard?
A: No, Kobo doesn't fetch book files from Bookhoard. 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: Bookhoard 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 Bookhoard sync queue and device management pages
4. Verify your configuration file is saved correctly
5. Open an issue on the Bookhoard GitHub repository

---

Last Updated: 2026-01-31
Bookhoard Version: 1.0
Kobo Firmware: 4.30.0+