Installing KOReader in the Kindle

March 31, 2024

A few years ago my trusty Kindle Paperwhite, which I had since its launch in 2012, decided that the battery had had enough. I bought a new one, and since then, the old one has been relegated to gathering dust on the bookshelf.

More recently, I was investigating alternative e-reader devices, preferably open source, to stop using Amazon products. It was at that time that I stumbled upon KOReader, an e-reader application that can be installed on various e-ink readers, with lots of customization options.

Before risking bricking my new Kindle, I set on trying KOReader on my old device. This document has a few notes on what I had to do to achieve it. It mainly links to Mobile Read threads, so please go there for the proper documentation.

Please, keep in mind that this only works for the first Kindle Paperwhite (2012 version), but some of the pages I link below have pointers on how to do it for other models. In case of doubt, refer to this thread on Mobile Read.

Caution: this can render your device unusable.

Downgrading the firmware

I always kept my old Kindle connected to the Internet, so it had the latest firmware version that Amazon released for it. In my case, the version 5.6.1.1. The jailbreak method that I found only works for versions 5.0.x to 5.4.2.2, so I had to install an older version of the firmware on my Kindle before I could proceed.

I found this guide that explains how to downgrade from version 5.6.1.1 to 5.3.3.

Download the firmware from the above page.
Put Kindle on “airplane mode” (WiFi and 3G disabled)
Connect that Kindle to the computer, with a cable that allows data transfer, not only charging.
Copy the “bin” file previously downloaded to the root folder of the Kindle.
Without disconnecting the Kindle from the computer, press the start button for about 20 seconds to force a restart.
After the restart, you should see a screen on the Kindle informing you of the progress of the “update” (the downgrade).

Jailbreaking the Kindle

Now that the Kindle has the old breakable version, we can use the jailbreak explained here.

Download the firmware from here. It's the “K5 JailBreak” zip file.[^1]
Unzip the file “kindle-5.4-jailbreak.zip” and copy the contents (not the whole folder, only the contents), to the root folder of the Kindle.
Eject and unplug the Kindle from the computer.
In the Kindle, go to Settings and in the menu at the top right choose the option “Update your Kindle”.
After a few seconds, you should see a message at the bottom of the screen saying “*** JAILBREAK ***“. This message confirms the successful jailbreak.

Installing KUAL (the launcher)

To be able to install other applications in the Kindle, first we need to install a “launcher”, that will enable us to find and execute our programs. I chose KUAL, as the documentation I found was accessible and easy to understand.

The installation instructions are here.

Plug the Kindle into the computer again.
Download KUAL from the Snapshots page.
Unzip it, and copy the file KUAL-KDK-2.0.azw2 to the documents/ folder of the Kindle.
Eject the Kindle from the computer.
In the Kindle, you should see a new “book” called Kindle Launcher.
- The Kindle should be in the “Local Library” view, not in the “Cloud” one. Otherwise, you won't see the launcher.
- I had a lot of books, so it took me a while to scroll through all to find the launcher. If that's your case as well, you can filter the books by “Active Content”. This filter is the dropdown that appears just above the books grid, usually filtered by “Books” or “All Items”.
Click the Kindle Launcher book to open KUAL.
- If you see an error message saying “This device is not authorized as a test Kindle by the developer of this item” or similar, go to the Settings of the Kindle and Reboot the device. It should work after.

Installing KOReader

Now we're ready to install KOReader (or any other application / KUAL extension that you desire).

Download the latest version from here.
- For my case, a PW1, I downloaded the file “koreader-kindle-vXXX.zip”. If you have another version, check this page to know what file to choose.
Unzip the file and copy the contents to the root folder of the Kindle device.
- Careful with the extensions/ folder, since it could already exist with some content on the Kindle. Make sure to not override or delete any content already present in that folder.
You can now launch KUAL from the Kindle and the launcher will show you a menu to open KOReader.
- As they mention on the GitHub page, don't plug your Kindle to the computer in USBMS[^2] mode while KOReader is open.
Check the user guide for KOReader here.

Disabling OTA updates

By this point, the Kindle is still in “airplane mode”, so the only way to transfer books is via USB, copying the ebook to the documents/ folder.

You can disable the airplane mode at any time to use any of the transfer options offered by KOReader, but there will be a risk of Amazon sending an OTA update to your device and erasing the jailbreak.

To enable Internet connectivity on the Kindle without suffering this risk, we have to do cheat the device into not installing the updates.

Following this guide, create a folder in the root of the Kindle, named “update.bin.tmp.partial”. It has to be a folder, not a file.
Install the BackDoorLock hack:
- Download and unzip the file “http://backdoorlock_kual_12.zip”.
- Move the contents to the extensions/ folder on the Kindle.
- Eject the Kindle from the computer.
- Open KUAL, click on “Back Door Lock”, and click on the option “Lock the back door”.

Lastly, for safe measure, I've also blocked some domains in the Pi-hole, using regex: amazon, cloudfront.net, and kindle.com. This last one is only used for DNS (dns.kindle.com), as far as I've seen, but I blocked it anyway.

Curiously, blocking these domains has completely broken the “experimental browser”, even for non-blocked domains. This also blocks the Kindle store.

After these changes, I tested the Internet connectivity from KOReader, and it works fine. It can connect to Wikipedia, download dictionaries, etc.

[^1]: On Mobile Read, the Kindle Paperwhite from 2012 is referred to as PW, PW1, or sometimes K5, depending on the hacks' compatibilities. To check the nomenclature of your device, check this page. [^2]: USBMS means USB Mass Storage. This is the mode that allows data transfer. To avoid using this mode while keeping the Kindle plugged into the computer for charging, “eject” the Kindle as you would do with any USB device before unplugging it.

#tech