I just got a new Kobo ebook reader, a Kobo Clara HD. It's pretty similar to the Glo HD I had but which has unfortunately died after 5 years, even after trying to replace the battery.

  1. Quick hardware review
  2. Configuration hacks
    1. SD card replacement
    2. Registration bypass hack
    3. Install koreader
    4. Install syncthing
    5. Avoided tasks

Quick hardware review

This is a neat little device. It's very similar to the Glo HD, which is a bit disappointing: you'd think they would have improved on the design in the 5+ years since the Glo HD has come out.. It does have an "amber" night light which is nice, but the bezel is still not level with the display, and the device is still kind of on the thick side. A USB-C (instead of micro-USB) port would have been nice too.

But otherwise, it's pretty slick, and just works. And because the hardware design didn't change, I can still hack at it like a madman, which is really why I bought this thing in the first place.

Hopefully it will last longer than 5 years. Ebook readers should really last for decades, not years, but I guess that's too much to expect from our consumerist, suicidal, extinctionist society.

Configuration hacks

Here are the hacks I done on the device. I had done many more hacks on the Kobo Glo HD, but I decided to take a more streamlined, minimalist and, hopefully, easier for new users than the pile of hacks I was doing before (which I expand on at the end of the article).

SD card replacement

I replaced the SD card. The original card shipped with the Clara HD was 8GB which meant all my books actually fitted on the original, but just barely. The new card is 16GB.

Unfortunately, I did this procedure almost at the end of this guide (right before writing the syncthing scripts, below). Next time, that should be the first thing done so the original SD card acts as a pristine copy of the upstream firmware. So even though this seems like an invasive and difficult procedure, I actually do recommend you do it first.

The process is basically to:

  1. crack open the Kobo case (don't worry, it sounds awful but I've done it often)
  2. take the SD card out
  3. copy it over to a new, larger card (say on your computer)
  4. put the larger card in

This guide has all the details.

Registration bypass hack

This guide (from the same author!) has this awesome trick to bypass the annoying registration step. Basically:

  1. pretend you do not have wifi
  2. mount the device
  3. sqlite3 /media/.../KOBOeReader/.kobo/KoboReader.sqlite
  4. INSERT INTO user(UserID,UserKey) VALUES('1','');
  5. unmount the device

More details in the above guide, again.

Install koreader

My e-reader of choise is Koreader. It's just that great. I still don't find the general user interface (ie. the "file browswer") as intuitive as the builtin one, but the book reading just feels better. And anyways it's the easier way to get a shell on the device.

Follow those instructions, particularly the NickelMenu instructions (see also the NickelMenu home page). Yes, you need to install some other thing to start koreader, which doesn't start on its own. NickelMenu is the simplest and better integrated I have found.

You might also want to install some dictionnaries and configure SSH:

  1. mount USB
  2. drop your SSH public key in .../KOBOeReader/.adds/koreader/settings/SSH/authorized_keys
  3. unmount USB
  4. enable SSH in koreader (Gear -> Network -> SSH -> start SSH)

Note that ed25519 keys do not work: try an RSA key. This might be because koreader ships with dropbear (or an older version), but I haven't verified this.

Install syncthing

I use Syncthing to copy all my books into the device now. I was previously using Koreader's OPDS support with Calibre's web interface, but that was clunky and annoying, and I'd constantly have to copy books around. Now the entire collection is synchronized.

As a bonus, I can actually synchronise (and backup!) the koreader metadata, since it's stored next to the files. So in theory, this means I could use koreader from multiple devices and have my reading progress sync'd, but I haven't tested that feature just yet.

I chose Syncthing because it's simple, lightweight, supported on Linux and Android, and statically compiles by default which means it's easy to deploy on the Kobo.

Here is how I installed and started Syncthing at first:

  1. Download the latest version for ARM
  2. extract the archive
  3. copy the syncthing binary into .../KOBOeReader/.adds/
  4. login over SSH (see above on how to enable) with -p 2222 -l root
  5. create the following directory: ~/.config/syncthing/
  6. create the following configuration file, named config.xml:

    <configuration version="18">
        <gui enabled="true" tls="false" debugging="false">
            <address>0.0.0.0:8384</address>
        </gui>
    </configuration>
    
  7. copy a valid ca-certificates.crt file (say from your Linux desktop) into /etc/ssl/certs/ on the Kobo (otherwise syncthing cannot bootstrap discovery servers)
  8. launch syncthing over SSH: /mnt/onboard/.adds/syncthing

You should now be able to connect to the syncthing GUI through your web browser.

Immediately change the GUI admin user and password on the Settings: GUI tab.

Then, figure out how to start it. Here are your options:

  1. on boot (inittab or whatever). downside: power usage.
  2. on wifi (udev hacks). downside: unreliable (see wallabako).
  3. on demand (e.g. nickel menu, koreader terminal shortcuts). downside: kind of clunky in koreader, did not work in nickel menu.
  4. manually, through shell. downside: requires a shell, but then again we already have one through koreader?

What I have done is to write trivial shell scripts (in .../KOBOeReader/scripts) to start syncthing. The first is syncthing-start.sh:

#!/bin/sh

/mnt/onboard/.adds/syncthing serve &

Then syncthing-stop.sh:

#!/bin/sh

/usr/bin/pkill syncthing

This makes those scripts usable from the koreader file browser. Then the folder can be added to the folder shortcuts and a long-hold on the script will allow you to execute it.

Still have to figure out why the Nickel Menu script is not working, but it could simply reuse the above to simplify debugging. This is the script I ended up with, in .../KOBOeReader/.adds/nm/syncthing:

menu_item :main    :Syncthing (toggle)    :cmd_spawn         :exec /mnt/onboard/scripts/syncthing-stop.sh
  chain_success:skip:4
    chain_success                      :cmd_spawn          :exec /mnt/onboard/scripts/syncthing-start.sh
    chain_success                      :dbg_toast          :Started Syncthing server
    chain_failure                      :dbg_toast          :Error starting Syncthing server
    chain_always:skip:-1
  chain_success                        :dbg_toast          :Stopped Syncthing server
menu_item :main    :Syncthing (start)    :cmd_output         :exec /mnt/onboard/scripts/syncthing-start.sh
menu_item :main    :Syncthing (stop)    :cmd_output         :exec /mnt/onboard/scripts/syncthing-stop.sh

It's unclear why this doesn't work: I only get "Error starting Syncthing server" for the toggle, and no output for the (start) action. In either case, syncthing doesn't actually start.

Update: according to a reader (thanks mmmaxwwwell!), this should work better:

menu_item :main :Syncthing Start :cmd_spawn :quiet:/mnt/onboard/scripts/syncthing-start.sh
chain_success :dbg_toast :Started Syncthing
menu_item :main :Syncthing Stop :cmd_spawn :quiet:/mnt/onboard/scripts/syncthing-stop.sh
chain_success :dbg_toast :Stopped Syncthing

... but I haven't tested this myself.

Avoided tasks

This list wouldn't be complete without listing more explicitly the stuff I have done before on the Kobo Glo HD and which I have deliberately decided not to do here because my time is precious:

Now maybe I'll have time to actually read a book...

thanks for howto! and suggestions

Thanks a lot for this writeup! I was able to get this all working. Here are some comments of things you might adjust:

  • for SSH using an ed25519 key didn't work, but rsa did. I guess a dropbear restriction?
  • on syncthing step 5/6 the file should be named config.xml in that dir
  • step 7 maybe suggest grabbing the ca-certificates.crt from their linux desktop system and scp'ing it over
  • on step 4 maybe include the ssh command with the "-p 2222 -l root" to be more clear
  • for syncthing GUI change "change the admin password" to "change the GUI admin user and password on the Settings->GUI tab"
  • maybe some hints on how to setup syncthing(or a link) would be helpful. Also do you recommend having syncthing sync /mnt/onboard directly or another dir?
Comment by taggart
answers

Thanks for the corrections! I tried to add them to the post.

You're right that the syncthing shares setup itself could use some help. I share all of /mnt/onboard and use the following .stignore:

.git
.adds
.adobe-digital-editions
.kobo-images
.kobo

I also have that in a stignore file instead of .stignore and put #include stignore in the .stignore itself, as syncthing ignores the .stignore file, which I find annoying.

Comment by anarcat
Nickel menu working

Hello there. I arrived here from the mobileread forum thread.

I've managed to get the nickelmenu options working with a script similar to what was posted in the thread

Here is what I have:

  1. Syncthing binary is at /mnt/onboard/.adds/syncthing/

  2. Start script: /mnt/onboard/.adds/start_syncthing.sh

     #!/bin/sh
     rm /mnt/onboard/syncthing.log
     ifconfig lo | grep -q addr:127.0.0.1 || ifconfig lo 127.0.0.1
     /mnt/onboard/.adds/syncthing -no-browser -home=/root/.syncthing -logfile=/mnt/onboard/syncthing.log &>/dev/null &
    
  3. Stop script: /mnt/onboard/.adds/stop_syncthing.sh

     #!/bin/sh
     killall -15 syncthing
    
  4. Nickel menu config: /mnt/onboard/.adds/nm/syncthing

     menu_item:main:start syncthing:cmd_spawn:quiet:exec /mnt/onboard/.adds/start_syncthing.sh
     menu_item:main:stop syncthing:cmd_spawn:quiet:exec /mnt/onboard/.adds/stop_syncthing.sh
    

I just copied the same script used for koreader and changed the shell scripts at the end. By the way, you need to add -gui-address to the startup command if you want to access the web interface on you PC.

Since I just use koreader all the time, the Nickel menu item isn't useful to me, but it may help someone here.

Comment by joseph channel
works on Kobo Libra 2 too
just wanted to confirm that these instructions worked like a charm on Kobo Libra 2 (including updated menu entries). Thanks!
Comment by skrobul
Comments on this page are closed.
Created . Edited .