At first sight, KOReader [1] looks disappointingly bare bones. But behind its unassuming interface hides a powerful application with an impressive array of features, from extensive gesture support to a built-in SSH server. Combined with a handful of hacks and a bit of creative thinking, you can use KOReader to unlock the full potential of your ebook reading device.

Installing KOReader

Although KOReader is available as an Android app and a Linux desktop application, its natural habitat is e-ink devices. How you install KOReader depends entirely on the ebook reader you have. Fortunately, the project's wiki [2] provides detailed installation instructions for all supported devices. Normally, installing KOReader requires copying files in the appropriate directories in the ebook reader's filesystem, so the process requires neither deep technical knowledge nor effort.

First Things First

While KOReader comes with sensible defaults, there are several settings you'll want to tweak for an optimal reading experience. The first thing to do is add custom fonts to KOReader, which is a rather straightforward affair. KOReader supports TrueType fonts (TTF), so all you have to do is to copy a folder with .ttf files to the koreader/fonts directory on the ebook reader. To enable any of the added fonts, open KOReader, tap on the upper edge of the screen to open the top bar, and choose Document | Font (Figure 1). To set the desired font as the new default, long tap on the font's menu entry and tap the Set as default button.

Figure 1: Selecting a custom font with KOReader.

Long tap on a configuration option prompt to set it as default. For example, long tap on the desired value of the Line Spacing option in the bottom menu, and tap Set as default. Speaking of the bottom menu, by default, activating the top bar also opens the bottom menu. While it's probably meant as a convenience, it becomes a nuisance rather quickly. To disable this option, open the top bar, choose Settings | Taps and gestures | Activate menu, and disable the Auto-show bottom menu option (Figure 2).

Figure 2: Disabling the Auto-show bottom menu feature.

By default, when you launch KOReader, it opens the file manager, so you have to manually select the book you want every single time you launch KOReader. Making KOReader automatically open the last viewed book when the application starts is more practical in most situations. Open the top bar and switch to the file manager. Tap on the top header to open the main menu, switch to the file manager section, and select Start with | Start with last file.

The status bar at the bottom of the screen provides useful information, such as reading progress, time, etc. By default, you can cycle through the available views by tapping on the status bar. But you can also squeeze all the information you find useful into a single view. To do this, open the top bar, choose Settings | Status Bar | Settings, and enable the Show all at once option. Return to the Settings | Status Bar menu and toggle the desired options (Figure 3).

Figure 3: Configuring the status bar.

While an e-ink display doesn't require a screensaver, there is nothing wrong with replacing the plain Sleeping message with something more informative, such as the current book along with your reading progress. Open the top bar, choose Settings | Screen | Screensaver, and enable the Use last book's cover as screensaver option. Enable Add message to screensaver, then choose Settings | Screensaver message, and specify the Page %c of %t message to show the current and total page count (Figure 4).

Figure 4: Configuring a custom screensaver message.

Going Further

With the basic settings sorted out, it's time to explore what else KOReader has to offer. Using KOReader's profiles functionality, you can create multiple reading configurations and quickly switch between them. For example, you can create a dedicated profile for night reading, with specific front light settings (brightness and color temperature), night mode enabled, etc. And you can create a daytime profile with both the front light and night mode off. To create a profile, open the top bar and choose Tools | Profiles | New, configure the desired settings, and you are done. To enable the created profile, long tap on it.

Like any reading application worth its salt, KOReader supports highlights, and it can export them as HTML, JSON, and plain text files. If you happen to use Joplin [3] as your preferred note-taking application, you'll be pleased to learn that KOReader can push highlights directly into it. The initial setup process requires some work, but once it's done, transferring notes to Joplin is easy.

First, you need to configure Joplin. Launch the application, choose Tools | Options, and switch to the Web clipper section. Press Enable Web Clipper Service and copy the automatically generated authorization token (Figure 5). Leave Joplin running.

Figure 5: Enabling Web Clipper in Joplin.

Install the socat package. To do this on Ubuntu and Linux Mint, run the command:

sudo apt install socat

Connect your e-reader to the machine, enable Start USB storage in KOReader, and open the koreader/settings.reader.lua file for editing. Locate the ["exporter"] section and add the following entries to it (replace 127.0.0.1 with the actual IP address of the machine running Joplin, and replace authorization_token with the copied token):

["joplin_IP"] = "127.0.0.1",
["joplin_token"] = "authorization_token",
["joplin_port"] = 41185,
["joplin_export"] = true,

Save the changes and safely disconnect the e-reader. On the machine running Joplin, open the terminal, and run the following command:

socat tcp-listen:41185,reuseaddr,fork tcp:localhost:41184

In KOReader, open the top bar, choose Tools | Choose formats and services, make sure the Joplin option is enabled, and tap either Export all notes in this book or Export all notes in your library.

Unlike any other available ebook reading applications, KOReader comes with a built-in SSH server. Enable it, and you can connect to your ebook reader from any machine on the same network. Not only can you move books to and from the device, but you can also have full access to its filesystem. To enable the SSH server in KOReader, open the top bar, switch to Settings | Network | SSH Server, enable the Login without password option, and start the SSH server.

Once the SSH server is running, KOReader displays a dialog with connection information. Note the IP address of the e-reader. Using a machine on the same network, establish an SSH connection to the e-reader using the following command (replace 127.0.0.1 with the actual IP address of the e-reader):

ssh -p 2222 root@127.0.0.1

On most Linux distributions, the default file browser can handle the SSH and SFTP protocols. So you can access the e-reader's filesystem by specifying its address in the location bar of the file browser. For example, ssh://root@127.0.0.1:2222.

The easiest way to connect to KOReader via SSH is to enable the Login without password option. The easiest approach is also the least secure one, as anyone on the same network can get root access to the e-reader. So it's a good idea to allow SSH access only to authorized devices. To do this, you need to generate an SSH key pair on the device you want to connect from to your e-reader.

To generate an SSH key pair on a Linux machine, run the ssh-keygen command in the terminal. Follow the prompts, but skip specifying a passphrase. Run the command

cat .ssh/*.pub

and copy the key. Connect the e-reader to the machine and create the authorized_keys file in the koreader/settings/SSH directory. Open the file for editing, paste the copied key in it, and save the changes. From now on, you don't have to enter a password when you connect to the e-reader from the authorized machine.