[GUI Plugin] Kobo Utilities

[Majutsushi]

The Kobo Utilities Plugin adds extra function to calibre for working with Kobo ereaders. This will allow changes on the eReaders that either cannot otherwise be made or will make them easier to do.

The plugin was originally created by @davidfor and is now mainly maintained by me. All future questions should be posted here, but the older thread is here for reference.

The current functions of the plugin are:

• Set/Remove font settings for specific books.
• Update metadata directly to the database on the device.
• Change the reading status.
• Manage series info for books on the device. This is mainly for books not in the calibre library including kepubs.
• Store/record current reading position for ePubs. This can be done manually or automatically when the Kobo ereader is connected. Profiles can be used to manage the reading positions of multiple devices.
• Upload/Remove covers for all books in the library. This includes kepubs.
• A couple of annotations options that I'm not happy with.
• Backup the device database.
• Run integrity check on the database. It doesn't fix anything, but it tells you if the database is OK or not.
• Clean up duplicate shelves.
• Remove annotations files.
• Update the ToC for selected books.
• Clean the images directory of extra cover images.
• Various database-related utility functions.

Warning

• Almost all the functions of this plugin directly update the database on the Kobo device. If anything goes wrong, the database could get corrupted. It shouldn't happen, but it could. Before using any function of the plugin, it is recommended that you backup the database.
• The plugin has been created by reverse engineering the function of the Kobo eReaders. This has been done by examining the database on the Touch and Glo and experimenting with it and the interface. There is a good chance that my conclusions from this are wrong. This is unlikely to damage the device, but it could result in the need to reset it.

Supported Devices

All Kobo e-ink ereaders are supported if calibre supports them. Some functions are not supported on the original Kobo eReader or the WiFi.

Supported calibre Versions

The oldest supported version of Calibre is 5.13.0. There are a few tests that run against both the oldest supported version and the current version, but they can't catch all issues. If something doesn't work in the supported versions please post about it in this thread.

Installation

Open Preferences -> Plugins -> Get new plugins and install the 'Kobo Utilities' plugin.

You may also download the attached zip file and install the plugin manually, then restart calibre as described in the Introduction to Plugins thread.

Configuration

Before use, some configuration of the plugin is needed. Pressing the toolbar button will display the configuration options, or it can be reached from the menu. Several custom columns are needed for the full function of the plugin. Pressing the help link will display the help for the plugin. This includes a full description of the columns needed.

Usage

• Once installed, the usage for most functions is to select one or more books in the library or device list and select an option from the plugins menu. A dialog will be displayed to set options for the action. Pressing OK will run the actions and when finished display a message showing the results.
• The functions available depend on whether you are looking at the library or the device list.
• A full description of each function is available in the help. This can be seen by pressing the help link in the top right of corner of each dialog.

Source

The source of the plugin can be found on GitHub: https://github.com/majutsushi/kobo-utilities

Acknowledgements

• A large chunk of the code is borrowed from the plugins written by kiwidude. Without his work, this would have been a lot harder to do.
• A few people have tried the beta versions of the plugin. Their reports, suggestions and encouragement have been important in getting it working.

Changelog

The changelog can be found here: https://github.com/majutsushi/kobo-u...n/CHANGELOG.md

[Majutsushi]

Time Spent Reading / Rest of Book Estimate formatting

If you want to show the "Time Spent Reading" and "Rest of Book Estimate" values in anything other than seconds, you will have to create two new columns that are based on the "seconds" columns and format the value differently.

Here is how you can do this:

• Open the Calibre preferences.
• Click on "Add your own columns".
• Click on "Add custom column" or the green "+" sign on the right.
• Enter a lookup name, like "#my_time_spent_reading".
• Enter a column heading, like "Time Spent Reading".
• For column type, choose "Column built from other columns".
• Right-click in the "Template" entry field and click "Open template editor".
• Enter the code to format the seconds to something else.
  
  Here is an example:
  

  program:
  
  total = $#kobo_time_spent_reading;
  hours = floor(total/3600);
  minutes = round((total-hours*3600)/60);
  
  def format(v, str):
      if v == 0 then return '' fi;
      return v & ' ' & str & ' '
  fed;
  format(hours, 'hr') & format(minutes, 'min')

  This will format the time as something like "3 hr 27 min".
  
  Make sure to replace "#kobo_time_spent_reading" with the actual lookup name of the seconds column you want to reference.
• Press "OK"/"Apply" to close all the dialogs and restart Calibre.

For more information about writing such a template check out https://manual.calibre-ebook.com/template_lang.html.

[Lys]

I was checking the list of functionalities listed for the plugin vs the ones I can see/use in the current version, since I know some of them were developed and then discarded after major Kobo firmware updates, and I think it would be best to clean the features list with the ones currently available

Dismiss tiles from tiled home screen.

Is this one still here? I can't find it in the dropdown menu, and if I remember correctly, this one is one of the functionality that davidfor dropped

Manage series info for books on the device. This is mainly for books not in the calibre library including kepubs.

I can still see a "Order Series Shelves" but I'm unsure what it's supposed to do. If I run it, it gives me back a list of my Collections (or Shelves as they were called back then), but no information related to Series. Maybe it was developed back when Kobo didn't have a separated Series tab?

List the books missing from the device database. This only lists the books that calibre thinks should be in the database.

I can only see the "Refresh the list of the books on the device" which seems to trigger a reconnection between Calibre and the device, but nothing related to "missing books"

Set "Related books" for sideloaded books.

I can't find anything for this part either


Features I can see/use on current version that aren't listed, instead:

• Update TOC for selected books
• Clean images directory for extra cover images
• Some additional database functionalities (compress DB, fix duplicated shelves)
• Easy access to currently in use Kobo-Calibre driver (and easy switch between KoboTouch driver and KTE)

[ownedbycats]

Originally Posted by Lys

Is this one still here? I can't find it in the dropdown menu, and if I remember correctly, this one is one of the functionality that davidfor dropped

I dont even think it works anymore, does it? Kobo doesnt have the right sort of tiles for it anymore firmware changes.

[Lys]

Originally Posted by ownedbycats

I dont even think it works anymore, does it? Kobo doesnt have the right sort of tiles for it anymore firmware changes.

Yeah, that's what I remember as well, but I'm not technical enough to know the details, tbh.

[JSWolf]

Originally Posted by Majutsushi

Time Spent Reading / Rest of Book Estimate formatting

If you want to show the "Time Spent Reading" and "Rest of Book Estimate" values in anything other than seconds, you will have to create two new columns that are based on the "seconds" columns and format the value differently.

Here is how you can do this:

• Open the Calibre preferences.
• Click on "Add your own columns".
• Click on "Add custom column" or the green "+" sign on the right.
• Enter a lookup name, like "#my_time_spent_reading".
• Enter a column heading, like "Time Spent Reading".
• For column type, choose "Column built from other columns".
• Right-click in the "Template" entry field and click "Open template editor".
• Enter the code to format the seconds to something else.
  
  Here is an example:
  

  program:
  
  total = $#kobo_time_spent_reading;
  hours = floor(total/3600);
  minutes = round((total-hours*3600)/60);
  
  def format(v, str):
      if v == 0 then return '' fi;
      return v & ' ' & str & ' '
  fed;
  format(hours, 'hr') & format(minutes, 'min')

  This will format the time as something like "3 hr 27 min".
  
  Make sure to replace "#kobo_time_spent_reading" with the actual lookup name of the seconds column you want to reference.
• Press "OK"/"Apply" to close all the dialogs and restart Calibre.

For more information about writing such a template check out https://manual.calibre-ebook.com/template_lang.html.

Can this ability to show hours and minutes be added in to Kobo Utilities?

[JSWolf]

Originally Posted by Lys

I can still see a "Order Series Shelves"

This should be changes as it's not shelves but collections.

[JSWolf]

Originally Posted by ownedbycats

I dont even think it works anymore, does it? Kobo doesnt have the right sort of tiles for it anymore firmware changes.

It worked for the version 3.x firmware. Version 4.x did away with the tiles. I do think that could be removed to streamline the code some.

[Majutsushi]

Thanks for the investigation, I didn't think to do that before posting. I'll update the list with your findings.

Originally Posted by Lys

Is this one still here? I can't find it in the dropdown menu, and if I remember correctly, this one is one of the functionality that davidfor dropped

I checked the code and it's only enabled for firmware versions before 4.4.0. I assume no one still uses a firmware that old so this can probably be removed.

Originally Posted by Lys

I can still see a "Order Series Shelves" but I'm unsure what it's supposed to do. If I run it, it gives me back a list of my Collections (or Shelves as they were called back then), but no information related to Series. Maybe it was developed back when Kobo didn't have a separated Series tab?

I'm not sure about this, I never used this functionality. Maybe someone knows more about this, otherwise I'll have a look at it when I have some time.

Originally Posted by Lys

I can only see the "Refresh the list of the books on the device" which seems to trigger a reconnection between Calibre and the device, but nothing related to "missing books"

I can't find anything about "missing" books in the code, so I'll just remove this item for now.

Originally Posted by Lys

I can't find anything for this part either

I actually came across this while preparing the release and noticed it's also only available for firmware versions before 4.4.0. So this can presumably also just be removed.

[Majutsushi]

Originally Posted by JSWolf

Can this ability to show hours and minutes be added in to Kobo Utilities?

That would be nice but unfortunately it's not that simple. The "raw" seconds need to be preserved in a column so that they can be restored to the device if desired, so transforming them on a normal sync wouldn't work.

What could be possible is to have some configuration for each of the two values that creates a secondary column with a configurable format, and which then creates a template similar to the one I posted automatically for the secondary columns. That would be a non-trivial change though so I'm not sure when I might get around to that. I would be happy to accept contributions though.

[compurandom]

Originally Posted by Majutsushi

I actually came across this while preparing the release and noticed it's also only available for firmware versions before 4.4.0. So this can presumably also just be removed.

I used this once, but admittedly i don't remember what version of the firmware I had at the time.

But the related books stuff is still in the current firmware, so I'm not sure why it would be disabled?

I just checked a couple of books, I only have a related books tab on a book from the kobo store, maybe because it's not filled in for other books.

I wonder if this was just never enabled for newer firmwares because it hadn't been tested? or the database structure changed and Davidfor didn't get a chance to fix it?

[icallaci]

Will the function "Compress the device database" eventually be implemented? I get the following error when I run it: "SQLError:SQLError: cannot VACUUM from within a transaction." After the error, I cannot eject the device. It appears to eject because the "On Device" column in Calibre disappears, but the reader never returns to the home screen. I must manually eject it from within File Explorer (I'm running Windows 11).

[DNSB]

Originally Posted by icallaci

Will the function "Compress the device database" eventually be implemented? I get the following error when I run it: "SQLError:SQLError: cannot VACUUM from within a transaction." After the error, I cannot eject the device. It appears to eject because the "On Device" column in Calibre disappears, but the reader never returns to the home screen. I must manually eject it from within File Explorer (I'm running Windows 11).

It did work at one point in time since I used it. Ghod alone knows when it stopped working. As for the eject after trying it? It took a couple of minutes after I clicked on Smart Eject before the Kobo went back to the home screen.

[icallaci]

I tried rebooting the device and the computer but I still get the error whenever I try to compress the database. After ejecting the reader from within Calibre, I waited for about a minute before closing Calibre and that's when the reader finally went back to the home screen. I'll try again tomorrow when my brain is functioning better. Thanks.

[compurandom]

Originally Posted by DNSB

It did work at one point in time since I used it. Ghod alone knows when it stopped working. As for the eject after trying it? It took a couple of minutes after I clicked on Smart Eject before the Kobo went back to the home screen.

Just tried dtatabase compress, worked fine for me.

Kobo Utilities v2.17.1
Calibre 7.16

That's at least a starting point...