# Kobo Utilities Plugin

The Kobo Utilities Plugin adds extra function to calibre for working with Kobo e-ink eReaders. This will allow changes on the ereaders that either cannot be done or will make them easier to do. The current functions of the plugin are:

- Set/Remove font settings for specific books.
- Update metadata directly to the database on the device. This includes: Title, Author, Series, Comments/Synopsis, Publisher and Date, ISBN, Language and Rating.
- 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.
- Update the ToC for books on the device
- Upload/Remove covers for all books in the library. This includes KePubs.
- Dismiss selected tiles from the new home screen and block them from returning.
- Display extras tiles to put the tiles for the extra on the home screen
- A couple of annotations options that I'm not happy with.
- List the books missing from the device database. This only lists the books that calibre thinks should be in the database.
- Set related books for sideloaded books.
- Remove annotations files from the device.
- Backup the device database.
- Some functions can be run automatically when the device is connected.
- Run integrity check on the database. It doesn't fix anything, but it tells you if the database is OK or not.
- Different function depending on whether you are looking at the library or the device list.

The plugin supports the WiFi, Touch, Glo, Mini, Aura HD, Aura and Aura H20. When a WiFi is being used, the options are limited options it supports. The plugin will probably work with the original Kobo eReader, but this has not been tested.

Known problems:

- There are currently no known problems.

## Warning

Almost all function 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. Again, if you cannot accept this, please do not try this plugin.

## Acknowledgements

A large chunk of the code is borrowed from the plugins written by kiwidude. A lot of the rest came from looking at other plugins and the general calibre code.

A lot of people on MobileRead have helped. Some by beta testing new versions, some with ideas for new functions and some by answering questions from other users.

And of course a big thank you to Kovid Goyal for calibre.

## Installation and Configuration

The plugin is installed through the calibre preferences dialog. During the installation, you will be prompted on which toolbar or menu to put the plugin button. As there is no available function when no devices are connected, put it on the "Main toolbar when a device is connected" or "The menubar when a device is connected". After the plugin is installed, restart calibre before attempting to use it.

To use the plugin, it needs to be configured. This can be done through the calibre preferences, or from the "Customise plugin" option on the plugins menu. There are two areas that need to be configured: the columns to be used by the plugin and the action to be taken when the plugin button is pressed.

### Configuration Dialog

The configuration dialog has three tabs:

- Profiles

The "Profiles" tab is used to create one or more profiles for different Kobo devices. Each profile has a set of custom columns used for storing the reading positions of books. If you have different devices use by different people, this allows them to store their reading status for each book in the same calibre library. The custom columns needed are described in "Columns for the Plugin".

- Devices

The "Device" tab has the list of know Kobo devices and the configuration needed for them. The options are for backing up the database and checking for firmware updates. These can be configured separately for each device or a common configuration used.

The known devices will be available to create a profile for on the "Profiles" tab.

- Other

The "Other" tab has options that are common for the plugin for all devices and libraries. This includes setting the function of the toolbar button, keyboard shortcuts and viewing the preferences as stored.

### Columns for the Plugin

The plugin can use several columns to store the current reading position of ePubs on the eReader. If you do not want to use this part of the plugin, they do not need to be configured.

The columns and types needed are:

- Current Reading Location: This is used to store the link to the current location in the book. It must be a "Text, column shown in the tag browser". It is recommended that the column is not shown in the column list and hidden in the tag browser. Alternately, it can be a "Long text, like comments, not shown in the tag browser." If this is chosen, it is recommended to set the 'interpret as' type to 'short text, like a title.'
- Percent Read: This is the current percentage read for the book. It must be an "Integers" column.
- Rating: This is the rating of the book. The standard "Rating" column in calibre can be used, or a custom used. If a custom column is used, it must be either a "Ratings, shown with stars" or an "Integers" type column.
- Last Read Timestamp: This is the date the book was last read. This must be a "Date" type column.

To add a custom column to calibre:

1. Open the preferences and select "Add your own columns".
2. Press the "Add custom column" button at the bottom, or the plus at the side of the window.
3. Enter a lookup name for the column. This is used internally by calibre and the plugin.
4. Enter the display name for the column. This is displayed in calibre with the column. This can be anything but should be meaningful to you and the purpose of the column.
5. Select the "Column type" from the drop-down list. Select the appropriate type for the column from those mentioned above.
6. Press OK to create the column.
7. When you have finished adding columns, press the "Apply" button to save the changes. You will be prompted to restart calibre. You must do this before the columns can be used.

### Configuration Steps

Once you have created the columns and restarted calibre, you can set the columns to be used by the plugin. To do this:

1. Open the plugin configuration dialog by either:

- If the device is connected, open the plugin menu and select "Customize plugin"
- If the device is not connected, open the calibre preferences. The select "Plugins" and find the plugin in the list. Select the plugin and press the press the "Customize plugin" button.

2. Select the "Profiles" tab.
3. Select or create a profile.

- A profile can be created for a selected device, no device or any device.
- If a profile exists for a device, it will be used when that device is connected.
- If a profile is is created for the device "*Any device", it will be used if a device is connected that does not have a profile. This can be used if you have only one device.

4. Choose the columns you want to use in the profile.

- For each column, the columns that can be used are listed in the drop-down list. This includes columns of the same type that may be used for something else. Make sure you select the correct column.

5. Select the options for storing the reading status when the device is connected. If no options are selected, the reading status will not be stored automatically.
6. Select the "Devices" tab and choose the backup and firmware update options.

- If a Kobo device connected, press the "Add connected device" button to add it to the list of known devices. This can be used when creating a profile.

7. Select the "Other" tab and choose the function to use when the toolbar button is pressed.

- The toolbar button can have a different function depending on whether you are viewing the library list or the device list.
- For each setting, only functions that are valid for that list are listed.
- From the drop down list, select the desired function.

8. When finished customizing the plugin, press the "OK" button to save the changes.

## Using the Plugin

The following section details each function available and how to use them. Some functions are only available for the library list, some only on the device list and some work for both. Most functions act on the books that are selected in the current list.

For most of the functions available, the way to use them are:

1. Select the books you want to set change something for.
2. Select the desired menu option.
3. When the dialog is displayed, adjust the options.
4. Press the OK button. If the Cancel button is pressed, no changes are made.

### Set Reader Font for Selected Books

When the reader settings are changed in the device, they are stored for that book and for any future book opened. This allows the user to change these setting for one or more books. And, for some of the settings, it allows finer grade options than the device settings dialog.

This option works the same for both the library list and the device list.

The options on the dialog are:

- Font Face: This is the list of standard fonts supplied by Kobo. It does not include any sideloaded fonts.
- Font Size: The device can use font sizes between 12 and 58. The settings on the device provide about 20 options in that size range. The plugin allows any font sizes in the range.
- Line Spacing:

- The device settings allow nine different line spacings. These can be selected using the spin button. "0" is the left-most line spacing on the device and "8" is the right-most. The line spacing value used is displayed in the read-only field.
- If the "Custom setting" option is checked, a custom line spacing can be entered. The value can be any number, but, from experimentation, the minimum value that has an effect is 1.225. Any number lower than that gives the same spacing.

- Left and Right Margin: The device setting use the same value for both the left and right margin, But they can be set separately. The value can be from "0", not margin, to "16". These are the same as selecting the left-most and right-most settings on the device. On the device, each setting jumps by two, The dialog allows single step increments.
- Lock margins: Lock the left and right margins to the same value. Changing the left margin will also set the right margin.
- Justification: From the drop-down, select "Off", "Left" or "Justify".
- Update config file: Update the 'Kobo eReader.conf' file with the new settings. These will be used when opening new books or books that do not have stored settings.
- Get configuration from device: Pressing this button read the "Kobo Reader.conf" file to retrieve the current settings used on the device.
- Get settings from device: Pressing this button will read the database on the device to get the settings for the current book. This will be disabled if more than one books is selected.

Once the settings are how you want them, press the OK button to save the settings and update the database on the device.

### Dismiss Tiles from Home Screen

The new home screen on the Aura HD and Glo uses as set of tiles to display recent activities. These can be pressed to do the same activity or dismissed. The tiles displayed change over time as different as the device is used.

This function is available for both the library and device lists.

When "Dismiss Tiles from Home Screen" is selected, a dialog is displayed. This has:

- The top section lists the type of tiles that can be dismissed. Select each type of tile that is to be dismissed.
- The middle section is to dismiss the tiles for new books and finished books.
- The bottom section creates or removes the database trigger. The trigger will work for the options selected from the top sections. Check the option, and then select whether to create or delete the trigger.

When you have selected the options, press the OK button. This updates the device and displays a message when finished.

Notes:

- This will dismiss all instances of a tile type. Some, such as "Sync" can only appear once. Others such as "Shelf" and "Award" can be on the home screen multiple times.
- Unless the database trigger is created, this does not permanently dismiss the tile. If the activity for the tile is used again, the tile will return to the home screen.
- Sometimes, after the device is disconnected, the home screen needs to be refreshed before the dismissed tiles are removed. This should be done by leaving the home screen and returning to it.
- If this function is used with devices that do not use the new home screen, there will be no affect or damage.

### Display Extras Tiles

The Glo HD does not have as many Extras as the other devices. And Kobo had also removed Chess from the devices. But, if there is a tile on the home screen for the Extras, they can be used. This function can add tiles for the Extras to the home screen.

This function is available for both the library and device lists.

When "Display extras tiles" is selected, a dialog is displayed. This has:

- The top section lists all the know Extras. Select the extras you want to see on the home screen.
- The option "Dismiss current Extras tiles" is there to remove any currently displayed extras tile.

When you have selected the options, press the OK button. This updates the device and displays a message when finished.

Notes:

- Sometimes, after the device is disconnected, the home screen needs to be refreshed before the displayed tiles change. This should be done by leaving the home screen and returning to it.
- If this function is used with devices that do not use the new home screen, there will be no affect or damage.

### Remove Reader Font for Selected Books

The reader settings are stored in a database for each book. This option removes the settings for all books selected. It will prompt you to continue by pressing "Yes" or stop by pressing "No".

This function is available for both the library and device lists. It will work for all book types that store the settings.

### Update metadata in device library

The metadata displayed on the device is read from sideloaded books the first time the device sees them. If the book and metadata is changed and sideloaded again, the metadata is not reread. There is also some standard metadata that is not read from ePubs.

For KePubs synced from the Kobo server, the metadata is populated from the server. It might get changed at later syncs.

This option only works from the library list.

The options on the dialog are:

- Metadata options:

- Title
- Author - the calibre {author} is used. This will correctly populate the author on the device for multiple authors
- Series and Index
- Comments/Synopsis
- Publisher
- Published Date
- ISBN
- Language
- Rating - this is only available if a rating column has been configured for the plugin.

- Reading Status - These options can be used to change the reading status of the books on the device. The function is identical to "Change Reading Status in device library" and it is described there.

### Change Reading Status in device library

This allows the reading status of books in the device that are not in the calibre library to be changed. An intended use is to reset an accidentally opened book to unread. It can also be used to mark books as finished after a factory reset or other reason for reloading books.

The function on dialog is shared with the "Reading Status" section of the "Update metadata in device library" function.

- Change reading status - Select this if you want to change the reading status.
- Unread, Reading and Finished - Select the status to change the books to.
- Reset reading position - If this is selected, when the status is changed,the current reading position is removed. If this is not done, the next time the book opened, it will be opened to the stored position.

Note: When the OK button is pressed, the changes are made on the device. But, the reading status options are not save. The next time the dialogs is opened, all options will be reset. This is deliberate. If this function is used, the decision of what changes to make must be made each time.

### Manage Series Information in device library

This allows you to change the series information for books already on the device. It allows you to set the series name and number for books that you do not have in your calibre. This can change the series information for KePubs.

The interface and most of the function has been taken from the "Manage Series" plugin written by kiwidude. If you are familiar with that plugin, this works in a very similar way, but is restricted to books on the device. If you want to manage series for books in your calibre library, please use the "Manage Series" plugin. The Kobo Touch driver can update the device with this information.

If you find a problem with the "Manage Series" function of the Kobo Utilities plugin, report it to the developer of the Kobo Utilities plugin. DO NOT report it as a bug in the original "Manage Series" plugin.

To manage series on the device, from the device list:

1. Select the books that are in the same series.
2. Select "Manage Series Information in device library"
3. A dialog displaying the list of books with several options is displayed. Here you can:

- In the list at the top, select the series name or enter a new one if the names not in the list.
- Set the starting number for the series number.
- Some Kobo books include the series name in the title. This can look something like Book title (The Whatever Series: Book #1). Selecting "Clean titles of Kobo books" will remove this.
- The title and the publishing date can be edited by clicking in the field and pressing the F2 key. Pressing the escape key will cancel the changes and any other action will save them.
- Change the order of the books by selecting one and pressing the up and down arrows at the right of the list.
- Remove a book from the list by press the trash button.
- Lock or unlock the series number for a book by selecting the book and pressing the lock or unlock buttons on the right. Locking the series number will prevent it an any books after it in the list from changing if the order is changed.
- To undo all the changes, press the "Restore Original Series" button.

4. When finished making changes, press the OK button to save them, or the cancel button to quit. No changes are made to the device database unless the OK button is pressed.

### Store/Restore current bookmark

This allows the current reading position in an ePub to be stored in the calibre library. This can then be sent back to the device or another Kobo device to restore the reading position. As well, the rating set on the device can also be stored and restored.

The device store the reading position in the database on the device. This is stored in several parts:

- The current chapter and the position in the chapter.
- The percentage read of the book
- The reading status: Unread, Read and Finished
- When the book was last read.

These can all be retrieved from the device and stored in custom columns in the calibre library.

This is only available in the library list.

To use this function, you need to:

1. Create the necessary custom columns and configure the plugin. This is described above.
2. Select the books you want to store or restore the reading position for. If books are selected that are not on the device or do not have an ePub format, they will be ignored.
3. Select the "Store/Restore current bookmark".
4. Choose either "Store" to copy the current bookmark to the library, or "Restore" to set the current bookmark on the device.
5. Set the options needed.
6. Press the OK button to do the action.
7. The function will run and a message will be shown with the changes made. When restoring, this is the number of changes made. When storing a list of the books that have changed is displayed. See below for more details.

The options on the dialog are:

- Clear if unread - If using "Store" and the book has not been read on the device, the bookmark values in the library will be cleared.
- Set reading status - This will change the reading status on the device based on the bookmark settings. If the book is 100% read, it will be marked as "Finished". If it is 0% read, then it will be marked as "Unread". Otherwise, it will be marked as "Reading".
- Set date to now - If this is set, then the last read timestamp will be set to now. This will push the book to the top of the "Recently Read" list and the Home screen. If this is not set, then the stored last read timestamp will be used.
- Update rating - Sets the rating on the device from the calibre library.
- Run in background - The store can be run as a background job. When complete, the changes will be displayed in a list to be accepted or rejected.
- Profile - Choose the profile to be used. This defaults to the profile for the currently connected device. But, any profile can be used.

#### The "Show Reading Position Changes" dialog

The "Show Reading Position Changes" dialog shows the list of books whose reading position has changed. Each book is listed with the percent read and last reading date that is on the device and in the calibre library.

The changes can be accepted or rejected. Each book has is ticked. If a book is not selected, the reading position will not be updated in the library when the OK button is pressed. To reject all changes, press the "Cancel" button.

The changes are shown compared to the values in the library for the profile used.

The dialog is shown when the storing the reading status is run as background job. This could be when started manually or when it is run automatically when the device is connected.

### Update the ToC for books on the device

When new books are added to Kobo devices, an import process is run. Details from the new books are extracted from the book and added to the database. The database is then used when the book is displayed in the library on the device.

One of the things extracted from the book during the import is the Table of Contents (ToC). This is added to the database and is used when the book is being read. The ToC displayed when reading is from the database, not the book. As well, any navigation done using the ToC or the next/previous buttons is based on the database version of the ToC. If the book is replaced with a new copy using calibre, it can be replaced without the import being run again. In this case, the ToC in the database will be different to the ToC in the book when it is read. But, the ToC in the database will still be used. This can cause problems when attempting to navigate in the book, or even when opening the book.

This function of the plugin can be used to update the ToC in the database when books have been changed. It only needs to be used then the ToC changes. This means either the ToC entries have changed, or the internal file structure has changed. If there are other changes, such as to the stylesheet, or the text of the book, this function is not needed.

The function supports KePub and ePub on the device. And supports both ePub2 and ePub3.

The function works by:

1. Connect the device and wait for the connection jobs to finish.
2. Select some books in the library.
3. Select the "Update ToC for Selected Books" option in the plugins menu.
4. The function will analyze the ToC for the book in three places: calibre, on the device and the database on the device.
5. A dialog is displayed showing the ToC status of the books.
6. On the dialog, you can select books to send to the device or update ToC in the device database.
7. Press the "Send Books" or "Update ToC" button and the action will be taken.

The dialog shows the results of the comparison and hence the status. The columns shown are:

- Overall status of the book as an icon.
- Title of the book.
- Author of the book.
- "Library ToC" - The number of ToC entries in the book in the calibre library.
- "Library Format" - The format of the book in the calibre library.
- "Kobo ToC" - The number of ToC entries in the book on the device.
- "Kobo Format" - The format of the book on the device.
- "Status" - Shows if the book matches or if it needs to be sent to the device.
- "Send" - Checkbox to for whether to send book when the "Send Books" button is pressed. It will be selected if the above status indicates the book on the device needs to be updated.
- "Kobo Database ToC" - The number of ToC entries in the database on device.
- "Status" - Shows if the ToC in the database needs to be updated compared to the book on the device.
- "ToC" - Checkbox to for whether to update the ToC in the database when the "Update ToC" button is pressed. It will be selected if the ToC status indicates the database on the device needs to be updated from the book on the device.
- "Reading Position" - Reading position in the database. Currently this is not used.
- "Comment" - Describes the status of the book and what needs to be done.

The three status columns use the following icons to show the status:

- Green tick - ToC matches and nothing needs to be done.
- Device icon with arrow - The ToC does not match between the calibre library and the book on the device.
- ToC icon with hand - The ToC needs to be updated in the database on the device.
- Red x - Nothing can be done for the book on the device. This usually means the format on the device is not one supported for this function.
- Red minus - Some other problem. This will probably not be displayed, but, is used internally.

The icons used are part of calibre so may be replaced by an icon theme.

The comparisons are done purely on what Kobo extracts from a book as the ToC. This is done when the book is imported on the device. The details are from the ToC in the book and the manifest. The changes considered are the actual ToC in the book and any related internal file names. This means the ToC will be considered different if any of the following are different:

- Total number of ToC entries.
- Internal file name for a ToC entry. Including any directory names.
- Text for a ToC entry.
- ToC entry depth.

No attempt to check for any other changes in the book are made. If things like spelling or styles are changed, these will not trigger any issues on the device if the book is replaced properly.

When the ToC is updated in the database, it is completely replaced. It is always updated from the copy of the book on the device. If this copy does not match the book in the library, the book should be sent to the device first.

The way I use this is:

1. New or changed books are added to the send-to-device Reading list.
2. Books where the ToC has changed are added to an "Updated" reading list. If I am not sure that something in the ToC has changed, I will add the books to the list.
3. When I connect the device, the books on the send-to-device Reading list are sent and the list is cleared.
4. I display the books in Updated reading list and select them all.
5. I then use the function to check for changes to the ToC. And update as needed.

### Upload covers for Selected Books

With this, you can change the cover on the device to the current cover in the calibre library.

To use it, select the books that you want to change the cover for, and choose the desired options. Then press the OK button to upload the covers.

The options on the dialog are:

- Black and White Covers - Covers are converted to black and white before uploading.
- Keep cover aspect ratio - When the covers images are sized for device, the current aspect ratio is kept. This can improve the look of the covers on the home screen and library lists.
- Upload covers for Kobo ePubs - Replace covers for Kobo KePubs with the cover from the calibre library.

### Remove covers for Selected Books

This will remove saved covers for the selected books from the device. This will allow the device to regenerate covers for these books when they are next needed.

To use it, select the books that you want to change the cover for, and choose the desired options. Then press the OK button to remove the covers.

The options on the dialog are:

- Remove covers for Kobo ePubs - Replace covers for Kobo KePubs with the cover from the calibre library.

This function is available for both the library and device lists. It will work for all book types that store the settings.

### Clean Images Directory

This looks at the images directory on the device and looks for any cover images that are not for books currently in the device database. The cover images can be removed or simply listed.

To use it, select the menu option and choose the desired options. Then press the OK button to check and clean the images directory. The clean is run as a background job.

The options on the dialog are:

- Delete extra cover image files - Delete an extra cover images found in the directory.

When the job is finished, how many extra cover image files were found and deleted is displayed. Pressing the "Show Details" button will list the extra cover image files that were found.

### Order Series Shelves

Using the KoboTouch driver, shelves can be created for each book series on the device. The books are then added to the shelf. But, there is no way to sort these shelves into the series order. This option allows uses the "Date Added" sort to show the books in the series order.

To use it, select the menu option. A dialog with the list of series shelves will be displayed. The shelves listed are those that have the same name as for series that are on the device. The number of books on each shelf will be displayed.

Select the options and press the OK button to order the shelves. The options on the dialog are:

- The "Series Order" order is either "Ascending" or "Descending". Choosing "Ascending" will put the books in the series order. Choosing "Descending" will put them in reverse order.
- If "Update config file" is selected, the selected sort order for the series shelves will be set to "Date Added" in the "Kobo eReader.conf" file. The is the sort order needed to display the books in the series order. If this option is not selected, the sort order will need to be changed when viewing the shelves.
- To skip ordering a shelf, select it in the list and press the "Remove" button.

When the shelves are ordered, a message box will be displayed with the number of shelves whose order was set. If the shelf only had one book on it, the shelf order will not be changed.

To see the books in the series order, select "Date Added" when viewing the shelf on the device.

A few notes about the ordering:

- Only books that have a series name that match the shelf are ordered.
- The books also have to have a series number. Some books from Kobo do not have the number.
- If the series number is not just a number, an attempt is made to extract the number. Again, books from Kobo frequently have a hash symbol in front of the number. If a number cannot be found, the book is not ordered.

This function is available for both the library and device lists.

### Set Related Books

As part of the details of each book, there is a "Related book" section. Kobo populates this for books synced from the Kobo server with a list of books that are in some way related to the current book. The related book could be from the same series, the same author or in a similar genre. Usually, it can be seen why the book is there, but occasionally it is not obvious.

To see the related books, go to the library list on the device and long press on a book to display the menu. On the menu, press "Details". The details of the book will be displayed. At the bottom is a section that can be changed. Select "Related books" in this section to see the books.

This also works for sideloaded books. But, the Kobo server does not populate this for sideloaded books. This function can. It allows you to set the related books as either all the books in the same series, or all the books by the same author. This is an alternative to using a series or author shelf as a way of grouping books.

To set the related books for sideloaded books:

1. Select the "Set Related Books" option from the plugins menu.
2. The dialog is displayed with options to set whether to set the related books by "Author" or "Series".
3. Select which type to use and press the "Get list" button. The list will be populated with the names and the number of books.
4. A name can be removed by selecting it and pressing the "Remove" button. This means that the selected books will not be set for books belonging to that series or author.
5. When ready, press the OK button to set the related books.

The related books will be set for all the names in the list. If there was only one book with the name, nothing will be done. This will also replace all current related books. This can take some time and a message will be displayed when finished.

If the "Delete All" button is pressed on the options dialog, all current related book entries for sideloaded books will be removed from the device database.

The function uses the device database for determining the related books. This means it can operate on all sideloaded books on the device, not just those in the current calibre library. It also means that the series name or author needs to be correct and consistent.

### Copy annotations for Selected Book

This will retrieve any annotations for the selected books and display them in a dialog. The annotations can be copied and save elsewhere. The annotations are retrieve using the same code as the "Fetch annotations".

### Backup Annotation File

Annotations for ePubs are stored on the device in two places: the internal database and files. The files have type "ANNOT" and are stored within the directory Digital Editions\Annotations. These files are contain XML that define the annotations. They can be copied to another Kobo device, or with a little fiddling, used with ADE.

Selecting this option will prompt for a directory to copy the files to. Either enter the directory name, or press the "..." button to select a directory. When the directory has been entered, press the OK button to copy the files.

### Remove Annotations Files

Annotations on the device are stored in two places. For all books, they are stored in the device database. For ePubs and PDFs that are in the main memory of the device, the annotations are also stored in a file. This file is created by the Adobe RMSDK. This is used by the firmware for reading ePubs and PDFs.

There are two problems related to the annotations files.

- The annotations files are read when the books are opened. While this works, some information is lost. This is which chapter the annotation is in, and how far thought the book the annotation is. When the book is reopened, the annotations list will show all annotations as being in the current chapter, and the percent through will be zero. Everything else about the annotations will still be correct.
- When the book is deleted from the device, the annotations file is not removed. What this means is that if a new copy of the book is sent to the device, it will get the annotations from the last copy when it is opened. This is fine if the book is the same or the only changes have been in the text such as correcting spelling or grammar. But, if changes to the structure of an ePub is made, it can cause problems when the book is opened to a page with an incorrect annotation.

Because of the above problems, it may be a good idea to remove the annotations files if you are reading ePubs in the main memory.

As the annotations files are created by the RMSDK, they are in the directory, "Digital Editions/Annotations". Within this directory, there is one file for each ePub or PDF that has been opened. The path and name of the annotations file is the same as for the book file with ".annot" added as an extensions.

To use this function:

1. Select the "Remove Annotations Files" option from the plugins menu.
2. Select the option for which annotations files are to be removed. These options are:

- All - Remove the annotations directory and all files within it
- For selected books - Only remove annotations files for the selected books
- Where book is not on device - Remove annotations files where there is no book on the device
- Empty - Remove all empty annotations files
- Not empty - Only remove annotations files if they contain annotations

3. Press the OK button to process the options.

When the processing has been finished, a message will be displayed indicating how many files where removed.

### Show books not in the device database

There are several circumstances where calibre will think a book is on the device, but it is not in the device database. This usually means the book has been sent to the device by calibre, but the book has not been processed yet.

When selected, a list of books is displayed in a separate window. This is simply a list of the books and has no function other than to display the books.

Note: This does not show any books that are on the device and calibre does not know about and are not in the device database. If books have been sideloaded in some other way and are not in the device database, they will not be displayed.

This function is only available when viewing the device list.

### Refresh the list of books on the device

When this is used, the books on the device will be reread. This is done in the same way as when the device is first connected. The main use for this is it will cause any changes for shelves an series information to be sent to the device.

### Fix Duplicate Shelves

Due to some errors with syncing to the Kobo server, the shelves occasionally appear to be duplicated. There are several things that can happen, but in one case old shelves that have been deleted are recreated.

To use it, select the menu option. A list of all shelves with the following information is displayed:

- Shelf Name
- Oldest - Date when oldest version of the shelf was created
- Newest - Date when newest version of the shelf was created
- Number - Number of versions of the shelf

To fix the duplicates, choose the options and press the OK button. The options are:

- Shelf to Keep: This can be either "Newest" or "Oldest". This determines which of the duplicate copies of the shelves should be kept.
- Purge duplicate shelves: Selecting this will delete the rows for the duplicate shelves from the database.

When the OK button is pressed, the duplicate shelves will be marked for deletion. The version of each shelve that is kept will be the one with either the newest or oldest date, depending on the options. After this is done, you should disconnect the device and sync to the Kobo server. This should remove all the duplicates from the server and should solve the problem.

If the Purge duplicate shelves option is selected, the duplicates will be deleted from the device database. If this is done and a sync to the Kobo server is then done, it is possible that the server will send all the shelves to the device again. But, if you don't sync the shelves in the future, this probably isn't important.

This function is available for both the library and device lists.

### Block Analytics Events

The Kobo devices collect information about actions taken on the device. This is stored in a database table called "AnalyticsEvents". There is evidence that this information is sent to Kobo during a sync. It is unknown how Kobo store or use this.

To use it, select the menu option and choose the desired options. Then press the OK button. The entries already in the AnalyticsEvents table will be deleted and a database trigger installed to prevent further entries from being created.

The options on the dialog are:

- Create or change trigger - When this is selected, the database trigger will be created or updated if it already exists.
- Delete trigger - This will remove the existing trigger and let the device work as Kobo intended it.

This function is available for both the library and device lists.

### Check the device database

Unfortunately, there are circumstances where the database on the device can become corrupted. When this happens, the database usually has to be replaced. This means loss of annotations and reading status for any sideloaded books. With this option, the status of the database can be checked.

One of the signs of a corrupt database is an error from calibre when the device is connected. This error is "DatabaseError: database disk image is malformed". When using the device, the symptoms can include things like the loss of reading position or the same books being processed multiple times.

Selecting this option will run PRAGMA integrity_check against the database and display the output in a window. If there are no problems with the database, "ok" will be displayed in the window. If the database is corrupt, the errors found in the database will be displayed.

If there is an error in the database, there is generally not much that can be done to fix it. If the problem is only with the indexes, then compressing the database might fix it. But, most errors will only be fixed restoring a database backup, or signing out of the Kobo account on the device and signing back in. If this doesn't work, a factory reset might be needed.

### Compress the device database

As books are added or removed from the device, their details are added or removed from the device database. This causes the size of the database file to increase. This option will compress the database file to clear unused space.

Selecting this option will run VACUUM against the database. When finished the uncompressed and compressed sizes of the database are displayed. If there is an error, the error message will be displayed.

It is recommended that you backup the device database before compressing it.

### Backup device database

This will copy the device database to somewhere on your computer. This will allow it to be restored if the database is ever corrupted.

When started, you will be prompted for a directory where to backup the database and a name for the backup. Once these are selected, pressing "Save" will copy the database from the device.

If you would like to run the backup when the device is connected to calibre, see "Automatic Device Backup".

### Automating Actions

The plugin can automate some actions when the device is connected. These will be run when calibre first sees the device and has run the initial device jobs to get the list of books from the device.

The following sections describe the actions that can be automated.

#### Storing Reading Positions

#### Device Backup

A backup of the device database can be run when the device is connected. This can be done either the first time the device is connected each day, or every time it is connected.

When the database backup is run, some configuration files are also backed up.

Configuring the automatic backup is done on the plugin configuration. To do this:

1. Open the configuration dialog.
2. Select the "Devices" tab.
3. The backup can be configured the same for all devices, or individually. The options are the same for both.
4. If configuring the same for all devices, uncheck the option "Configure options for each device".
5. The options to change are in the "Device Database Backup" section.
6. Choose between "Backup the device database daily" and "Backup the device database on each connection" for how often the backup is done. The first will do a backup the first time the device is connected to calibre each day. The second will do it each time the device is connected. If neither is selected, the backup will not be done.
7. Enter a destination directory for where the backup is to be stored.
8. Select "Copies to keep" and enter a number if you want to keep several backups. The plugin will delete older backups when this number of backups is reached. If it is not entered, you will need to manually delete old backups.
9. The configuration files are put into a zip file. If "Compress database with config files" is selected, the database backup is also put into this file. This will save space. If the option is not selected, the database backup will be saved as a separate file.

When the device is connected, a background job is started in calibre to do the backup. The first step of this job is to determine if a backup is needed. If it is not, then nothing is done. If a backup is needed, the following steps are done:

1. The device database is copied to the backup destination
2. A check is run on the database to make sure it is not corrupt. If it is corrupt, an error will be display and the backup file will have "CORRUPT" added to the name. No further action is taken.
3. The configuration files are copied to a zip file in the backup destination.
4. If the database backup is to be compressed, it is moved into the above zip file.
5. If the copies to keep has been set and there are more than this number of backups, the oldest are deleted until the correct number are left.

The backup files are named to show when the backup was done and which device. The format of the name is:

> KoboReader-<device model>-<device serial number>-<timestamp>.[zip|sqlite]

Where:

- <device model> is the model of the Kobo device.
- <device serial number> - is the serial number of the device.
- <timestamp> is the timestamp of when the backup was taken.
- The extension for the database backup will be "sqlite". The extension for the compressed file with the configuration files is "zip".

#### Check for Kobo Updates

### Customize plugin

This displays the configuration dialog. The details are in "Configuration" and the following sections.

### About Plugin

This shows the usual about dialog for the plugin.

## Problems

If you problems, you can find me on the MobileRead forums. The best way to get support is by posting a message in the thread for this plugin. It is Kobo Utilities. I monitor the thread and as long as I am not away or sick or something, I will see it within a few hours. And if I am not around, someone else is likely to try and help. And it is likely that there is already discussion for any common problems.

You can also send a PM (private message) to me. My profile is davidfor. I will respond to PMs, but my response will be no faster than if you post in the thread.

When posting about a problem, please give as much information as possible. In general, there is no such thing as to much information when trying to debug remotely. And if you think "he won't need that", it is almost guaranteed to the most important bit.

When a problem is reported, I will respond as quickly as I can. But, remember, it will take time to read the report, think about what could be going on and then write a response. And I am probably in a different timezone to you. Plus, this is done in my spare time. I work, have a family and like to use my Kobo devices for their intended purpose, reading. If I know I am going to be away for a few days, I will try to post in the thread or inform someone of what is happening.

After hearing of a problem, I might ask you to run calibre in debugging mode and send me the output produced. If I do, these are the steps:

1. Restart calibre in debug mode by clicking on the arrow next to the preferences button and selecting "Restart in Debug mode".
2. Calibre will close and reopen. When calibre reopens a message about being in debug mode will be displayed.
3. Perform the actions in calibre that are not working as expected. This will normally mean connecting the the device and waiting for it to sync and then using whichever of the plugins functions didn't work for you.
4. Close calibre.
5. The calibre debug log will then be displayed.
6. Send a copy of the log file to me when requested.