Kindle Touch Hacking

From MobileRead
Jump to: navigation, search

UNFORTUNATELY, THIS NOTICE SEEMS TO BE NECESSARY: This page is not a "cookbook", and it does NOT contain "recipes" that you should follow without thinking.


This page contains technical descriptions for a complex device. If you follow the procedures outlined below (especially the more technical ones), you should AT LEAST have a rough understanding of what you are doing, and be able to describe the expected result. If you don't know what to expect, then it's likely that you don't know what you are actually doing, so it might be better to refrain from doing it in the first place.


Abstract: The purpose of this page is to bring together, in a concise way, much of the information found in the Kindle Developer's Corner concerning the Kindle Touch (KT), regarding topics such as jailbreaks, modifications, and how to develop for the device.

This page will hopefully always be under construction. You are more than welcome to add valuable information that you find to be currently missing!

Contents

[edit] Jailbreak

The jailbreak itself does not yet allow you to do much. In fact, it only installs an additional "developer" key on the device, allowing for the installation of additional packages via the Kindle's own update mechanism.

Jailbreaking the KT is extremely easy to do.

[edit] jailbreak.mp3 method

This method works on Kindle Touch version 5.0.0 and 5.0.1. For newer firmware versions, see below.

  1. Download and unzip the jailbreak. (Mirror)
  2. Follow the instructions in the README file.

Note: if you want, you can directly install the usbnetwork package (see below) together with the jailbreak, by copying update_simple_usbnet_1.1_install.bin to the top-level folder of the device before applying the jailbreak.

[edit] data.tar.gz method

This method works on Kindle Touch version 5.0.0 through 5.1.0.

Depending on your firmware version, it may be easier (or more complicated). Carefully read all of the instructions below, and follow them only after you have read everything and are sure what to do.

IMPORTANT: The "universal" method works on all firmware versions (at the time of writing). This method takes a bit of time, but is guaranteed to succeed. The "simple" method only works on older firmware versions (5.0.0 - 5.0.4). If in doubt, follow the "universal" method!

Universal method

  1. Download and unzip the jailbreak.
  2. Plug in the Kindle and copy data.tar.gz to the Kindle’s USB drive’s root
  3. Create a blank text file named ENABLE_DIAGS (note: no file extension!, i.e., it's not ENABLE_DIAGS.txt or so) and save it directly on the Kindle's USB drive's root (not in a subdirectory)
  4. Create the directory diagnostic_logs in the Kindle USB drive root directory
  5. Create a blank text file named device_info.xml inside that diagnostic_logs directory
  6. Safely remove the Kindle from USB and restart it (Menu -> Settings -> Menu -> Restart)
  7. Once the device restarts into diagnostics mode, select "D) Exit, Reboot or Disable Diags" (by tapping on the appropriate entries)
  8. Select "R) Reboot System" and "Q) To continue"
  9. You should see the Jailbreak screen and the device should restart back into diagnostics mode; Select "D) Exit, Reboot or Disable Diags" again
  10. Select "D) Disable Diagnostics" and "Q) To continue"
  11. Now the Kindle should reboot into the normal firmware and it should be jailbroken. You can safely delete the diagnostic_logs folder on the Kindle USB drive.

Simple method (ONLY for older firmware versions!)

  1. Download and unzip the jailbreak (Mirror).
  2. Follow the instructions in the README file.

[edit] Uninstalling the jailbreak

Regardless of which jailbreak you installed, their net result is always the same: a developer certificate is installed on the device. Should you ever want to "un-jailbreak", apply the update_jailbreak_1.1_k5_uninstall.bin file from Yifan Lu's Jailbreak, version 1.1.

[edit] Unbricking

For the "modern" methods of debricking kindles, see "Boot over USB HID serial / USB downloader mode" below.

♦♦♦This part should be updated. There is a better tool on this thread (first thing to try) or full version ♦♦♦

This section is somehow related to both the Jailbreak topic above, and the Recovery topic below.

Before attempting the unbricking process you should try to reset the device.

  1. First make sure it is charged
  2. remove the interface cable
  3. then hold down the power switch for 20 seconds.

If the unit recovers after lifting your finger then the reset worked and you can continue using the device.

The method shown here is employed in the second (data.tar.gz jailbreak). However, the same method may also help to unbrick the device if it is still somewhat functioning (i.e., if the Kindle still allows USB access to its files).

Full background can be found at this thread, but to use it, in short: 

test -f /mnt/us/RUNME.done && exit
# The following set of commands will be executed (in the context of your Kindle) exactly once. To make them execute again, remove RUNME.done
#
# (mntroot rw and mntroot ro below are only shown for convenience, and not needed for this particular script. These commands allow
# to modify the internal file system. Use only if you know what you are doing. Oh well, you should have only ended up needing this advice
# if you knew what you were doing in the first place. ;-)
mntroot rw
showlog > /mnt/us/log.txt
mntroot ro
touch /mnt/us/RUNME.done

Adapt this file to your needs. The snippet above shows an example that may be particularly useful for de-bricking, as it dumps the device log into log.txt on the USB-accessible storage.

Another useful example can be found in this post, where remote login via Wifi to a bricked device was established.

If you're stuck at the "Your Kindle needs repair" screen, add echo 0 > /var/local/upstart/lab126_gui.restarts to RUNME.sh (see this thread).

[edit] Backup

It's always a good idea to backup everything before you start modifying things. The procedure to make backup copies of the Kindle's partitions is outlined below.

The examples below assume that you are able to connect to your Kindle via network (i.e., you must have installed the jailbreak, and enabled usb networking already), and that are using a Linux or MacOS computer (the "host") which has the appropriate commands installed, and is available via network at 192.168.15.1. Adjust according to your setup.

Repeat this procedure for mmcblk0p2 through mmcblk0p4 accordingly. The files that you get are binary copies of the individual partitions of the device. A short explanation of each partition can be found below.

[edit] Partitions

A backup of partitions 3 and 4 is thus not necessarily needed, if you can afford to lose personal settings. In contrast, backups of partitions 1 and 2 are highly recommended.

On Linux, you can mount partition images using mount -o loop,ro <image> <mountpoint>. Since partition 4 is actually a disk image which contains a single partition itself, the mount command for that partition is mount -o loop,ro,offset=8192 mmcblk0p4.bin <mountpoint>. From there, you can access the original files, to restore them on the device if some modification went wrong.

[edit] Recovery

See the USB HID section down below

[edit] Packages

Unless otherwise noted, packages are installed by copying update files (usually called <package>_<version>_install.bin) onto your device, and then choosing Settings -> Update Your Device. Packages installed this way mostly include an uninstaller as well.

[edit] USB Networking

This is arguably the most basic, and the most useful package, because it enables you to connect to your Kindle via SSH.

[edit] Automatically enabling USB network at boot

By default, when the Kindle starts up, it automatically sets "USB drive" mode. Below are few observations about how to automatically get it into USB networking mode:

[edit] Option 1: Starting usbnet from upstart

Create the file /etc/upstart/usbnetwork.conf with the following content: 

start on starting framework
task
script
	if [ -f /tmp/USBNET_ON ]; then
		echo USB network already enabled
	else
		source /usr/local/bin/usbnetwork.sh
	fi
end script

Your Kindle will now go into USB network mode once the framework has loaded.

If you reboot your device while being connected to it, that means two things:

This has the disadvantage that you can not directly reconnect via network after a network reboot. On the other hand, a network reboot will now automatically enter Storage mode, which may be beneficial sometimes. To get into network mode again, unplug and replug.

[edit] Option 2: create ENABLE_USBNET file (non-working)

This method involves creating a file named ENABLE_USBNET in the home directory (the root directory when mounting the kindle as a USB drive, or /mnt/us/ on the actual device. This file is checked by /etc/upstart/usbnet-autostart.conf. However creating this file is not enough, as it expects a wrapper script at /usr/local/bin/usbnetwork which is nonexistent.

[edit] Other options

Currently unknown, but there certainly are some. Please update this page if you know of any!


[edit] SSH access over Wifi

SSH access is disabled by default. The usbnetwork package does enable SSH access over Wifi, but only when USB networking is enabled. If you want to permanently allow SSH through Wifi (even without USB networking), you have to change the iptables rules on the device.

[edit] Finding out the Wifi IP of your Kindle Touch

Use the ;711 shortcut to display the networks diagnostic page. You should find the information in there.

[edit] Some useful commands for SSH

lipc-set-prop -- com.lab126.scanner doFullScan 1
link

[edit] Mounting via sshfs

It may also be helpful to mount your Kindle's filesystem into your computer. You can use sshfs to achieve this. You will need to have SSH access working in the first place, and you need the sftp-server binary.

Adjust the above examples to your particular setup as needed.

[edit] Localization

Localization packages for various languages are available in this thread.

[edit] Text-to-Speech (TTS)

See this post for instructions; The post only explicitly mentions german, but at the provided link there are packages for many other languages, and the procedure is exactly the same.

Note for firmwares starting with 5.1.0: TTS is disabled on non-english books. To enable it, install jbpatch and make sure that the TTS patch is loaded.

[edit] 24-hour clock

To change top bar clock format from 12- to 24-hour format change /var/local/system/locale from 

LANG=en_US.utf8
LC_ALL=en_US.utf8

to 

LANG=en_GB.utf8
LC_ALL=en_GB.utf8

and restart the device.

This also can be done without a jailbreak using "data.tar.gz" file with absolute path to /var/local/system/locale containing the lines above.

an alternative one which doesn't need jailbreak is on this page

You can achieve the same effect on firmware 5.1 by switching the language from English US to English GB in the settings.

[edit] Setting the time zone

By default, the time that the Kindle displays is UTC. If you are in a different timezone: 

[root@kindle root]# mntroot rw
# copy the required files to the Kindle!
[root@kindle root]# find /usr/share/zoneinfo/
/usr/share/zoneinfo/
/usr/share/zoneinfo/zone.tab
/usr/share/zoneinfo/iso3166.tab
/usr/share/zoneinfo/Europe
/usr/share/zoneinfo/Europe/Berlin
[root@kindle root]# ln -sf /usr/share/zoneinfo/Europe/Berlin /etc/localtime

You will first need to copy the respective zone directory/file (shown in bold above) from another Linux system, as /usr/share/zoneinfo/ is initially (almost) empty on the Kindle!

[edit] GUI Launcher

This mod adds a new menu option to the home screen and to the reader screens. The purpose is to allow for other mods to integrate with the menu system, so that users have easy GUI access to their functionality. Here's how it looks:

Home Menu: Launcher (Home Menu) Submenu: Launcher (Individual Menu)

The first post of the thread contains download links, as well as source code and instructions for developers.

Documentation: http://yifanlu.github.com/KindleLauncher/

[edit] Extensions for the GUI Launcher

Using YiFanLu's GUI Launcher as the foundation, these mods add additional functionality.

[edit] Folder Toggle

http://ebookjuggler.com/kindle/folder-and-book-hider/ This mod allows you to hide or show a subset of your books. You can go into the config file for each profile, and add a list of directories to toggle. Still in development, but moving along nicely. Download the zip file attached in the thread, and follow the README. Project originated on: http://www.mobileread.com/forums/showthread.php?t=164259

[edit] SSModeSwitcher

http://www.mobileread.com/forums/showthread.php?t=170080
This extension helps to change screensaver mode among four screensaver profiles ( default, screenlock and 2 custom modes)

[edit] CollectionSync

File:CollectionSync.zip is an extension to work with yifanlu's launcher, to generate collections according to current contents.

[edit] Enterprise WPA

Kindle Touch supports Enterprise WPA out of the box from firmware 5.1 onward.

For older fimwares (5.0.0-5.0.4), it does not (though the underlying wpa_supplicant does). There is a Launcher extension available in this thread. Configuration is manual, but at least, once the network is correctly configured, it can be connected to with a single click. You can use this extension for other types of connection also: WPA-PSK , WEP

[edit] Removing Ads

Using the launcher and this extension we can run a script that removes ads permanently, changing the kindle into a non-ad supported version. You can then use the screen saver hack, etc. http://ebookjuggler.com/kindle/removing-ads-on-the-kindle-touch/ Original thread: http://www.mobileread.com/forums/showthread.php?t=164261

[edit] HackedUpReader / CoolReader 3

HackedUpReader is a port of CoolReader 3 for Kindle Touch. Use this custom reader to read mobi/epub/fb2/txt/rtf/html/pdb. To install, unpack https://github.com/downloads/varnie/HackedUpReader/HackedUpReader-0.1.2-varnie.tar.gz (better version, maintained by user Varnie) to cr3xcb folder in /mnt/us/ (root dir via USB). After that, you need to unpack https://github.com/varnie/HackedUpReaderLauncher/zipball/master to the extensions folder. Original thread: http://www.mobileread.com/forums/showthread.php?t=170436

[edit] WAF based extensions

These are extensions that launch apps written in html/js and can be found at :http://code.google.com/p/wafonkindle/

[edit] Sokoban

You can download a version of Sokoban for KT.

http://pbchess.vlasovsoft.net/en/games.html
[edit] pbchess

pbchess is a powerful chess training program available for Kindle Touch. With pbchess you can:

  1. Solve chess problems (a lot of chess problems you can find on the website)
  2. Load and review PGN with comments/variations, analyze games, try variations
  3. And of course - play chess (6 most famous free chess engines, 12 levels).

You can download a version of pbchess for KT here:

http://pbchess.vlasovsoft.net/en/index.html
[edit] Audio Recorder and Player

Very simple exension that can record sound using the built-in microphone, and play back the last recorded file.

http://www.mobileread.com/forums/showthread.php?t=167172
[edit] Image Viewer

A very simple extension to run the hidden Image Viewer on Kindle Touch 5.1: http://starsy.github.com/Kindle-Touch--Image-Viewer/

Direct donwload: https://github.com/starsy/Kindle-Touch--Image-Viewer/zipball/master

Screenshot: [2]

[edit] VNC Server

You can install a VNC Server on your Kindle Touch and access your Kindle from a VNC Client (computer) via WiFi or usbnetwork. Steps needed to connect via WiFi:

  1. Install the package found in this thread.
  2. Install a VNC client on your computer. (TightVNC is super small and works well) (the VNC Client must be on the same WiFi as the Kindle)
  3. Enable WiFi on your Kindle
  4. Input ;711 in the search field on your Kindle and press enter;
  5. Note the IP address listed in section "4-Interface"
  6. Use your VNC Client to connect to that IP address on port 5900 (IP::5900)

To disable the VNC server without uninstalling it, rename or delete /mnt/us/vnc/ENABLE_VNC and restart your Kindle.

[edit] Additional command-line tools: "Extend"

Description: Extend uses "optware" packages to enhance linux functionality by mounting a premade 512mb image file with software such as openssh, nano, screen, irssi, php, bash, rsync pre-compiled with optware tools. Packages can be managed with the command /opt/bin/ipkg, no need to cross-compile.

[edit] Smaller optware.img

The size of the optware.img contained in the above archive is a whopping 500 MB, of which only some 55 MB are actually used. This means that about 445 MB are wasted (but will eat up the storage space on your Kindle).

[edit] Fix for /opt/bin/ipkg requiring the root filesystem to be mounted read-write

Even though the packages available through ipkg are completely installed inside the directories under /opt, actually using the ipkg command may result in this error: 

[root@kindle ipkg]# /opt/bin/ipkg list
ipkg_conf_init: Failed to create temporary directory `(null)': Read-only file system

This is a minor issue, and the cause and possible solutions are given in this post.

[edit] Automatically enabling extend

By default, the extensions are not mounted automatically, and the newly available binaries must be explicitly invoked from /opt/bin. The examples below show how much of this can be automated. They are taken from my personal setup. Create or edit these files according to your needs.

/etc/upstart/extend.conf: 

start on starting framework
task
script
	source /mnt/us/extend/upstart.sh
end script

/mnt/us/extend/upstart.sh: 

if [ -e /opt/bin/nano ]; then
	echo Extend already mounted
else
	/mnt/us/extend/mount.sh
	cp /mnt/us/extend/.profile /tmp/root/
	source /tmp/root/.profile
fi

/mnt/us/extend/.profile: 

export PATH=$PATH:/opt/bin

Note: for reasons unknown at this time, this does not work reliably (i.e., not on every boot). Please correct or add comments if you find better ways. [While debricking my kindle, I discovered that accessing files on /mnt/us/ during startup sometimes has "Stale NFS Mount" errors. Perhaps the script needs a delay until user partition mounted.]

[edit] Screen Savers

On non-ad-supported devices, you can change the screensavers to your own ones.

This does not seem to work anymore with Kindle Touch Software Update Version 5.1.0.

Workaround for version 5.1.0: Use the older version, that is the simple screensaver which can found at the following link

[edit] Custom Fonts

The fonts used on the Kindle Touch can be changed by installing this hack.

Read the README file (inside fonthack directory) carefully and, always, read the last news on this thread so you can follow all development and discussions.

Pre-packaged fonts for use with it, in alphabetical order:

You can also use the fonts for K3 (mirror). Included are: Bembo, Constantia, Droid Serif, Georgia, Georgia2, ITC New Baskerville, Linux Biolinum, Linux Libertine, Miller Serif, Minion Pro, Palatino, Times New Roman. Attention: these fonts are using a different file naming convention, so you need to manually rename the files to the naming convention that FontHack expects before you can use them.

[edit] Useful hidden functionality

[edit] Search Bar Shortcuts

Just like the older models, the KT supports shortcuts / commands entered via the search bar. Tap on the search bar, enter the command, followed by the return "key". The following commands have been identified (source post): 

;dm - Dump messages to /documents
;dh - Dump cvm heap
;dt - Dump cvm stack
;shpm - set device to shipping mode
;urst - Reset user partition, deletes content of hidden System folder, Audible folder, Documents and tts folder. 
        Before using do a complete backup of your device
;debugOn - verbose logging
;debugPaint - log painting functions
;debugOff - non-verbose logging
;debugPref - pref level logging
;dP - alias of ;debugPref
;311 - change carrier settings
;411 - server information
;611 - wan information
;711 - wifi information
;setTime - sets kindle time to unix clock
;st - alias of ;setTime
~ds - Never show screen saver   (then you cannot lock the kindle till next reboot. 
                                 Rebooting the Kindle will restore the screen saver lock and, hopefully, everything goes fine! )

And of course, if you installed the usbnetwork hack: 

;usbnetwork - toggle USB networking
;un - alias of ;usbNetwork

These shortcuts are defined in the file /usr/share/webkit-1.0/pillow/javascripts/debug_cmds.js (in 5.0.0) or /usr/share/webkit-1.0/pillow/debug_cmds.json (5.0.3). Additional shortcuts can be manually added to this script (at user's own risk) in the same format as the originals. For example, adding ";xterm" = "/opt/bin/xterm" (after adding a comma to the previously final line) allows you to launch xterm (installed through the "extend" system) from the search bar by typing ";xterm", although it will not be visible on the KT until a way to display custom Xorg apps is worked out. It will, however, appear in "top" and be assigned a process ID, suggesting it is running in the background.

[edit] Image Viewer

Only for firmware 5.1 and hopefully, later versions!

Put some pictures in /mnt/us/images/ and run this command: 

lipc-set-prop com.lab126.appmgrd start app://com.lab126.booklet.imageviewer

[edit] Taking screenshots

Hold down the home button for 2 seconds, tap the screen, and keep holding the home button for another second or two. Screenshots are saved into the /mnt/us/ folder, i.e., the root folder of the device when mounted via USB.

Alternatively, if you're logged in via USB network, just issue the screenshot command.

[edit] Forcing update installation

The normal procedure for installing updates is to connect the Kindle as a USB drive, then copy an update_*.bin file to the root of the Kindle drive, eject the drive, and use "Menu > Settings, Menu > Update Your Kindle" on the device.

When updates are copied to the device in some other way (for example putting the file to /mnt/us in USB network mode), the Kindle will normally not recognize that there is an update, and the "Update Your Kindle" menu entry remains grayed out. However, you can still force the installation from the command-line: 

lipc-set-prop com.lab126.ota startUpdate 1

[edit] Architecture

The Kindle Touch is running a Linux OS. While you're interacting with it, internally, a mixture of native programs, Java, and Javascript is being run on the device. Quoting Yifan Lu from a forum thread:

The Kindle "OS" or whatever you call it starts out when the Kernel calls upstart (not sysvinit anymore). Upstart loads the low level linux components. Lipc is this thing amazon wrote to allow all components to talk to one another. Everything in the Kindle is modular. In theory, I can write a python implementation of the media player and set a lipc event handler and property reader and music will play through python. Pillows are the HTML5/JS component of the system.
It's weird how they decided to make some parts of the OS HTML. My guess is that either 1) they wanted the whole thing to be HTML and halfway through realized it wouldn't work and fell back to Java, but didn't have time to rewrite everything or 2) they wanted the whole thing is Java but didn't have time to rewrite everything and then quickly whipped up some HTML stuff they were doing for the browser anyways. Either way, pillows are registered into the appdb (a sqlite3 database) which also contains a listing of book handlers (java reader plugins) and download handlers (unused). Overall, it's VERY messy.

[edit] The big picture

Kindle Touch Architecture

The above image is a first attempt to visualize the individual subsystems of the Kindle Touch, and how they relate and interact. The parts which are probably of most interest to developing new stuff are marked in red. Below follow descriptions of the more important parts.

[edit] Linux OS and applications

The KT runs a custom Linux (source code downloads). Available applications are mostly what busybox provides, plus quite a few tools that Amazon wrote. You can easily add more tools by installing the extend package as described above.

[edit] Startup

If you want to fiddle with the startup procedure, like what software gets loaded, or how it is parameterized, look into /etc/upstart.

[edit] Log Files

Fortunately, the Kindle Touch provides pretty extensive logs, which are useful to understand what's going on. For example, showlog -f shows the syslog, while showlog -p shows the wpa_supplicant logs. Issue showlog --help for further information.

You can increase the level of logging verbosity using the shortcut command ;debugOn.

[edit] Developing and Debugging

The Kindle is using an ARM processor, so all binaries you wish to run must be compiled for the correct architecture. If you're using the correct toolchain, most Linux programs can be compiled to run on the Kindle.

The Kindle also comes with a bundled version of gdb. This may be helpful to debug (at assembly level) native applications.

Somebody asked for an elaboration? 

#include <stdio.h>

int main()
{
	printf("lolhimobileread!\n");
	return 0;
}

[edit] LIPC

LIPC is essentially an inter-process communication tool. Processes can start other apps, send events to them, register listeners for events, etc. Internally, it is (seems to be) built on dbus. There are LIPC bindings for the higher-level layers as well, which for example enables a Webkit application (written in HTML+Javascript) to communicate with a Java service, or a native application, etc. Complex data structures are encoded as JSON.

[edit] Application registry

In fact, LIPC is an essential underpinning of the system. There is an SQLite database located at /var/local/appreg.db containing a lot of information about how the "wiring" is performed. (This DB seems to be the "union" of the files /var/local/reg/ServerConfig.db and /var/local/reg/prereg.db).

Below are excerpts from a dump of it. While not everything is fully understood yet, there are a few "educated guesses" added as comments: 

Interfaces could be considered "types" or "kinds" of pieces of software.
CREATE TABLE interfaces ( interface TEXT PRIMARY KEY NOT NULL ON CONFLICT IGNORE );
INSERT INTO "interfaces" VALUES('acx');
INSERT INTO "interfaces" VALUES('extractor');
These are in principle stand-alone (UI) applications that can be launched and will be displayed to the user: 
INSERT INTO "interfaces" VALUES('application');
INSERT INTO "interfaces" VALUES('detail');
These are internal services which the Java subsystem (only?) uses to provide specific functionality 
INSERT INTO "interfaces" VALUES('kaf-service');
INSERT INTO "interfaces" VALUES('todo');
INSERT INTO "interfaces" VALUES('indexer');
INSERT INTO "interfaces" VALUES('download');

Every LIPC handler known to the system must be registered. The purpose of many of them unknown, but here's a few interesting ones.
CREATE TABLE handlerIds ( handlerId TEXT PRIMARY KEY NOT NULL ON CONFLICT IGNORE );
A few "hidden" Webkit/WAF applications. They are pretty crude, but actually work:
INSERT INTO "handlerIds" VALUES('com.lab126.draw');
INSERT INTO "handlerIds" VALUES('com.lab126.sample');
These handlers trigger the home screen, and settings screen respectively:
INSERT INTO "handlerIds" VALUES('com.lab126.booklet.home');
INSERT INTO "handlerIds" VALUES('com.lab126.booklet.settings');
A few services, names should be self-explaining:
INSERT INTO "handlerIds" VALUES('com.lab126.kaf.keyboardLayoutService');
INSERT INTO "handlerIds" VALUES('com.lab126.kaf.wifiService');
INSERT INTO "handlerIds" VALUES('com.lab126.kaf.rotationService');
INSERT INTO "handlerIds" VALUES('com.lab126.kaf.TTSService');

This table contains further configuration for particular handlers:
CREATE TABLE properties ( handlerId TEXT NOT NULL REFERENCES handlerIds( handlerId ), name TEXT NOT NULL, value TEXT, PRIMARY KEY (handlerId, name) ON CONFLICT REPLACE );
This one is obviously launched through a command-line:
INSERT INTO "properties" VALUES('com.lab126.draw','command','/usr/bin/wafapp -l com.lab126.draw -c /var/local/waf/draw/');
These ones concern the home screen:
INSERT INTO "properties" VALUES('com.lab126.booklet.home','lipcId','com.lab126.booklet.home');
INSERT INTO "properties" VALUES('com.lab126.booklet.home','jar','/opt/amazon/ebook/booklet/home.jar');
INSERT INTO "properties" VALUES('com.lab126.booklet.home','supportedOrientation','U');
INSERT INTO "properties" VALUES('com.lab126.booklet.home','maxLoadTime','40');
INSERT INTO "properties" VALUES('com.lab126.booklet.home','maxGoTime','30');
INSERT INTO "properties" VALUES('com.lab126.booklet.home','defaultContext','context=0');
KAF services are (mostly) defined by their class name: 
INSERT INTO "properties" VALUES('com.lab126.kaf.TTSService','serviceClass','com.amazon.kindle.restricted.media.TTSServiceImpl');

MIME types supported by the system (showing only two samples):
CREATE TABLE mimetypes ( ext TEXT COLLATE NOCASE PRIMARY KEY NOT NULL ON CONFLICT IGNORE, mimetype TEXT COLLATE NOCASE NOT NULL ON CONFLICT REPLACE );
INSERT INTO "mimetypes" VALUES('azw','MT:application/x-mobipocket-ebook');
INSERT INTO "mimetypes" VALUES('pdf','MT:application/pdf');

This is redundant with the above table, and contains (almost) identical information. Not sure why this is so, or which table is used.
CREATE TABLE extenstions ( ext TEXT COLLATE NOCASE NOT NULL ON CONFLICT REPLACE, mimetype TEXT COLLATE NOCASE PRIMARY KEY NOT NULL ON CONFLICT REPLACE );
INSERT INTO "extenstions" VALUES('azw','MT:application/x-mobipocket-ebook');
INSERT INTO "extenstions" VALUES('pdf','MT:application/pdf');

This finally associates extensions or mime types with handlers:
CREATE TABLE associations ( handlerId TEXT NOT NULL REFERENCES handlerIds( handlerId ), interface TEXT NOT NULL REFERENCES interfaces( interface ), contentId
TEXT NOT NULL, defaultAssoc TEXT, PRIMARY KEY (interface, contentId, handlerId) ON CONFLICT REPLACE);
INSERT INTO "associations" VALUES('com.lab126.mobi.extractor','extractor','GL:*.azw','true');
INSERT INTO "associations" VALUES('kindlet.extractor.azw2','extractor','GL:*.azw2','true');
INSERT INTO "associations" VALUES('com.lab126.booklet.reader','detail','MT:application/pdf','true');
INSERT INTO "associations" VALUES('com.lab126.booklet.reader','download','MT:application/pdf','true');
INSERT INTO "associations" VALUES('com.lab126.kaf.TTSService','kaf-service','none','false');

[edit] Interesting handlers / actions

Please insert additional information you have on how to interact with particular handlers, in particular if valid values for setting properties are not easy to determine. You can get an exhaustive list of the handlers and supported properties by invoking lipc-probe -a -v.

[edit] Starting arbitrary applications

Use lipc-set-prop com.lab126.appmgrd start app://com.lab126.sample or the like. The last part is the handler name of the application you want to start. Examples:

[edit] Changing screen orientation

lipc-set-prop com.lab126.winmgr orientationLock L -- use U,D,L, or R to set the desired orientation.

[edit] Influencing titlebar and menu

lipc-set-prop com.lab126.pillow configureChrome '{"titleBar":{"clientParams":{"secondary":"Hello World","useDefaultPrimary":false}}}'

More information: http://www.mobileread.com/forums/showthread.php?p=2072496#post2072496

[edit] Preventing screen saver activation

lipc-set-prop com.lab126.powerd preventScreenSaver 1

[edit] Disabling "Share that you have read this book" after end of book

More info: http://www.mobileread.com/forums/showthread.php?p=2022528#post2022528

[edit] Java Subsystem

Much of the user interface is written in Java. The JVM is a proprietary one, and is compatible with Java 1.4. The framework is started from /etc/upstart/framework.

As described above, the Java subsystem provides LIPC handlers both for services, and for providing the UI -- so-called Booklets.

[edit] Remote Debugging

[edit] Poking around in amazon's classes

This is extremely useful if you want to understand the inner working of a particular part of the framework.

The exact procedure is left as an exercise to you, but here's a short outline:

The KT jars are (as of version 5.0.1) only partially obfuscated -- most importantly, class, method, and many constant names are intact.

[edit] Changing functionality

There is an extremely powerful tool which allows to modify almost any Java class in whichever way required, without having to modify the files on your device. See jbpatch thread for information, patches, and a short HOWTO.

[edit] Webkit Subsystem

With the Kindle Touch, Amazon has introduced a second way to create UI components. This one is based on Webkit, i.e., HTML5 and Javascript.

There are two places in the system where the KT makes use of this technology:

[edit] Applications in /var/local/waf/

WAF presumably standing for Web Application Framework, in this directory you can find quite a few applications -- most notably, the built-in experimental browser can be found there. There are quite a few other apps, such as a proof-of-concept drawing app, Facebook- and GMail apps, a Store app etc. Some WAFs are composed of a simple config.xml with reference to a source URL. These pages are cached somehow. 

com.lab126.draw - <content src="http://mrdoob.com/projects/harmony/#simple" />
com.lab126.gmail - <content src="http://m.gmail.com" />
com.lab126.fb - <content src="http://touch.facebook.com" />
com.lab126.store - http://www.amazon.com/gp/digital/juno/

A somewhat detailed description of the config.xml format and features can be found in this post (information as of Firmware 5.0.1)

As for custom WAF development, check out my website at http://www.sudoforlunch.co.cc/building-a-waf-the-easy-easier-way/

[edit] Components in /usr/share/webkit-1.0/pillow/

In that directory, two html pages can be found, namely:

In contrast to the WAF applications above, these are much more interwoven with the system.

[edit] Pillow

In order to interact and tightly integrate with the system, there must be a way to access it from within Javascript. This is achieved through pillow, a Javascript library that allows access to the LIPC component. In addition to LIPC access, it also provides a so-called native bridge, which allows to log to syslog, to create and dispose dialog windows, and to run executable commands (this was the vector used for the jailbreak).

[edit] Blanket

Blanket is the system Amazon uses to draw images and text to screen at the "low end" of the architecture. Basically, it draws the splash screen, the usb connected screen, the screensavers, the ad screensavers, the language picker, and the "service needed" screen. However, the system is designed to be flexable enough to handle any LIPC event. The interesting part is that libblanket loads "modules" to do things. Yifan has reverse engineered libblanket to produce a working header for writing your own blanket modules. He has also decompiled the screensaver module painstakingly by hand as a reference implementation. The code you see there should be almost identical to Amazon's own code. Blanket uses Cairo to do the drawing, so it would not be THAT hard to write a custom screensaver module that could do more than just draw a single picture. Some things that come to mind would be: converting colored pictures and resizing on device, drawing the cover of the book currently read, drawing a calendar, drawing weather data, etc.

[edit] Boot over USB HID serial / USB downloader mode

Freescale i.MX508 MCU used in Kindle Touch has a "USB downloader" boot mode.

When mode is enabled, Kindle is recognized as USB HID device with VID 0x15A2 and PID 0x0052. It should be possible to connect to it via custom Serial Download Protocol designed by Freescale and described in MCU Reference Manual. Protocol allows to read/write memory, upload program image into RAM and start executing at given address.

To enable this mode one should perform "hard reset" with pressed Home button. Hold Home button, then perform "hard reset" by holding Power button for 20 seconds and releasing it. Then wait about a second or two and release Home button. That's all.

It's easier to follow with Kindle connected to computer. After 20 seconds of holding Power button, Kindle USB disk should be detached from computer. It's time to release Power button. Then Kindle should be recognized as USB HID device. Now Home button could be released.

This mode is described in section 6.9 (Usb Downloader) of i.MX50 Reference Manual. Serial Download protocol specification could be found at section 6.9.2.

Freescale provides software tool for Windows to upload data into RAM and execute it in USB Downloader mode. Tool is named "sb_loader" and available for free download at Freescale website. Here's the direct link: http://cache.freescale.com/files/32bit/software/sb_loader.v1.1-g63b47f0_bin+src.zip. (Link is provided on i.MX508 Product Summary page under the tab "Software & Tools" in section "Programmers (Flash, etc.)" under the name "IMX_SB_LOADER".) Tool's source code is included in distribution archive and provided under BSD license.

This USB Downloader mode has been used to load and run a modified u-boot.bin compiled from amazon gpl source code, which had custom changes added to repair damaged idme variables (most importantly pcbsn, which allowed the kindle to finish booting). The custom u-boot also changed idme var "bootmode" to "fastboot", and the kindle fastboot tool was used to complete the repair.

And now there are custom u-boot images supplied with freescale MfgTool custom profiles, that let you boot your kindle to main, diags, or fastboot bootmodes using a menu selection. Even a severely bricked kindle touch or k4 cant be booted to fastboot to flash linux kernels or diags partitions, and then booted to diags to write the main partition from an image file (with "dd"). And there is now a touch diags partition image with SSH preinstalled (which you can flash with fastboot). To make this even easier, the kindle flashboot tool has been ported to run in a native win32 command console. Many kindles have been debricked using these tools. Read more about it here:

Select Boot for K4 and Touch: http://www.mobileread.com/forums/showthread.php?t=169645

simple kindle touch (and k4nt) debricking method: http://www.mobileread.com/forums/showthread.php?t=170929

Fastboot Manifesto: http://www.mobileread.com/forums/showthread.php?t=170241

Fastboot for Windows: http://www.mobileread.com/forums/showthread.php?p=2001683

Kindle Touch partition images: http://gitbrew.org/~dasmoover/kindle/touch/forensic/

[edit] Implementing Particular Functionalities

[edit] Android

Hi, this is Yifan. I want to see Android running on this thing. After that, we can also run the Nook Simple Touch OS and have access to BN store & ePub reading with a good UI. It'll also allow easy development and running of android apps (although slowly). Here's a great (but outdated) reference on what needs to be done for an Android port: http://wiki.kldp.org/wiki.php/AndroidPortingOnRealTarget Also, since Amazon graciously provided the kernel sources with relevant drivers and patches for the Touch, it should not be as hard as porting Android to a non-linux device. http://cache.freescale.com/files/32bit/doc/user_guide/IMX50SDG.pdf <- Freescale provides a wonderful development guide for iMX50 including a section on porting android.

[edit] Terminal Emulator

Installing the Extend framework allows one to install (via ipkg) xterm, which can then be launched successfully without further configuration.. but it won't display.

Starting another XOrg server allows apps to be displayed (as detailed here). Over SSH, this is accomplished by typing: Xorg :1 & (The ":1" tells it to open an alternative display to the usual ":0". The ampersand sends to background) followed by: xterm -display :1 & (The "-display :1" tells xterm to connect to the new Xorg, above. The ampersand sends to background on ssh.) Doing the above and clicking the front panel button on the Kindle Touch results in the xterm appearing on-screen on the touch, but it cannot be interacted with and is quickly replaced by items from the other (default) xorg server; in other words, it's replaced by items on the top status bar, the search bar, book lists. Touching xterm does not interact with it, passing through to items on the main kindle display.

Xterm can be started from the search bar by adding a shortcut to the list, as described above. Perhaps by appending display parameters, it can be coaxed to display.

To be determined; 1) Is there any danger in disabling the "nolisten tcp" function on the default Xorg server, which might perhaps allow more seamless integration of X apps with the display? 2) How does the kindle keyboard work, and can it be used to direct input to Xorg apps? 3) xterm supports sending screen-refresh signals to Xorg; is this enough to refresh the E-ink screen?

[edit] Collections

I want to know whether there is working tool for kindle touch collections. I've scratched up a hack to generate collections from directories. The theory is: use a script to generate json codes use to insert& update collections for current contents in /mnt/us/documents/, use the http://localhost:9101/change port to do the real work. I've made an extension to use the yifanlu's laucher, Here
Directly dealing with /var/local/cc.db might work, but risks should be much higher.

[edit] Creating custom packages

To create signed update packages signed with the jailbreak key (that is installed when the Kindle is jailbroken), you must use KindleTool. KindleTool is designed to run on Unix based systems, so it doesn't play nice on Windows. However, it is easy to set up on Linux and OSX.

OSX To Compile:

  1. Install Xcode 4
  2. Install MacPorts
  3. Using macports, install the packages: libtar, openssl, and zlib
  4. Get the source code for KindleTool from GitHub, open it in Xcode, and compile

To just run:

  1. Download the latest binary release archive.
  2. Extract the OSX directory, and run the tool from Terminal

Linux To Compile:

(For Ubuntu 10.04, an all-in-one command for steps 1.-3. is sudo apt-get install build-essential libssl-dev zlib1g-dev libtar-dev)

  1. Install the standard set of compiling tools including gcc and make
  2. Install openssl-devel and zlib-devel
  3. Compile and install libtar
  4. Get the source code for KindleTool from GitHub, cd to it in shell, and type "make"
  5. (you may have to modify the makefile to point to the include files from the libraries you installed above)

To just run:

  1. Make sure you have openssl and zlib installed
  2. Download the latest binary release archive.
  3. Extract the Linux directory, and run the tool from Terminal

Windows To Compile

  1. Install cygwin with the packages openssl-devel and zlib-devel
  2. Compile and install libtar in cygwin
  3. Get the source code for KindleTool from GitHub, cd to it in cygwin's shell, and type "make"
  4. (you may have to modify the makefile to point to the include files from the libraries you installed above)

To just run:

  1. Install cygwin
  2. Download the latest binary release archive.
  3. Extract the Windows directory, and run the tool from cygwin's shell (NOT command prompt)

[edit] Usage

Run the tool with no arguments for a detailed usage guide.

[edit] Example

Let's say you want to run a script "run.sh" on the device which extracts "data.tar.gz" to the Kindle.

  1. Rename run.sh to run.ffs and move it to ~/kindle
  2. Move data.tar.gz to ~/kindle
  3. Run the tool: ./kindletool create ota2 -d k5w -d k5g ~/kindle ~/update_custom_script.bin

This creates an update package that will run on all Kindle Touches.

[edit] Limitations

Retrieved from "http://wiki.mobileread.com/wiki/Kindle_Touch_Hacking"
Personal tools
Namespaces
Variants
Actions
Navigation
MobileRead Networks
Toolbox
Advertisement