Kobo eReader development notes


(note: the information on this page assumes you have a kobo set up with nickelmenu, or another application launcher. If not, I suggest NickelMenu. If you haven't got anything custom currently installed on your kobo, I suggest the one-click installers for NickelMenu and koreader, which set everything up automatically. KOReader is also well worth having, it is better than the stock reading app in basically every way. All of these notes are related to my kobo aura HD. Other kobo models may behave differently. This page will continue to update as I learn more about kobo development.)

NickelMenu thread & download (launcher only)
One click installers for koreader and nickelmenu (full installers)

Setting up a go development environment for kobo

(assumes you're already set up to develop go. If not, you probably should start with something more normal than the kobo)

To develop anything useful in go for kobo devices, you're going to need CGO and a C toolchain targeting the kobo (because drawing to the display requires a C library). Install koxtoolchain (instructions are in the README) and then build your go programs with these envronment variables:


I put these in a makefile for convenience.

koxtoolchain github

Useful go libraries for the kobo

Go wrapper for FBInk (drawing on kobo)
Kobo input in go (this library is meh, I might fork it and improve it)

fbink doesn't provide any drawing primitives. you can use a library like gg to draw frames and then display them with fbink.


Where to install applications to

I think you can probably put executables anywhere in the filesystem and run them, but the convention seems to be to place them in /mnt/onboard/.adds/[app name]/[content].

Running your application outside of nickel

If you want to build software that runs outside of nickel (aka, any substantive application, rather than just a small utility) you will quickly find that nickel (the stock reader application) likes to eat up inputs, clobber the framebuffer, and generally be a pain in the ass. The easiest way to deal with this is simply kill nickel and then restart it when your custom application exists.

Killing nickel is easy. I just wrote a shell script which I put alongside my application that kills nickel, runs my app, then restarts nickel on exit:

file: /mnt/onboard/.adds/gemini/run.sh
killall -TERM nickel hindenburg sickel fickel 2>/dev/null
/mnt/onboard/.adds/gemini/kobo-gemini # replace with your app
exec /mnt/onboard/.adds/gemini/nickel.sh

The nickel.sh file restarts nickel. It comes from koreader.


Adding items to NickelMenu

The application launcher I use on my kobo is NickelMenu. It's easy to add your own custom items to it. Just add the line:

file: /mnt/onboard/.adds/nm/config
menu_item : main : [label] :cmd_spawn :exec [path to your application]

Activating a kobo without an account

I don't want to use kobo's online services, so I use this trick on new and reset kobos to avoid registering an account. On a new or reset kobo, choose "setup via Computer". Then, mount the kobo and run this command:

echo "insert into user (UserID, UserKey)  values (1, 'empty')" | sqlite3 [YOUR KOBO MOUNT POINT]/.kobo/KoboReader.sqlite

Then, Unmount and unplug your kobo. On an aura HD this is also the time I do a firmware update.

Enabling nickel developer mode

You can enable nickel's developer mode on a kobo by tapping the search icon and searching "devmodeon". It will add the developer options menu to "about device" in settings and, more importantly, lets you telnet into your kobo while nickel is running. you can login as `root`. NOTE: MAKE SURE TO DISABLE THIS IF YOU ARE ON A PUBLIC NETWORK! OPEN ROOT SSH IS A HUGE SECURITY ISSUE! To disable developer mode, search in the search box for "devmodeoff".

SSH access

You can get SSH access into your kobo (which is very useful while debugging) by installing NiLuJe's KoboStuff package. Download it and place the KoboRoot.tgz file in /.kobo/ on your kobo over USB. Then unplug your kobo, let it update, and connect in with `ssh root@[kobo IP address]`. THIS IS PASSWORDLESS! DON'T CONNECT TO A PUBLIC NETWORK WITH IT ENABLED!

The benefits of this over the devmode's built in setting is that it persists when nickel is killed, which is incredibly useful for debugging your own applications.


SSH over USB

You can also connect to the kobo over SSH over USB, for faster and more stable access. To do this, with KoboStuff installed, add an option to nickelmenu the same way you would for an app:

menu_item : main : USBNet Toggle :cmd_spawn :exec /usr/local/stuff/bin/usbnet-toggle.sh 

Then, tap this menu item, you should get a message on your display saying that it has been switched from USBMS to USBNet.

On your computer you will now need to configure the USB network. I can only offer the steps for a linux machine with NetworkManager:

1. In networkmanager, a new connection should show up when you enable USBNet on the kobo. Open it up to edit.

2. Set ipv6 mode to disabled and ipv4 mode to manual. Add the ipv4 address

3. in a terminal, connect via ssh to

4. You should have SSH over USB on your kobo!

NOTE: this can be finnicky and didn't work for me the first time, but now does.

More resources

If anything isn't covered here or you have any questions, go to the kobo developer's forums on mobileread. The community there is helpful and there are more resources than you can imagine.

Kobo Developer's Corner (forum)