Skip to content

Kobo Integration

Jump to bottom Edit New page
Bat-Shark edited this page May 17, 2022 · 27 revisions

WARNING

This feature is fairly new in Calibre-Web and has had limited testing: You will likely run into new issues if you try this out. I'd recommend waiting a little bit for this cautionary message do disappear if you aren't comfortable with some rough edges.

Known issues:

  • #1219 : Fixed Layout ePubs aren't imported correctly over the Sync protocol.
  • #1276 : Syncing of large libraries may timeout and fail.

Setup

As a prerequiste you need to install the dependencies listed in optional-requirements.txt under the Kobo integration section.

A simple way to do this is to move them to a kobo-requirements.txt file, then run the following for a pip install

./venv/bin/python3 -m pip install -r kobo-requirements.txt

Kobo integration must first be enabled in Calibre-Web by toggling ON the Enable Kobo sync checkbox in the Basic configuration >> Feature Configuration page. If you are accessing your Calibre-Web instance from your Kobo via some sort of portforwarding mechanism (e.g. your router maps port X to machine Y on port Z), please change the External Port setting to port X in this example (the external port). This necessary due to a bug in HTTP-requests the Kobo reader creates and can't be avoided.

The Kobo eReader.conf file found under the .kobo/Kobo directory on Kobo devices is used to configure which URL the device uses for syncing books. By default, the config file contains the following row:

api_endpoint=https://storeapi.kobo.com

Users can generate a URL to sync with Calibre-Web instead by clicking the Create/View button under their Calibre-Web profile page.

Note: there is a checkbox for setting the sync to only use a specific shelf, it is unclear how this works.

Store purchases

If you want to maintain access to the official Kobo store on the device, you can set the Proxy unknown requests to Kobo Store checkbox. When syncing, we will try to sync against both the official Kobo Store as well as Calibre-Web's library.

Privacy & Security caution

The Kobo device sends out a unique and irrevocable (even across password reset) {device_id; user_id} pair during the Sync protocol. If CalibreWeb is exposed over the internet without SSL, then this id pair could theoretically be stolen (if anyone was bothered to...). As far as I can tell, a malicious individual wouldn't be able to make account changes or purchases, but would be able to download the list of purchased or borrowed books, collections, reading stats, etc.

Optional: Installing a self signed certificate on Kobo

You can install a self-signed certificate on the device by copying a DER encoded certificate with a .cer file extension to the .kobo/certificates directory on the Kobo device. For example, to convert an existing certificate to the right format:

openssl x509 -in self-signed-cert.crt -outform DER -out /media/KOBOeReader/.kobo/certificates/calibre_web.cer

Feature support:

Book management

Adding books to Calibre/Calibre-Web will cause them to appear on the device the next time it Syncs with Calibre-Web.

Deleting a book from Calibre/Calibre-Web will not cause it to be removed from the device on the next Sync. In order to trigger deletions from their devices, users must archive books and then sync their devices.

Reading state and statistics

Book progress and reading statistics are synced with and stored in Calibre-Web. At the moment, Calibre-Web will only display whether books have been completed (Read) or not (Unread).

Troubleshooting

If you're having trouble with Kobo sync, there are a few things you can do to help identify the problem:

  1. enable debug logs on the Kobo itself
  • search for devmodeon on the kobo
  • go to settings -> device information -> on page 2, developer options
  • here you can enable logs for specifig settings
  1. enable debug logs in calibre
  • go to the calibre web admin panel
  • go to basic configuration
  • expand Logfile configuration
  • adjust the log level (and location)
  • optionally (though very useful) enable the access log
  1. monitor logs from the Kobo during a sync
  • figure out the IP of your Kobo (you can do this from settings -> device information)
  • run netcat to view the logs on your local machine: nc $KOBO_IP 5001
  1. if you're using a reverse proxy (such as nginx), enable access/error logs
  • see nginx documentation for steps on how to do this for your setup
  • see reverse proxy setup instructions here
Add a custom footer
Add a custom sidebar
Clone this wiki locally