Introduction

This post is a little backstory of why this was important to me and how to get Wallabag articles onto your Kobo eReader. I use the Kobo H2O but judging from the documentation it could apply to many of the Kobo eReaders.

What’s a Wallabag?

Wallabag is what’s called a “read it later” service. The software allows you to create a curated library of news articles to read later. I like to read bunch of articles serially, instead of when they pop up.

This forces me to only save articles that are less time-sensitive and encounter less articles meant to create fomo or a sense of urgency. By saving the articles in Wallabag, you also remove distractions such as newsletter prompts, ads, and related articles that may entice you to read about something you didn’t originally intend to read.

What is a Kobo?

A Kobo in this case is referring to an electronic reading device called an eReader. You can read many types of content on an eReader but most people read books (the electronic format of them) on them.

eReaders differ from electronic tablets in the way that means that the screen is more paper-like. The screen doesn’t emit light like a smartphone or tablet screen but rather reflects the light that is shone on it.

Some eReaders come with a backlight, but these are often simply cool to warm LED lights that are positioned to have the light reflect off the paper-like screen.

I won’t get into the psychology or physics of this except to say that your brain and eyes treat and react to this light differently.

Why combine the two?

I have the option to use Wallabag on my phone, without much effort. Just download the app and use the API credentials to connect. I’ll always have the articles I saved available because my phone is connected to the internet, right?

Well, see, that’s part of the problem here. Between notifications from apps, the possibility of using the internet, and all the shiny colours and distracting animations, my phone is just too “energetic” compared to an eReader. There’s always the opportunity to pull up an app and surf some sort of social media, always some email that pops up here and there that will catch my attention.

I could just as easily disable all notifications when I’m in reading mode by enabling do not disturb. But then I could still wander off to try and research some random detail about the article I’m reading. I could pull up a word game to distract my brain from the topic at hand. The phone is simply imbued with too much potential for my impulsive brain to resist.

So my solution is to get those news articles onto my eReader.

KOReader

Enter KOReader, an alternative document view for E Ink devices. This basically acts as an app that lives on your E Ink device of choice. This app is extensible in the sense that you can connect the reader to several external services, even your NextCloud instance if you want to share an eBook library between you and some friends.

In my case, I wanted to configure the Wallabag plugin to connect to my self-hosted Wallabag instance so that I could download the articles to my Kobo. By doing this, the articles are downloaded and then converted to ePub format, allowing KOReader to open the articles as an eBook.

KOReader Installation

These instructions are specific to macOS as that is the platform I’m running, but they will be very similar on Linux.

Following these instructions will allow you to install KOReader. Also installed will be KFMon, which is a file monitoring software. This software allows the Kobo eReader to perform some file processing tasks in the background, in an efficient manner. NickelMenu is also installed. This adds a menu item in the Kobo navigation bar on the bottom that allows you to launch KOReader.

NOTE: While I have provided direct links below to the install packages, they may be out of date by the time you read this.

1. Plug your Kobo eReader into your computer. Usually this is done with a USB-A or USB-C to microUSB or USB-C cable. When prompted, tap on the connect button that will show up on the screen.
2. On this page download the One-Click Kobo package for KOReader (direct link).
3. Further down on the same page, download the macOS install script archive (direct link)
4. Within Finder, double-click on the OCP-KOREader-* zip file to unzip it.
5. Double-click on the kfm_mac_install.zip file to unzip it.
6. Open your terminal app of choice and navigate to your downloads folder (or wherever you saved the zip files originally). Normally you would do this by typing cd Downloads/ and pressing Enter.
7. Make the install.command file that appeared in step 5 executable by typing chmod +x install.command and pressing Enter.
8. Run the file by typing ./install.command
   1. If the program immediately quits, saying that it couldn’t find a Kobo eReader volume, try unplugging and replugging the device and tapping Connect once again.
9. When a privacy prompt comes up, asking if Terminal (or your terminal app of choice) should be allowed to connect to removeable volumes, click Allow.
10. On the screen a list of available packages to install on your Kobo device will appear. Type the number corresponding to your desired package and then press Enter. Normally it is 0.
11. After the installer completes, from Finder click the eject icon beside the volume for your Kobo eReader.

Once the device is successfully ejected, your Kobo eReader will start importing content and then display on the screen Updating… with some monospace text on the bottom of the screen. Let it do its thing until it once again shows you your Kobo home screen. It will reboot a few times while doing this.

You can disconnect the cable from your eReader at this point.

Once the install is finished, you will have a new entry in your bottom navigation bar with the label NickelMenu. Tap this and then tap KOReader to open the KOReader software. You will be prompted with the first-run guide. Go through that guide at your own pace. At the end, tap File Browser

Configuration

Now that KOReader is installed and running on your eReader, we’ll need to do a little prep and then we’ll be able to configure Wallabag within KOReader.

API Credentials

To set up Wallabag in any app or plugin, you’ll need to configure some client API credentials in your Wallabag account.

1. Navigate to your Wallabag server in a web browser on your computer

2. Open the KOReader menu by tapping on the word KOReader at the top of the screen.

3. Tap the wrench + screwdriver icon

4. Tap Wallabag

5. Tap Settings

6. Tap Configure Wallabag server

7. Type in the full URL for your Wallabag server (including https://)

8. Navigate to your Wallabag server in a web browser on your computer.

9. Once logged in, at the top right of the page, click your profile icon then select API clients management.

10. Click on CREATE A NEW CLIENT.

11. In the client name field, type Wallabag Kobo Plugin then click CREATE A NEW CLIENT.

12. Leave this page open for now. We’ll come back in a later step.

KOReader initial setup

Going back to your eReader, you should still be on the KOReader file browser.

1. In the File Browser, navigate up one folder by tapping ↑ ../.
2. Tap the + icon at the top right then in the pop up menu tap New folder.
3. Type wallabag and click Create
4. Tap on the text that says KOReader at the top to open the top menu.
5. Tap on the wrench + screwdriver icon.
6. In the menu options, tap Wallabag > Settings > Configure Wallabag server.
7. In the Server URL field enter the URL for your Wallabag instance including the https:// portion (eg: https://wallabag.it).
8. Tap Apply
9. Tap Set download folder.
10. Tap ↑ ../
11. Using the arrows at the bottom of the screen to show the wallabag folder and long-press the folder.
12. Tap Choose to set this folder as the Wallabag plugin folder.
13. Plug the device into your computer once again, then tap Share on the Kobo screen.

Configuration of Wallabag creds

1. In Finder on your computer, navigate to the Kobo eReader’s volume. (Mine was called KOBOeReader) and was shown in the Locations section.
2. Navigate to the following location within the Kobo volume: .adds/koreader/settings
   1. If you do not see the .adds folder, press Command+Shift+Period to show hidden folders.
3. Open the wallabag.lua file with a plaintext editor like Text Editor or Visual Studio Code.
4. Going back to your web browser, copy the client ID and secret into the corresponding sections within the wallabag.lua file.
5. In the file, also enter your Wallabag username and password.
6. Save the file and then eject the eReader using Finder. Below is similar to what your file should look like at the end.

return {
    ["wallabag"] = {
        ["articles_per_sync"] = 30,
        ["download_queue"] = {},
        ["filter_tag"] = "",
        ["ignore_tags"] = "",
        ["is_archiving_deleted"] = true,
        ["is_auto_delete"] = false,
        ["is_delete_finished"] = true,
        ["is_delete_read"] = false,
        ["is_sync_remote_delete"] = false,
        ["remove_finished_from_history"] = false,
        ["server_url"] = "https://wallabag.it",
        ["client_id"] = "jiwoefjege9r8h3thuiwghprpshgr_4tu3",
        ["client_secret"] = "fjieogjres9p8runiwt4ngroshr",
        ["username"] = "jdoe",
        ["password"] = "Sup3rS3cr3tP455w0rd",
        ["directory"] = "/mnt/onboard/.adds/koreader/wallabag",
    },
}

Connecting to Wallabag

Now that your Wallabag account is configured in KOReader, you should be able to retrieve articles.

To do so:

1. From the KOReader file browser, tap on KOReader to show the top menu.
2. Tap the wrench + screwdriver icon.
3. Tap Wallabag > Retrieve new articles from server.
4. Tap Turn on to turn on Wi-Fi and download articles. If you have a lot of articles unread, this will take a while to finish.
5. Once done, navigate back to the Wallabag plugin menu.
6. Tap Go to download folder

You will now see a list of the articles saved in your Wallabag account. They will have been converted to ePub files. Tap on one of them to read the article.

Conclusion

While this process seems a little involved, after doing it the first time, it seems a lot easier. So if you mess up halfway through, don’t be afraid to start over.

I’m extremely satisfied with how stable this has seemed to be over the past 2 weeks since I set it up.

While writing this guide I did, however, manage to force factory reset my Kobo eReader. Turns out that if the device finds itself in an unusable state, that’s the default behaviour. Neat!

If you have any questions about the guide above, feel free to reach out to me at [email protected] or on Mastodon @[email protected].