About

NickelMenu adds custom menu items to various menus in Kobo's eReader software. It works on all recent firmware versions, and persists between firmware upgrades. There are many built-in actions for controlling Nickel and for running external software.

NickelMenu requires firmware 4.6+ to work, and has been fully tested on 4.20.14622 - 4.24.15672. It is safe to install it on any firmware version, as it has a lot of error checking and a failsafe mechanism which will automatically uninstall it as a last resort.

If you are using the main menu on firmware 4.23.15505+, you will need NickelMenu v0.3.2 or newer.

Screenshots

Sample menu items in the main NickelMenu menu on firmware 4.23.15505+. Sample menu items in the main NickelMenu menu on firmware 4.6+. The library menu configured with custom FTP and Import Books menu items. The reader menu configured with many useful items. The full-screen browser on firmware 4.23.15505+ with custom Quit and Open Pop-Up menu items. Using NickelMenu with the KFMon generator to launch external applications on firmware 4.23.15505. The default main menu on 4.6+ with NickelMenu installed. The main menu on a different view on firmware 4.23.15505+.

Installation

  1. Connect your Kobo eReader to your computer over USB.
  2. Download KoboRoot.tgz (release notes) into KOBOeReader/.kobo. You may need to show hidden files to see the folder.
  3. Safely eject your eReader and wait for it to reboot.
  4. Ensure there is a new menu item in the top-left main menu entitled NickelMenu (it will appear in the bottom-right on firmware 4.23.15505+).
  5. Connect you Kobo eReader to your computer again and create a new file (of any type) named KOBOeReader/.adds/nm/config, and follow the instructions in KOBOeReader/.adds/nm/doc to configure NickelMenu.

Features

  • A built-in failsafe will automatically remove NickelMenu if any fatal error occurs, and will never result in an unbootable Kobo. Non-fatal errors will appear as a menu item with more details.
  • Multi-version compatibility (even for future versions).
  • Can add items to the main menu, reader menu, browser menu, and the library menu.
  • Many built-in actions:
    • Debug messages (dbg_syslog, dbg_error, dbg_msg, dbg_toast).
    • Nickel settings (nickel_setting:{toggle,enable,disable}:{invert,lockscreen,screenshots,force_wifi,auto_usb_gadget}).
    • Nickel browser with support for showing as a pop-up (e.g. for a reference site while reading) and adding custom CSS (nickel_browser:{modal:,}{ ,})
    • Nickel extras (nickel_extras:{unblock_it,sketch_pad,solitaire,sudoku,word_scramble}).
    • Nickel views (nickel_open:{discover:storefront,discover:wishlist,library:library,library:all,library:authors,library:series,library:shelves,library:pocket,library:dropbox,reading_life:reading_life,reading_life:stats,reading_life:awards,reading_life:words,store:overdrive,store:search}).
    • Nickel WiFi (nickel_wifi:{autoconnect,autoconnect_silent,enable,disable,toggle}).
    • Nickel orientation, even on devices without a sensor (nickel_orientation:{portrait,landscape,inverted_portrait,inverted_landscape,invert,swap}).
    • Other Nickel stuff (nickel_misc:{home,force_usb_connection,rescan_books,rescan_books_full}).
    • Gracefully exit Nickel (power:{shutdown,reboot,sleep})
    • Launch system commands and optionally display the output (cmd_spawn{,:quiet},cmd_output:timeout{,:quiet}).
    • KFMon (kfmon, kfmon_id).
  • The web_browser action has additional features such as opening a pop-up window, opening a custom URL instead of the homepage, or adding custom CSS styles to the webpages.
  • Action chaining (chain_{success,failure,always}).
  • Dynamically generated menu items (generator:kfmon).
  • Simple configuration format with support for multiple configuration files.
  • Configuration files and item generators will be updated instantly without a reboot.
  • Comprehensive logging to syslog (view over telnet or SSH with logread, or enable developer options and see the syslog files in KOBOeReader/.kobo).
  • No system files are ever touched directly, and no patching is required.

Troubleshooting/FAQ

I don't see any menu items in the main menu
Try re-installing NickelMenu. If it still doesn't appear, please reboot and post the contents of the syslog.
I rebooted, and NickelMenu suddenly disappeared
You probably triggered the failsafe (if you rebooted within 20 seconds after first turning it on).
I want to uninstall NickelMenu
Create a new file named KOBOeReader/.adds/nm/uninstall, then reboot your Kobo.
I want to update NickelMenu
Follow the installation process again. Your configuration files will be preserved.
When I press one of the actions, I get an error message about dlsym
Something has probably changed in your firmware version. Try updating NickelMenu, and if it still doesn't work, please post your current version and the action you are trying to use.
When I try to open a file in KOBOeReader/.adds/nm, I get asked what I want to open it with
Open it with a text editor, for example, Notepad, Notepad++, or Visual Studio Code.
When I open a configuration file, everything is jumbled in one long line
Open it with a different text editor which supports unix line breaks. If you are trying to view the documentation, it is also available online.
I need help writing a configuration file
There is an example configuration file in the documentation. If you still need help, feel free to post in this thread.
I found a bug in NickelMenu
Try re-installing NickelMenu. If that still doesn't work, please post your syslog, your configuration file, and a description of the issue in this thread or on GitHub.
I found a bug in Nickel (i.e. Kobo's reader itself)
Before you report it, first reboot and confirm the issue is still reproducible without using any menu items.
I would like to request a new feature
Please post it in this thread or open an issue on GitHub.
I receive an error message when trying to launch a KFMon action
Make sure the launcher name you specified is correct. It should look like action.png or something similar. Also, make sure you have installed the latest version of KFMon and try re-installing NickelMenu.
How do I configure NickelMenu
Read the instructions above again, and see the documentation.

Reporting Issues

If you still have a question or have found a bug in NickelMenu, you can open an issue on GitHub or post it to the thread on MobileRead. Please try upgrading to the latest version first. If you aren't sure whether you are on the latest version, re-install NickelMenu (your configuration files will be preserved).

Other Stuff

If you like NickelMenu, you may also be interested some of my other mods/tools:

  • kobofirmware: Direct links and notifications for firmware updates.
  • kepubify: A fast EPUB to KEPUB conversion tool.
  • dictutil: Custom dictionaries and tools to work with them.
  • NickelSeries: Adds support for series and subtitle metadata when sideloading books.

NickelMenu can also be used to launch alternative software for Kobo eReaders, including:

  • Vlasovsoft: A collection of apps including PBChess, a calculator, a file manager, and more.
  • KOReader: An alternative reader for e-ink devices.
  • Plato: Another alternative reader for e-ink devices.
  • KFMon: Anything compatible with KFMon can be launched directly through NickelMenu.

If you're interested in creating mods similar to NickelMenu and NickelSeries, you may be interested in:

  • NickelHook: The library which powers NickelMenu, NickelSeries, NickelDBus, and other mods which directly interact with Nickel.
  • NickelDBus: A mod by @shermp which exports the functionality of NickelMenu and more over DBus.