Kobo Integration & Sync

CWA's Integrations with Kobo

Calibre-Web Automated (CWA) provides comprehensive integration with Kobo e-readers, allowing you to sync your library, reading progress, and manage your collection directly from your device. This guide covers both user setup and developer implementation details.

🚀 Quick Start

Prerequisites

• Kobo e-reader (Clara HD, Libra 2, Sage, etc.)
• Calibre-Web Automated instance accessible from your network
• Administrator access to enable Kobo sync
• Books in EPUB or KEPUB format

Admin Configuration

1. Enable Kobo Sync

   • Navigate to Admin → Basic Configuration → Feature Configuration
   • Check "Enable Kobo sync"
   • Optionally enable "Proxy unknown requests to Kobo Store" for additional functionality
   • Save settings

2. User Permissions

   • Users need "Download" permission to sync with Kobo devices
   • Optionally grant "Sync only books in selected shelves with Kobo" for advanced users

📱 User Setup

Step 1: Generate Kobo Authentication Token

1. Go to your User Settings or have an admin navigate to Admin → Edit Users → [Your User]
2. Click "Generate Kobo Auth URL"
3. Copy the displayed api_endpoint URL

⚠️ Important: Access CWA from a non-localhost address to get a valid endpoint for your Kobo device.

Step 2: Configure Your Kobo Device

Method 1: Direct File Edit (Recommended)

1. Connect your Kobo to a computer via USB
2. Navigate to .kobo/Kobo/ folder on your device
3. Open Kobo eReader.conf in a text editor
4. Add the following line under the [Service] section:

   api_endpoint=https://your-server.com/your-auth-token/v1/library/sync
   

5. Save and safely eject your Kobo

Method 2: Via Kobo Web Browser (Alternative)

1. Open the web browser on your Kobo
2. Navigate to your CWA instance
3. Log in and generate the auth URL as above
4. The configuration should be applied automatically

Step 3: Initial Sync

1. Restart your Kobo device
2. Connect to WiFi
3. The initial sync will begin automatically
4. Check your library - CWA books should appear

📚 Understanding Sync Modes

Full Library Sync (Default)

• Behavior: All books in your CWA library are synced to your Kobo
• Use Case: Best for users who want their entire library available
• Archive Behavior: Books deleted from Kobo are moved to "Archived Books" in CWA

Shelf-Only Sync (Advanced)

• Behavior: Only books in designated "Kobo Sync" shelves are synced
• Use Case: Curated syncing for users who want selective content
• Setup: Enable "Sync only books in selected shelves with Kobo" in user settings
• Archive Behavior: Books deleted from Kobo are simply unsynced (not archived)

Setting Up Shelf-Only Sync

1. Enable Feature

   • Go to User Settings → Check "Sync only books in selected shelves with Kobo"
   • Save settings

2. Create Sync Shelves

   • Navigate to Your Shelves → Create Shelf
   • Name your shelf (e.g., "Kobo - To Read")
   • Check "Sync this shelf with Kobo device"
   • Save shelf

3. Add Books to Sync Shelves

   • Add books to your sync-enabled shelves
   • Only these books will appear on your Kobo after the next sync

🔄 Two-Way Sync Features (New in CWA)

Calibre-Web → Kobo Deletion Sync

When using shelf-only sync:

• Remove a book from a sync shelf in CWA
• The book is automatically deleted from your Kobo on the next sync
• Creates seamless library management from the web interface

Kobo → Calibre-Web Deletion Sync

The behavior depends on your sync mode:

Full Library Sync:

• Delete book from Kobo → Book is archived in CWA
• Book remains in library but marked as archived

Shelf-Only Sync:

• Delete book from Kobo → Book is removed from sync status
• Book remains in library and shelves, simply unsynced

📖 Reading Progress Sync

Automatic Sync

• Reading position, bookmarks, and statistics sync automatically
• Progress updates when you:
  • Turn pages
  • Close a book
  • Switch between books
  • Connect to WiFi

Manual Sync

• Go to Settings → Sync and Share → Sync Now on your Kobo
• Or simply connect to WiFi if auto-sync is enabled

🔧 Advanced Features

Format Conversion

• CWA automatically converts EPUB to KEPUB format when possible
• KEPUB provides better integration with Kobo features
• Requires kepubify tool to be configured in CWA

Cover Sync

• Book covers are automatically downloaded and displayed
• Multiple resolution support for different Kobo models
• Fallback to Kobo store covers if local covers unavailable

Metadata Sync

• Title, author, series, and description sync automatically
• Tags and series information maintained
• Publication dates and ratings supported

🚨 Troubleshooting

Common Issues

Books not appearing on Kobo:

• Verify user has download permissions
• Check that books are in EPUB/KEPUB format
• Ensure WiFi connection for sync
• Try manual sync from Kobo settings

Sync shelf not working:

• Confirm "Sync only books in selected shelves" is enabled
• Verify shelf has "Sync this shelf with Kobo device" checked
• Check that books are actually in the sync shelf

Authentication errors:

• Regenerate auth token if expired
• Ensure CWA is accessible from non-localhost
• Verify correct api_endpoint in Kobo config

Reading progress not syncing:

• Check WiFi connectivity
• Verify user permissions
• Try manual sync from device

Reset Sync Status

If you need to reset your sync status:

1. Admin can force full sync in user settings
2. Or delete auth token and regenerate

🛠️ Developer Information

API Endpoints

The Kobo integration implements these key endpoints:

• /kobo/<auth_token>/v1/library/sync - Main sync endpoint
• /kobo/<auth_token>/v1/library/<uuid>/metadata - Book metadata
• /kobo/<auth_token>/v1/library/<uuid>/state - Reading state
• /kobo/<auth_token>/v1/library/<uuid> (DELETE) - Book deletion

Database Schema

Core Tables

• kobo_synced_books - Tracks which books are synced per user
• kobo_reading_state - Reading progress and timestamps
• kobo_bookmark - Current reading position
• kobo_statistics - Reading time and progress stats
• archived_book - Archived book status
• remote_auth_token - Authentication tokens

Key Fields

-- User configuration
users.kobo_only_shelves_sync  -- Enable shelf-only sync mode

-- Shelf configuration  
shelf.kobo_sync  -- Mark shelf for Kobo sync

-- Sync tracking
kobo_synced_books.user_id, book_id  -- Active sync relationships

Two-Way Sync Implementation

Deletion Sync Logic (HandleSyncRequest)

# For shelf-sync users only
if current_user.kobo_only_shelves_sync:
    # Find books on device but not in sync shelves
    synced_book_ids = {books currently on Kobo}
    allowed_book_ids = {books in sync shelves}
    books_to_delete = synced_book_ids - allowed_book_ids
    
    # Send deletion commands to Kobo
    for book_id in books_to_delete:
        send_archive_command(book_id)

Device Deletion Handling (HandleBookDeletionRequest)

if current_user.kobo_only_shelves_sync:
    # Shelf-sync users: just remove sync status
    pass
elif current_user.check_visibility(32768):
    # Full-sync users: archive the book
    kobo_sync_status.change_archived_books(book_id, True)

# Always remove from sync tracking
kobo_sync_status.remove_synced_book(book_id)

Configuration Options

System-wide Settings

• config.config_kobo_sync - Enable/disable Kobo integration
• config.config_kobo_proxy - Proxy unknown requests to Kobo store
• config.config_kepubifypath - Path to kepubify conversion tool

User Settings

• user.kobo_only_shelves_sync - Enable shelf-only sync mode
• User permissions for download and archive access

Security Model

Authentication

• Unique tokens per user via RemoteAuthToken table
• Tokens embedded in API URLs for stateless authentication
• No password storage on device

Authorization

• User permissions checked on each request
• Download permission required for sync access
• Archive permission required for deletion handling

🔗 Related Resources

• Original Calibre-Web Kobo Integration
• External Setup Guide
• Kobo Developer Documentation

🤝 Contributing

The Kobo integration is actively developed. Key areas for contribution:

• Enhanced format support
• Improved sync performance
• Additional device compatibility
• Better error handling and user feedback

See the main project repository for contribution guidelines.

---

This documentation covers Calibre-Web Automated's enhanced Kobo integration. Features may differ from the original Calibre-Web project.