1 month ago
Installing KOReader onto a Kobo
This week, I set up a Booklore instance to allow me to wirelessly sync ebooks to my Kobo e-reader.
However, in the (short) time since, I've run into a bit of a limitation: Booklore's Kobo sync doesn't support PDF files (which seems to be a limitation of the way that Kobo fetches files from its store rather than Booklore specific).
Most of the _books_ that I read are in EPUB format, but I've also got various user manuals and technical reference docs in PDF that I'd like to be able to fetch onto the reader, on demand.
Although I _could_ use a USB cable to sync PDFs over, it'd somewhat undermine the point in running Booklore in the first place.
So, I decided to install KOReader onto my Kobo.
KOReader is a document reader designed for e-ink devices and can fetch books (and more importantly, PDFs) from Booklore via OPDS, syncing reading progress back via Booklore's dedicated KOReader api.
This documentation details how to install KOReader onto a Kobo before configuring it to work with Booklore. If you're a Calibre user, KOReader can also talk to Calibre.
* * *
### Installing KOReader
In order to actually _run_ KOReader, we also need to install a launcher: KFMon.
Plug your Kobo into your computer and add the following to `.kobo/Kobo/Kobo\ eReader.conf` to prevent the Kobo from attempting to index KOReader's application files:
[FeatureSettings]
ExcludeSyncFolders=(\\.(?!kobo|adobe).+|([^.][^/]*/)+\\..+)
Download the latest KFMon release (the latest is attached to this forum post) and then extract it into the Kobo's root directory:
curl "https://www.mobileread.com/forums/attachment.php?s=5ed946e0efd33c5eb358887feb1b368f&attachmentid=220113&d=1767688393" -o /tmp/kfmon.zip
cd /media/ben/KOBOeReader/
unzip /tmp/kfmon.zip
Next, change into the `.adds` subdirectory and extract the latest `KOReader` release:
curl -L https://github.com/koreader/koreader/releases/download/v2025.10/koreader-kobo-v2025.10.zip -o /tmp/koreader.zip
cd .adds
unzip /tmp/koreader.zip
Eject and unplug the Kobo.
It'll tell you that it's installing an update:
Once it's done installing, the device will reboot. I had a brief moment where I worried that I'd bricked it:
However, about 20 seconds later it started booting and KOReader appeared as if it were a book:
* * *
### Connecting to Booklore
To integrate fully with Booklore, there are two things which need to be configured
* KOReader sync
* OPDS browsing
The first pushes reading progress back to Booklore, while the second grants access to the full library.
* * *
#### KOReader Progress Sync
Progress sync is **decidedly** easier to find in KOReader's menus.
Hit the Settings Icon (spanner and screwdriver, not cog) -> `Progress Sync` -> `Custom Sync Server`
Enter the KOReader URL taken from Booklore's settings interface:
Hit `OK` and then hit `Register / Login`. Enter the credentials from Booklore and then hit `Login`.
Unfortunately, testing suggests that progress sync doesn't work with PDFs1.
* * *
#### OPDS Syc
KOReader has OPDS support built in but you won't easily discover it on first launch.
The OPDS option doesn't appear in the menus if you're in reading mode (which KOReader opens by default).
Instead, you need to be in the filebrowser view - tap the top of the screen to display the menus and then choose the filing cabinet icon
Then, tap the top again to re-open the menus and choose the magnifying glass. You should see `OPDS catalog` at the bottom
If you hit the three bar menu at the top, there's an option to `Add OPDS catalog`. This will open a dialog allowing you to provide the catalog URL and credentials:
Once you've entered the OPDS URL and credentials (taken from Booklore's settings UI) you should be able to browse your libraries:
Tapping an item will open a dialog offering to save it to your device ready for reading.
* * *
### Making Downloaded Books Available To Kobo Reader
Ideally, I wanted to avoid having to read PDFs in a different interface to the one that I was used to when reading ebooks.
This _is_ actually supported out of the box, but comes with a particularly frustrating niggle.
For a book to show up in the main view, the Kobo must have re-indexed its storage. This happens, for example, after you eject the Kobo from a computer. That's not _particularly_ helpful when trying to set up fully remote syncing though.
Thankfully, there's a solution - NickelMenu - which allows you to add menu items to Kobo's launcher (Nickel).
Plug the Kobo into your computer and download NickelMenu onto it:
cd /media/ben/KOBOeReader/.kobo
curl -L https://github.com/pgaskin/NickelMenu/releases/download/v0.6.0/KoboRoot.tgz -o KoboRoot.tgz
Next we create a couple of menu items:
cd /media/ben/KOBOeReader/.adds
mkdir nm
# Create a menu item to launch KOReader
echo "menu_item:main:KOReader:cmd_spawn:quiet:exec /mnt/onboard/.adds/koreader/koreader.sh" > nm/koreader
# And one to trigger rescan
echo "menu_item:main:Rescan:nickel_misc:rescan_books" > nm/rescan
Eject and remove the Kobo. It should tell you that it's installing an update:
Once it boots back up, you should have a new menu available:
NickelMenu has support for a lot of actions so it's also possible to add menu items to do everything from forcing dark mode to shutting the e-reader down.
* * *
### Conclusion
Although I was slightly frustrated at the _need_ , getting KOReader up and running was quick and easy.
Navigating KOReader's menus can be a little unintuitive and I found myself getting lost a few times. But then, I don't think _any_ e-reader has a particularly intuitive navigation structure.
It's a little disappointing that progress sync isn't reliably working for PDFs but, in all honesty, I'm unlikely to notice it much in future - most of the documents that I have PDFs for aren't things that are read progressively like a book, instead I tend to flick to a specific location.
Overall, though, I think it's been a fairly beneficial step forward: KOReader seems to do a better job of displaying PDFs than Kobo Reader **and** the resulting introduction to NickelMenu is probably going to open up an entire world of interface customisation.
* * *
1. From the very quick look that I've had, this looks to be a Booklore limitation rather than a KOReader one - I'm guessing that the two are using different methods to figure out reading location ↩
New #Documentation: Installing KOReader onto a Kobo
Author: Ben Tasker
www.bentasker.co.uk/posts/documentation/gene...
#ebook #kobo #koreader #nickelmenu
0
0
0
0
