Hacking and development notes

Useful notes for tweaking or debugging okreader installs.

Resetting your Kobo

1. Hold down the power switch for about thirty seconds to turn your Kobo off.
2. Wait about five seconds
3. Slide the powerswitch again to boot the Kobo.

If your kobo hasn't hung, you may also be able to use the reboot command in the terminal emulator, or over SSH.

Don't use the "reset" switch (the small hole on the bottom of the kobo, near the micro USB port). On at least the Kobo Glo, this will corrupt your okreader install!

Setting a root password:

In the built-in terminal editor (tools menu, second page), enter these commands, substitution yourpasswordhere with your password of choice:

echo 'root:yourpasswordhere' | chpasswd
reboot

The Kobo will take about 30 seconds or so to restart (watch for the light near the powerswitch to cycle).

Once set, the password will be retained across reboots.

Connect to your Kobo over SSH:

1. Set a root password as above.
2. Turn on WiFi (settings menu, network, check WiFi connection).
3. Obtain your IP address (settings menu, network, network info; or run ifconfig in the terminal emulator)
4. ssh root@kobo.ip.address.here

Be aware that the Kobo (or just its wlan card?) will go into powersave after a few minutes of no keypresses on its screen, at which point your SSH connection will drop.

Run koreader with debugging enabled

You need to be connected over SSH to do this, as the terminal emulator is part of koreader.

1. Set a root password and connect via SSH (as above)
2. You need to kill the existing koreader instance, and the okreader.sh shell script that spawns it.
3. Kill okreader.sh first, as it will otherwise re-spawn koreader so long as it is running:
   1. ps aux | grep okreader.sh to find the PID of the bash instance running the script
   2. kill <PID> to terminate that process.
4. Now kill koreader itself. koreader is a Lua program run by the luajit executable. So:
   1. ps aux | grep luajit, then kill all PIDs for LUA JIT processes running ./reader.lua:
   2. kill <PID>
5. At this point, the existing KOReader instance is dead, and your Kobo's touchscreen should be non-responsive. To start a new instance, with debugging enabled:
   1. cd /opt/koreader
   2. ./reader.lua -d
6. You should see some output as koreader starts up, and be left with a working touchscreen.

When finished debugging, you can Ctrl+C to stop koreader, and use the reboot command to restart your kobo.

Internal storage partition shows as unformatted on Windows when connecting over USB

Edit /etc/rc.local, and change the line that reads

modprobe g_file_storage file=$DATA_PART

to

modprobe g_file_storage file=$DATA_PART removable=y

Fixing the dictionary viewer

Version a9bf918_build and older builds are missing a library necessary to use Koreader's dictionary viewer. If you set up SSH (see above), you can install it using Apt like so:

apt-get install -y libglib2.0-0

This may also work from within the terminal emulator, if you have wifi connected.

If you receive an error about insufficient disk space, on Kobo Glo devices (and perhaps others) you can remove the (unused) parition 2, and expand partition 1 to fill the remaining space. (Onboard storage for books is in partition 3, i.e. /dev/mmcblk1p3).

This may be fixed in a future okreader release; see issue #11.

Storing StarDict dictionaries on the SD card

Over SSH, or in the terminal editor:

1. Create a folder on the sdcard: mkdir /mnt/external/dict
2. Remove the existing (empty) folder from the root filesystem: rm /opt/koreader/data/dict
3. Create a symlink on the root fs to the folder on the sdcard: cd /opt/koreader/data && mklink -s /mnt/external/dict

If you don't use an external sdcard, you can substitute /mnt/nboard/dict in the commands above, and you'll be able to upload dictionaries over USB.

You may need to restart the Kobo after adding new dictionaries. Dictionaries can be tested using the "Dictionary lookup" command on koreader's search menu.bb