NickelDBus

Introduction

NickelDBus is a mod for Kobo e-readers. Heavily inspired by NickelMenu, it allows developers to perform many of the same actions as NickelMenu, but from scripts or programs, instead of from the UI.

As well as the ability to trigger actions, NickelDBus also allows you to wait on a limited selection of signals. Such signals include knowing when the content import process has completed, or whether WiFi has connected, among others.

This is all achieved through the magic of d-bus. NickelDBus registers itself on the system bus.

You can follow the development of NickelDBus at the GitHub repository.

Installation

Installing NickelDBus is simple. Simply go to the latest release page and download the KoboRoot.tgz file.

Copy the downloaded KoboRoot.tgz to the .kobo directory on the root of your kobo when plugged into USB. Eject/disconnect your Kobo, and it will automatically install itself.

There is no need to configure anything after installation.

Note: NickelDBus should survive factory resets.

Note: to check what version of NickelDBus you have installed, open the file `.adds/nickeldbus` in a text editor. Applications should use the provided ndbVersion method to get the current NickelDBus version instead of parsing this file.

Upgrading

To upgrade NickelDBus, simply follow the same procedure as installing it.

Uninstallation

If you ever want to remove NickelDBus, simply connect your Kobo to your computer over USB and delete the file called nickeldbus in the .adds directory.

Then disconnect your Kobo, and reboot. NickelDBus should now be removed.

Developer Documentation

Note: Please do not directly install NickelDBus when installing your own application. If you wish to include NickelDBus as a convenience for your users, consider performing an install or upgrade (never downgrade) during your application start-up process.

NickelDBus presents itself on the d-bus system bus. It has an interface of com.github.shermp.nickeldbus and a path of /nickeldbus.

To interact with NickelDBus, you can use language bindings for your favourite programming language. Most if not all languages have bindings available.

Usage

CLI Tools

Shell script users may use the standard dbus-send and dbus-monitor tools. Programs like qdbus and gdbus are also available.

Alternatively, NickelDBus installs a small tool called qndb if you wish to use it. qndb allows you to call a method, or wait for a signal, or call a method then wait for a signal.

qndb

The qndb usage is as follows:

Usage: qndb [options] [args...]
Qt CLI for NickelDBus

Options:
  -h, --help                  Displays this help.
  -v, --version               Displays version information.
  -s, --signal <signal name>  Wait for signal, and prints its output, if any.
  -t, --timeout <timeout ms>  Signal timeout in milliseconds.
  -m, --method <method name>  Method to invoke.
  -a, --api                   Print API usage

Arguments:
 arguments                   Arguments to pass to method. Have no affect when
                             a method is not set.

And here are a few examples:

Print the current NickelDBus version

qndb -m ndbVersion

Show a toast on-screen for 3 seconds, with message 'Hello World!':

qndb -m mwcToast 3000 "Hello World"

Trigger library rescan, and wait for content import to complete, with a 30 second timeout:

qndb -t 30000 -s pfmDoneProcessing -m pfmRescanBooksFull

Note: Even though qndb may time out, the content import process will not be aborted.

Language Bindings

Most languages will have d-bus bindings available. NickelDBus and qndb were written in Qt using QtDBus.

API Documentation

The API is documented here. It is Qt based documentation, but it should be easy to determine what's needed for other languages or CLI tools.

Compiling NickelDBus

NickelDBus is a Qt and C++ based project. It was designed to be used with NickelTC. As such, the Makefile expects that to be available.

To build everything from scratch, run:

make clean && make && make cli && make koboroot

That will compile the library, qndb and package it up into a KoboRoot.tgz ready to be installed onto a Kobo.

To make this documentation, run

make doc

If you are developing NickelDBus, you will probably want to run

make interface

if you haven't already run make so that you have the auto-generated adapter and proxy code and header files.