Install KOReader on a Tolino device (Vision 5)

koreader_on_tolino.md

Install KOReader on a Tolino Device

Tolino Debug Menu codes

For KOReader (or any other APK) to be installed on a Tolino device, the debug menu has to be enabled:

• if the tolino is on system version 14, search for code 124816 source
• if the tolino is on system version 15, search for code 1123581321 source
• if the tolino is on system version 16, search for code 112358132fb source

Note: "searching" as in the search for books on the tolino itself (the magnifying glass in the top bar)

Enable Debug-Menu Settings

Once in the Debug Menu, do the following things (may be named differently based on software version):

• Change the Environment to prod (debuggable) (optional)
• Change usb debugging to be enabled (enables ADB)
• if not wanting to ever put the debug code ever in again, enable show debug dialog quick access button (the button can be found in the search when not having put in anything yet)

Additional Notes about the debug menu:

• On a separate page the AOSP Settings can be accessed, through which WIFI, APPs and Developer settings can be accessed (like a normal phone)

Note: the pages in the Debug Menu can be switched by swiping the direction you want or clicking either < or > in the top of the dialog

Install

Install the APK through the Debug menu

When wanting to install the KOReader APK without ADB, then follow these steps:

• connect your tolino with your PC
• put the koreader (or any other apk) directly in the root directory for the tolino device (make sure the file end in .apk)
• switch the page in the debug menu until seeing Next, Install & Uninstall buttons
• select the APK you want to install with Next if not already selected
• install the APK with Install

Note: The install most likely will say Well, that did not work! Wrong apk?, but the app will still be installed, though the installed app may not be accessable without a launcher. (after installing the launcher, reboot the device for the Select launcher prompt)

Install through ADB

When wanting to install the KOReader APK through ADB, then follow these steps:

• ensure you have ADB installed on your PC
• connect your tolino with your PC
• run adb devices to check that the tolino is visible
• if any Allow this device dialog shows up on the tolino, accept it
• run adb install ./koreader.apk (replace ./koreader.apk with the path to the APK)
• wait for the command to finish and KOReader is installed

Tolino System Updates while KOReader is installed

Due to how Tolino is set-up (at least in Vision 5), there are 2 important partitions:

• System, ~500mb - stores the system and extra apps
• Data, ~5GB (on a Vision 5)

Tolino's base system consumes ~200mb and update packages are commonly ~100-170mb only are getting downloaded to the system partition, but this can get close to the limit already, but with KOReader installed and unpacked which is around ~40mb apk size and ~100mb unpackaged extra size, this can result in too low space for a update, so the workaround is to Clean Data of KOReader App before installing. This will not delete any configuration or books (with default paths) and will only delete the unpacked files from KOReader.

Extra Notes

• it is recommended to install a separate APK for a Home Screen, because KOReader itself is not a Home Screen and Tolino does not start other apps, so the only other way would be through ADB
• it is recommended to install a separate APK for Buttons, because the tolino system does not have the android navigation buttons enabled (and can also not be done through settings on system 15)
• F-Droid could once also be installed on the tolino as a APK, but currently (September 2022) it seems like F-Droid upgraded the version requirement and so cannot be installed on the android 4.4 versions anymore that tolino (Vision 5 and below) use

Bricked System

In case there should ever be a bricked tolino, you can go to https://mytolino.de/software-updates-tolino-ereader/ and download the version for your device and fully reset your system through recovery.

The steps would be as follows:

• shutdown your tolino while having it connect to a PC OR use adb reboot recovery
• run watch -n 1 adb devices in a terminal on your PC (or run adb devices manually until a device shows up)
• hold the POWER-button on the Tolino device until the command from watch (or manual commands) show a device in recovery
• if the output should not show anything related to recovery or the device should start-up normally, re-try from step 1
• run adb sideload ./path/to/update.zip
• wait for it to finish and reboot the device (for example with adb reboot)

Note: the USB has to be connected while shutting down, because otherwise the device will start itself up again on connection (like it unlocks / starts the lockscreen just by plugging it into power)

personal_notes.md

The guide above is meant to be generally generic, and in this file i will provide some things i had done for myself:

Extra Apps

As the extra apps i have used:

• for a Home Screen: SmartLauncher
• for the buttons: ButtionSavior (non root)

Both of those extra apps can be found in this allesebook blog post (or this direct download link), they are under the directory 3_adb named z_smartlauncher.apk and z_button.apk respectively.

Alternatively for the Vision 6 (and other android 8+ based devices) Simple EInk launcher should work, which can be found in this allesebook blogpost (or direct download) und the directory c_adb named z_simple.ink.launcher.1.2.apk. (this package is for the Vision 6 and i have not tested it on a Vision 5!)

ART runtime

Personally i have also enabled the runtime ART in developer-settings and think the performance is better than before, though i dont have any comparison.
Note that switching to ART will reboot the device (or at least require a reboot) and the next boot can take very long, for me it took ~30 minutes.

Should it be rooted?

Rooting is also possible (at least adbd rooting), though it requires a custom adb and i have personally only used it for debugging and would not recommend to go through the hassle.

Extra Notes

I had also wrote the guide for users wanting to customize their tolino without having to scavenge forums (especially when most are german) and outdated information, so i tried to include the most important information for various versions and devices.

If there should be any questions or outdated information, i will try to keep this updated, though i only have a Vision 5 and it seems unlikely to change much anymore, seeing that a Vision 6 is released with a upgraded system.

@hasezoey I tried both of them, but neither of them worked. When I am using the 32bit one it tells me something like “Version downgrade failed” and on the 64bit the message from the upper comment.

@hasezoey I tried both of them, but neither of them worked. When I am using the 32bit one it tells me something like “Version downgrade failed” and on the 64bit the message from the upper comment.

Please check if the KoReader app already appears in the android settings under installed apps, if yes, uninstall it, then try installing the 32bit one.

Oh wow yeah that worked… thank you!
And how can I start it now without a launcher? Is there an adb command for that?

And how can I start it now without a launcher? Is there an adb command for that?

there is one, but i recommend you add a launcher, because if the app crashes (which could happen) or just hangs or you need to restart your device, you will have to somehow restart the app

# inside adb shell
am start -n org.koreader.launcher/org.koreader.launcher.MainActivity

Note: i have not tested this command and assembled it from what i found about koreader online

Do you maybe have an Link to an tutorial on how to install a Launcher?
I found this one http://retinal.dehy.de/docs/doku.php?id=technotes:tolino_epos
Can you recommend that or an other?

I found this one http://retinal.dehy.de/docs/doku.php?id=technotes:tolino_epos

you could use nova launcher, personally i currently use smartlauncher(but i cannot find the download / blog post anymore from where i got it), now quickly searching for that blog post lead me to allesebook blog post using simple eink launcher, which you could also try. (or direct download, go to c_adb and look for file z_simple.ink.launcher.1.2.apk or build it yourself)

Note: the mentioned allesebook blog post is about rooting the device, but that is not necessary to just install the launcher (at least on tolino vision 5)

EDIT: i have now found the blog post again (direct download), path 3_adb -> z_smartlauncher.apk

Ah alright, it just needed to be installed like KOReader, thank you very much!

Would this work on a Tolino Page 2 ? I dont wanna risk my device by just trying it out.
@hasezoey

@ElryWeeb i cant verify as i only have a Tolino Vision 5, but from my reading the Page 2 runs the same software, so the codes should work and the app installs too:

(context: all of the listed devices have the same firmware)
source

PS: though note that i am still running my tolino with firmware 15, as i had no reason to upgrade yet (to my knowledge firmware 16 on the vision 5 basically only updates the app, not the system)

Well im in the debug and have the apks in the root (launcher and koreader, but it says "Well, that did not work! Wrong apk?" and idk what to do now.

@ElryWeeb i cant verify as i only have a Tolino Vision 5, but from my reading the Page 2 runs the same software, so the codes should work and the app installs too:

(context: all of the listed devices have the same firmware) source

PS: though note that i am still running my tolino with firmware 15, as i had no reason to upgrade yet (to my knowledge firmware 16 on the vision 5 basically only updates the app, not the system)

Nevermind it installed but threw an error for no reason

Hi. I managed to get the koreader-android-arm-v2024.03.1.apk. on my tolino vision5 (FW 16.1)
I too get the message "well, that did not work! wrong apk?" during installation.
in the debug options, if I go to "open aosp settings" , and then to Apps, I do see the KOReader as the only app, but I don't know if it is properly installed or how to use/activate it ? I did (manually) restart the tolino after this, no difference

@ercoodeperco it is likely installed, but to open it you either need to go through a adb command or install some kind of launcher

did this, got error on the Tolino while it ran : "an error hs occurred and all actions have been aborted. Please try again..."

but if I look at this screenshot , app seems active now ? (since button to Force Stop is highlighted). But apart from this, nothing changed on the tolino. Manual reboot after this : no effect.

I copied the smartlauncher.apk in the root dir , and restarted the tolino. This worked, and I can run KOReader now.
Thanks. Working (on firmware 16.2 now)

Just tested with a Tolino Vision 4 HD running 15.3.2 and KOReader (koreader-android-arm-v2024.04.apk) + SmartLauncher are working.
When installing the APKs I've got the same error as ercoo saying "Well, that did not work! Wrong apk?" but I've restarted once and I got the prompt of which launcher I wanted to use.
Thanks for the amazing guide!

Just to leave a token of my appreciation for this documentation. My only suggestion would be to add the smartlauncher link that is in the comments in the main text, next to your personal comments about it, because the later versions of the same software don't work, so it would save time to point straight to one that does work!
Thanks again!

Hey, not sure if OP is still active here, but help!

I did install a launcher, but after installing koreader-android-arm-v2024.07.apk I cant run it and get this message :( Any Ideas?

Using a Tolino Epos 1

@Lithopi likely already a known issue with no fix as of yet (aside from building your own before the bad commits / using a earlier release) koreader/koreader#12348

@hasezoey Ohhh thank you soo much for the helpful and quick reply! Its now working!! :)

Just a summary of what I have done . I followed this guide on my tolino shine3 .

• used password 112358132fb .
• Enabled debugging
• Installed adb on my linux
• adb install ~/Downloads/koreader-android-arm-v2024.11.apk
• adb install ~/Downloads/books/z_smartlauncher.apk
• adb install ~/Downloads/books/z_button.apk
• adb shell > type the command to start something
• Restart tolino (took a bit longer)
• Accept to use smart launcher
• Find Koreader
• Unresponsive. Restart menu didn't pop up for a while. somehow it did .Restarted.
• KOreader always seems to hang. Maybe it doesn't work on Shine . Give up.

Unresponsive. Restart menu didn't pop up for a while. somehow it did .Restarted.
KOreader always seems to hang. Maybe it doesn't work on Shine . Give up.

Koreader hangs on first start or on update for quite a while as it is decompressing modules it needs, for me it takes about 30 seconds, but it may take longer on other systems. You could try to adb logcat and see what it is doing (assuming you can get it to not go into USB Storage mode).

As for the restart menu, if something is unresponsive, the buttons app seems to still continue to work, so try to kill it via that.

Alternatively, try a older release of koreader as some newer ones had problems with android installs (and as a final alternative i could provide a build i did for myself, see this fork & branch)

I will try that out . Thanks a lot for your reply!

Hi, I installed KOReader on Tolino Vision 5, following your tutorial . I chose also chose an older version of KOReader which works fine (2024.04) - the newest one did not work. Or would you have a suggestion for a different version?

I also activated ART runtime and I use Simple-ink Launcher. However, I have a couple of issues. Maybe you have a solution for them?

1. When I put Tolino to sleep and open it again, sometimes I am completely on a different page (e.g. on the end of a book, or ten pages somewhere else). Could it be that buttons work partially even in the sleep mode? Could I do something with this? I use a magnetic cover so maybe an issue here?
2. Sometimes buttons for page turning stop working and I have to restart KOReader to make them work again.
3. The system is rather unstable, apps crash and sometimes Tolino completely freezes and I have to do hard reset. Did you encounter this as well? Any suggestions? Otherwise, I quite enjoy KOReader on Tolino Vision. It is definitely much quicker than the default application.

Thank you very much in advance.
 

I chose also chose an older version of KOReader which works fine (2024.04) - the newest one did not work. Or would you have a suggestion for a different version?

Kinda sad to hear that newer koreader versions still dont work, though i already had reported that 2024.11 does not work, but nightly do, try the nightly builds or build it yourself. (alternatively, i could also provide the apk i am using and have compiled myself, which is based on this branch).

When I put Tolino to sleep and open it again, sometimes I am completely on a different page (e.g. on the end of a book, or ten pages somewhere else)

I have never (from what i recall) encountered this, when this happens, does tapping / selecting text reset you to the correct page?

Sometimes buttons for page turning stop working and I have to restart KOReader to make them work again.

I also have not encountered this, for me it consistently works (though in the newer versions of koreader you have to use event_map.lua, ie custom keybindings to make them work in the first place, unless you use a manual compile which includes this patch again)

Could it be that buttons work partially even in the sleep mode? Could I do something with this? I use a magnetic cover so maybe an issue here?

At least while the tolino is in sleep (lockscreen), to my knowledge, no button press gets passed, though i also dont have a cover or anything for my tolino.
This might be unrelated, but note that (at least my tolino) unlocks when it gets / loses a usb connection.

The system is rather unstable, apps crash and sometimes Tolino completely freezes and I have to do hard reset

I dont recall having a completely unstable system, though i still am on 15.x firmware and dont intend to upgrade. (specifically i am on 15.3.2).
Depending on what you mean, you might wanna look at the adb logcat output to figure out what the problem is.
Do you have Button Savior (or similar) installed, if yes does that freeze too?

Thank you very much for the reply. If you could provide the apk, I would be very grateful for that.

I am not sure then, what I have done wrong. Maybe it is because that I am on 16. firmware. I bought the device second hand and it was already there.

Maybe it is because that I am on 16. firmware. I bought the device second hand and it was already there.

You could try to factory reset or completely replace the firmware again (by following the Bricked System instructions), by replacing the firmware you also unlock (or at least be able to choose) which store to use for the tolino app. Replacing the firmware is what i had done as, if i recall correctly, i had bricked mine, or wanted a clean slate again after messing around. (This was before i wrote those instructions)

If you could provide the apk, I would be very grateful for that.

koreader-android-arm-v2024.11-72-gf883a66e4_2024-12-16.apk, uploaded to drive as github does not support apk or zip in comments. Please note that i might not keep this file around forever.
This build is made using ./kodev release android-arm in flatview-v2024.11-further branch on linux and signed with a debug key.
EDIT: Note that to install this version, you will first have to uninstall the previous koreader app you had, this is required as this build uses a different signing key than the official version.
This build / branch differentiates itself from the main koreader tree by being based on a commit which actually does run on my tolino, has the event_map.lua patch backed-in again and includes the Flatview POC which i personally like. (before it was available as a user-patch)
Note on using the Flatview POC, koreader has to know metadata from the added files, which it does not (to my knowledge) parse automatically, so you will have to run Extract and cache book information (in the file browser the + in the top Right) every time you added (or removed) books. (as for the options it presents, i will leave to your judgement on what you wanna do and where your books are placed)
PS: if you encounter bugs with this version, please re-test in a newer version first before trying to report them.

Alternatively, again, if you want a clean build of koreader, try a nightly version.

Hi @hasezoey,
could I tap your impressive Tolino knowledge once again? I’m now running the correct version that you mentioned above in the thread on my Tolino Epos, and I LOVE it, but I’m having a small issue: the light colour adjustment doesn’t work on Koreader, although it does using the preinstalled Tolino software. Is there any known fix for this?

Thanks so much!

Tolino Epos
the light colour adjustment doesn’t work on Koreader, although it does using the preinstalled Tolino software. Is there any known fix for this?

This could be some things, to narrow it down please read koreader/koreader#8482 (comment) and provide the Compatibility test result data (ie Device info)
TL;DR: To test drivers go to "Tools" -> "More Tools" -> "Developer options" -> "Start compatibility test" in KOReader FM.
(Also for simplicity, please provide the full model name as it is marketed, ie Tolino Vision 5)

If it does not already say [TEST LIGHTS] Tolino Ntx (where [] is a button), then try the dropdown on Right side (the arrow down) and select Tolino Ntx and try it, if it does not work, maybe try some others (though i dont expect others than Tolino to actually work)

you might want to add this link for tap2flip support in koreader: koreader/koreader#11720