Kobodeck

A minimalist Readeck article downloader for Kobo e-readers. It can

• fetch content from a Readeck instance
• sync some properties (read/archived/favorite) from the Kobo device to Readeck

flowchart LR
    K[Kobo Device]
    R[Readeck Instance]

    R -->|unread articles| K
    K -->|archive completed articles| R
    K -->|mark favourites| R

Loading

The project is forked from wallabako.

who is this for ?

This plugin could be useful for you if you

• do not want to use KOReader, which has a native Readeck/OPDS plugin or Plato, which includes an article fetcher
• are ok with mixing ebooks and articles in the native Kobo UI - if you want to keep them separate, check out kobeck
• are fine with a lack of ui - syncing happens in the background

how to use it

When wifi is turned on, kobodeck connects to your Readeck instance in the background, downloads new unread articles as KEPUBs with cover images, and syncs read status back to Readeck.

If any files changed, it triggers a Nickel library rescan via a simulated USB event. Press Connect to rescan immediately, or Cancel - the files are already downloaded either way.

prerequisites

• a running hosted or self-hosted Readeck instance
• a Readeck API token (generate one in Readeck under Settings → API tokens)
• a Kobo device from the Glo generation or newer running the stock Nickel firmware (tested on Kobo Libra Color; very old models may not work)

installation or upgrade

To install or upgrade

1. obtain the latest KoboRoot.tgz:
   • download it from the releases page, or
   • build from source via make tarball
2. save the file in the .kobo directory of your e-reader
3. copy and edit the configuration file kobodeck.toml
4. store it as .adds/kobodeck/kobodeck.toml on your Kobo device
5. optionally verify your configuration with kobodeck --config .adds/kobodeck/kobodeck.toml --check via the binary provided in the tarball
6. safely disconnect the reader - it should restart, install kobodeck and remove KoboRoot.tgz

Logs are written to .adds/kobodeck/kobodeck.log on the device.

uninstalling

Empty the file .adds/kobodeck/kobodeck.toml (delete its contents, but keep the file) and connect to wifi. Kobodeck will detect the empty config, remove its installed files, and exit. If uninstall succeeded, .adds/kobodeck/ will no longer exist.

manual uninstall

Manual removal requires root access to the device. The following need to be deleted:

/etc/udev/rules.d/90-kobodeck.rules
/usr/local/bin/kobodeck
/mnt/onboard/.adds/kobodeck/
/mnt/onboard/kobodeck/

The last path is the default output directory (Output.Path in the config) - adjust if you changed it.

development

Check the Makefile for common operations on the project.

manual testing before release

• add a new article to Readeck
• build KoboRoot.tgz
  • no errors
• install on device, connect wifi
  • article downloaded
• mark article as read, add to favorite collection, reconnect
  • article archived in Readeck
  • article favourited
• reconnect again
• check the logs
  • first connect: article downloaded, no errors
  • second connect: article archived, article favourited, no errors
  • third connect: no downloads, no syncs

updating the Nickel schema

The integration tests use schema files in testdata/ named nickel-schema-{version}.sql, where {version} is the DbVersion from the KoboReader.sqlite database. After a firmware update that changes the database schema, dump the new schema with:

DB=/media/$USER/KOBOeReader/.kobo/KoboReader.sqlite
VER=$(sqlite3 "$DB" "SELECT version FROM DbVersion;")
sqlite3 "$DB" ".schema" > testdata/nickel-schema-${VER}.sql

known issues

• Already downloaded articles are never re-downloaded, even if the local file is corrupted or unreadable. To force a re-download, delete the file from .adds/kobodeck/ manually.
• Articles in a favourite collection are re-marked as favourite on every sync, even if already marked in Readeck (redundant API calls).
• Removing an article from the favourite collection on device does not un-favourite it in Readeck — favouriting is one-way (kobodeck never sends is_marked: false).
• Un-archiving an article in Readeck does not restore it to the device, because the local file already exists and re-downloads are never triggered.

future work

• Sync highlights and annotations from the Kobo (Bookmark table in KoboReader.sqlite) to Readeck's annotations API
• Add sync of reading progress (current position) from the Kobo to Readeck - note that progress may differ between EPUB and KEPUB formats
• Add functionality to also fetch archived articles
• Add functionality to fetch favourites only
• Syncing is currently only one way, as we avoid writing to Kobo's NickelDB - reverse sync may still be worth exploring
• Kobodeck does not inhibit device sleep - if the Kobo sleeps during a long sync, downloads may be interrupted