Kindle Touch Hacking
 |
Languages: |
English |
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) And Kindle Paperwhite (PW), 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!
| 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. |
Before you start:
- One of the first things you REALLY SHOULD DO once you have jailbroken your device is BACKING IT UP!. Trust us, you'll be glad you did.
- Make sure that your device is set to the correct time and date. (The easiest way is to connect to a wireless network). If your device's time is incorrect, you may experience problems while installing update packages.
[edit] K5 index
Index of the important K5 category threads, posts and off-site resources.
K5 index
[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.
[edit] CURRENT UNIVERSAL METHOD
In this thread you will find a jailbreak method that works for some Kindle Touch AND PaperWhite/PaperWhite2 firmwares (5.0.0, up to 5.4.4.2).
If you are currently running or intend to run FW >= 5.4.5 & < 5.6.x on a PW2, know that it is possible, but do read the relevant section in the JailBreak instructions carefully! If you aren't currently running FW >= 5.6.x, but intend to through an update, know that it is doable safely (on specific configurations only), but it entails some potential drawbacks. Again, read the relevant section of the JailBreak thread very carefully.
UPDATE: This thread has universal jailbreak instructions for most touchscreen Kindle versions running firmware prior to 5.8.8: http://www.mobileread.com/forums/showthread.php?t=275877
This wiki page is meant to replicate that threads information. 5.x.x "Universal" Jailbreak Method
The rest of this section is only kept for historical reference.
[edit] Which method is best for me ?
This depends on your device and firmware version.
- Kindle Touch:
- Firmware 5.0.0 - 5.1.2: use the data.tar.gz method. Be careful to select the correct file to use based on your firmware version.
- Firmware 5.3.2, 5.3.2.1, 5.3.7: use the manual method below, or refer to this thread (Yes, it's written for the 5.3.7, but in fact works on all versions).
- Kindle Paperwhite:
- Firmware 5.2.0 - 5.3.1, 5.3.4, 5.3.5: use the jailbreak.mobi method.
- Firmware 5.3.3, 5.3.6: use the jailbreak.mobi method. (You'll have to downgrade to 5.3.1 or 5.3.5 first)
[edit] jailbreak.mobi method
This method works on the Paperwhite only, on firmware versions 5.2.0 - 5.3.1, 5.3.4, 5.3.5. It is the recommended method for jailbreaking the Paperwhite. If you are running a newer firmware version, you can downgrade to 5.3.1, install the jailbreak, then upgrade again. Instructions for doing so are contained in the linked thread.
To install the jailbreak, follow the instructions in this thread.
[edit] data.tar.gz method
- Thread: http://www.mobileread.com/forums/showthread.php?t=186645
- (More technical background information: http://www.mobileread.com/forums/showpost.php?p=1902438&postcount=41)
This method works on Kindle Touch version 5.0.0 through 5.1.2, and on Kindle PaperWhite version 5.2.0.
- Download and unzip the jailbreak.
- If you're running firmware 5.1.x or 5.2.0:
- Plug in the Kindle and copy the data.stgz file to to the Kindle’s USB drive’s root
- Safely remove the Kindle from USB and restart it (Menu -> Settings -> Menu -> Restart)
- If you're running an older firmware 5.0.x:
- Plug in the Kindle and copy the data.tar.gz file to to the Kindle’s USB drive’s root
- Safely remove the Kindle from USB and restart it (Menu -> Settings -> Menu -> Restart)
[edit] jailbreak.mp3 method
This method works on Kindle Touch version 5.0.0 and 5.0.1. For newer firmware versions, see above.
- Background information on how it works
- Thread in Kindle Developer's Corner
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] Manual method
This method works on the Kindle Touch only, but it should work on all firmware versions. It is considerably more complicated than the above methods, for the simple reason that Amazon wants to make jailbreaking difficult, and has rendered all previous jailbreak methods impossible with recent firmwares. So if you're on firmware 5.3.2 on a Touch, be prepared for a tedious jailbreaking procedure.
Thread: http://www.mobileread.com/forums/showthread.php?t=203971
[edit] Uninstalling the jailbreak
Kindle Paperwhite: Follow these instructions.
Kindle Touch: 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_*_uninstall.bin file from here.
[edit] Exiting Diags Mode
So, for one reason or another, your Kindle Touch or Paperwhite is in diags mode, and you don't know how to get out of it? Here's how:
- Press "S) Device Setting" (the very first item in the list) on the Touch Screen
- Press "X) Exit"
- Press "D) Exit, Reboot or Disable Diags"
- Press "D) Disable Diagnostics"
- Press "Q) To continue"
Wait a moment (around 30 seconds). Your device is rebooting in main mode.
[edit] Rebooting
The device can be rebooted by quickly pressing power button 4 times. This does not reset settings.
[edit] Unbricking
The recommended tool for debricking or downgrading Kindle Touch is a Linux LiveCD/LiveUSB called Kubrick. You should not need anything else. Note that this does not work for the Paperwhite.
Here are links to other methods:
- Factory reset a K5 (Paperwhite) using a single file
- Select Boot for K4 and Touch
- Simple debricking for K3, K4 and K5
- data.tar.gz / RUNME.sh (does not work on all models)
- Fix "Your Kindle needs repair"
- Unbrick your kindle Paperwhite via serial port
[edit] Backup
It's always a good idea to backup everything before you start modifying things.
Of particular note to PW & PW2 users: since FW 5.3, official updates bundle a full image of Partition 1 & the Main Kernel, which is pretty much the most important stuff we used to recommend backing up, so some of the information that follows is redundant for you. (In case of emergency, your tool of choice to get at those files inside the casing of the update file is KindleTool, described at the bottom of this page).
[edit] A: The easy way
- Kindle Touch: You can manually install an SSH-enabled diags partition by following these instructions, or, even simpler, by flashing your firmware using Kubrick.
- Kindle Paperwhite: This Paperwhite Jailbreak already includes everything that you need. Note that you will have to re-install the rescue pack if you update your firmware to 5.3.3 or higher.
This is your safety net in case your Kindle gets bricked. It's probably a good idea to "dry-run" it after you installed it ("dry-run" meaning: verifying that you can properly access it, but not actually re-flashing anything) - see below for the instructions.
[edit] B: The manual way
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.201. Adjust according to your setup.
- on the Host: nc -l 31337|dd of=mmcblk0p1.bin. Note: depending on your version of netcat, this may not work. If you have an old version of netcat, try nc -l -p 31337|dd of=mmcblk0p1.bin instead.
- on the Kindle: dd if=/dev/mmcblk0p1|nc 192.168.15.201 31337
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
- Partition 1 (mmcblk0p1 / ext3, 350 MB): The root file system. This contains the operating system and the files of the framework. If this partition is damaged, your device will not work properly.
- Partition 2 (ext3, 64 MB): This is the emergency recovery system (diagnostics system). You normally won't even get to seeing or modifying this partition. Under all normal circumstances, keep your fingers away from this.
- Partition 3 (ext3, 32 MB (KT)/ 64MB (PW)): This partition (mounted to /var/local/ ) contains local settings. Most probably, the contents can be deleted [1]. You will lose your settings, but the device will still work.
- Partition 4 (FAT32, 3.3 GB (KT and some PW2) / 1.4 GB(PW)): This is where your documents go. In normal operations, it is mounted as /mnt/us, and this is the partition you get to modify when you mount the Kindle via USB. You can delete the contents if you can afford to lose your documents; the device will still work. [Do not delete /diagnostic_logs/device_info.xml from a USB Drive exported from the diagnostic recovery menu screen, or it will be difficult to reboot to the main partition.]
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.
When looking through a mounted image do not get confused with links, that point to outside of your image or you might wonder, why there are eclipse or even worse: teamviewer files at /lib/firmware/opt
[edit] Kernels
- Main (main_kernel): The main Kernel used by the device.
- Diags (diags_kernel): The Kernel used when the device runs in diagnostic mode.
You can easily backup your device's kernels using geekmaster's getkernels tool. For example, after unpacking the latest version in the userstore:
cd /mnt/us && ./getkernels /dev/mmcblk0 && cd -
[edit] Recovery
See the USB HID section down below
[edit] Packages
Unless otherwise noted, packages are installed by copying update files (usually called update_<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.
- Jailbreak required
- Download 'usbnet' from here extract it and then move the appropriate update.bin to the mrpackages folder in the root directory of the your device.
- Install the package from within KUAL+ (use the Helper menu 'Install MR Packages')
- USB networking can be toggled by entering ;un into the search box of the menu.
- See this site to enable NDIS based USB networking on your PC
- With the default settings, the IP of the kindle is 192.168.15.244
- Connecting to the Kindle
- from Linux: ifconfig usb0 192.168.15.201 && ssh root@192.168.15.244
- from Windows:
- To connect from Windows, you'll need a remote terminal application (two of the popular choices are PuTTy & WinSCP).
- Plug in your Kindle and wait for Windows to recognise the device.
- Then go to Control Panel > Network and Internet > Network and Sharing Center > Change adapter settings. Find the Local Area Connection # with small text "Unidentified Network, RNDIS/Ethernet Gadget" below, Right click on it and click properties, choose the Internet Protocol Version 4 (TCP/IPv4) and click Properties, click "Use the following IP address" and enter IP address 192.168.15.201, and 255.255.255.0 for the subnet mask, click OK twice. (take a look at the discussion page if you have problems finding the RNDIS connection)
- Open your remote terminal application, and connect as root to the address 192.168.15.244, leaving the password empty (or use mario if all else fails).
- from FreeBSD:
- Plug in your kindle and get the device name using usbconfig |grep -i linux - it will be something like ugen0.5
- Use the device name to update config usbconfig -d ugen0.5 set_config 1
- Set the ip address use ifconfig ue0 192.168.15.201
- To set ip address automatically add this to /etc/rc.conf ifconfig_ue0="inet 192.168.15.201 netmask 255.255.255.0"
- To set the set_config setting automatically on connect find the idVendor and idProduct using usbconfig -d ugen0.5 dump_device_desc
- create file /usr/local/etc/devd/kindle.conf with the following replacing vendor and product with the values from usbconfig
- from Linux, using NetworkManager (tested using Ubuntu 18.04.1):
- Open your network settings
- Open "USB Ethernet" settings
- (Optional) In the "Identity" tab, set "Name" to something to remind you that it's your Kindle
- In the "IPv4" tab:
- Set "IPv4 Method" to "Manual"
- Under "Addresses", set "Address" to 192.168.15.201 and "Netmask" to 255.255.255.0
- Click "Apply"
- Restart the connection by disabling it and re-enabling it
notify 100 {
match "system" "USB";
match "subsystem" "DEVICE";
match "type" "ATTACH";
match "vendor" "0x0525";
match "product" "0xa4a2";
action "usbconfig -d $cdev set_config 1";
};
[edit] Automatically enabling USB network at boot
Once you've confirmed that your settings are working, just drop a blank auto file in the /mnt/us/usbnet folder. The Kindle will switch to usbnet as soon as possible during the boot process (usually during the early graphical boot: during the 'Boy Under The Tree' (without text, and without progress bar) splash screen on the Touch, and during the 'Boy Under The Tree' (with the spinner) splash screen on the PaperWhite). To get an idea of the exact timing, drop a blank verbose file in the /mnt/us/usbnet folder, the hack will then print important milestones (like when the sshd comes up) on the bottom of the screen.
Booting like this while the Kindle is plugged in might lead to undefined results. I'd recommend not plugging the device in until the switch to usbnet has been confirmed.
[edit] Preventing networkmanager to connect to device
Note: if you don't experience the following problem, you also don't have to fix it (duh!)...
On some systems, you may experience this problem: everytime you connect your Kindle in USB networking mode, the system assigns a random MAC address to it. This makes it impossible for networkmanager to identify the device. So we have to add an udev rule which assigns a new MAC address to it. Which will allow us to specify the Kindle as an unmanaged device. Optional you can set the IP address.
Create the file /etc/udev/rules.d/90-local.rules with the following content and save it.
ACTION=="add", KERNEL=="usb0", ATTRS{manufacturer}=="Linux 2.6.31-rt11-lab126 with fsl-usb2-udc", RUN+="/etc/udev/scripts/kindle"
Now create a file named kindle in /etc/udev/scripts/ and paste this litte script.
#!/bin/bash ifconfig usb0 down ifconfig usb0 hw ether 48:b3:35:3e:96:9b ifconfig usb0 192.168.15.201 ifconfig usb0 up
Make the script executable and reload the udev rules.
sudo chmod +x /etc/udev/scripts/kindle sudo udevadm control --reload
The last thing you have to do is to edit /etc/NetworkManager/NetworkManager.conf and add the following lines.
[keyfile] unmanaged-devices=mac:48:b3:35:3e:96:9b
[edit] Some useful commands for SSH
- a full rescan:
- lipc-set-prop -- com.lab126.scanner doFullScan 1
- link
- an index refresh:
- dbus-send --system /default com.lab126.powerd.resuming int32:1
- If you mix this command with Alt-Z, you may get duplicates so just stick to the command.
- Also for some reason, new documents may show up but not shown as the newest, so sort by title to find them.
- link
[edit] SSH access over Wifi
By default, SSH access over wifi is disabled. To enable it, set USE_WIFI to true in the config file (/mnt/us/usbnet/etc/config).
If you just want to enable SSH over WiFi, without switching to USB over Ethernet mode, set USE_WIFI_SSHD_ONLY to true.
[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] 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.
- To mount the Kindle's root FS to the local directory "kindle": sshfs root@192.168.15.244:/ kindle/
- To read-only mount the Kindle's root FS to the local directory "kindle": sshfs -o ro root@192.168.15.244:/ kindle/
- To unmount: fusermount -u kindle/
Adjust the above examples to your particular setup as needed.
On Windows OS you can use WinSCP from http://winscp.net to access your kindle's filesystem.
[edit] Additional command-line tools: "Extend"
This hasn't been updated in a while, and the recommended method is now to pull stuff from Debian armel.
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.
- Forum thread
- Download / Mirror
- Installation instructions are contained in the archive.
- This package supports integration with the GUI launcher (see the second screenshot above).
[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).
- Drop-in replacement optware.img files of size 60 MB / 100 MB are available here (inspired by this post)
- You can easily enlarge an image, should the need arise [2].
[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 mounted_userstore 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
sleep 7 # workaround for "Stale NFS Mount errors"
/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
[edit] App Launchers
These are programs that are used for launching other applications. See also GUI Launcher
[edit] Kindle Unified Applications Launcher
This kindlet replaces the, now outdated and non-working GUI Launcher (See below). Rather than adding a menu option to the home screen or to the reader screens the applications are presented as paged lists of named buttons inside a kindlet. The KUAL allows for the work of other developers, who had previously integrated with the GUI Launcher menu system, not to be wasted. These applications will be automatically picked up by the launcher. It supports Kindle 2, 2i , DX, 3, 4, 5, & PW in contrast to other offerings and continues to ensure that users have easy GUI access to functionality of their choosing. Installation and operation are covered on the MR thread.
[edit] (Yifan Lu's) GUI Launcher
Superseded by KUAL.
This NOW OBSOLETE mod added a new menu option to the home screen and to the reader screens. The purpose was to allow for other mods to integrate with the menu system, so that users have easy GUI access to their functionality. It only supported The Kindle touch Model FW revisions 5.0.0 - 5.1.2. It is now superseded by Kindle Unified Applications Launcher for all kindle devices. However the GUI Launcher does still work on those older firmwares... Here's how it looked:
Home Menu: 
Submenu: 
- Version 1.0.0 (Firmware 5.0.0 - 5.0.4 ONLY) - the first post of the thread contains download links, as well as source code and instructions for developers.
- Documentation: http://yifanlu.github.com/KindleLauncher/
- Update v 1.2.2 (Firmware 5.1.0 - 5.1.2 ONLY - PW users: no, it won't work on the PW!); Use the Kindle Unified Applications Launcher instead; Note: if you just want to take full advantage of all rotations, it is strongly recommended to install JBpatch as well Although again check the patches available for your Firmware revision.
- Instructions: actually, the "end user" documentation of GUI Launcher is pretty poor (both in the thread and in the README files). While the procedure is pretty standard and really simple, it's not documented for that particular software. So, here are the instructions for newcomers:
- Plug the Kindle to your computer
- Copy the update_launcher_*_install.bin file directly to the Kindle (not into documents, or any other folder)
- Safely remove the Kindle drive from your computer
- Finally, on your Kindle, choose Menu > Settings, then Menu > Update your Kindle.
[edit] Extensions for the App Launchers Launcher
Using YiFanLu's GUI Launcher or Kindle Unified Applications Launcher as the foundation, these mods add additional functionality.
[edit] Terminal Emulator
Users of kindle touch 5.3.2, 5.1.2 and paperwhite (all versions) can use KTERM to provide terminal functionality.
For firmwares lesser that or equal to 5.1.2, you can use xterm as well. NOTE THAT XTERM IS NOT SUPPORTED ANY LONGER, AND WILL NOT RECEIVE ANY FURTHER UPDATES
[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
Is not [KUAL] Kindle Unified Applications Launcher supported. http://www.mobileread.com/forums/showpost.php?p=2414240&postcount=6
[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)
This outdated extension only works on a limited range of early firmware touch machines and is not [KUAL] Kindle Unified Applications Launcher supported. TOUCH < 5.3.2 ONLY
[edit] CollectionSync
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] 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] Gnash
Open source Gnu Flash player.
Was ported for the K5. Main thread HERE
Download for GUI Launcher / Kindle Unified Applications Launcher:
Download
Site with extra info by Author is HERE
Comes with extra swf R-SIN ALARM clock
Game download availble Hexxagon[hexxagon.swf]HERE
KUAL supported, KUAL support notes are HERE
[edit] GUI Launcher Reboot
An easier-to-access reboot option. http://goo.gl/Nn4aH
The KUAL support notes for this are HERE It is NOT supported
[edit] gtksudoku
A native kindle app using gtk to provide a simple sudoku game, available from http://www.mobileread.com/forums/showthread.php?t=188997 Not Kindle Unified Applications Launcher Supported on most firmwares. Specifically: This hangs KT 5.3.2 & Paperwhites. It's known to work on KT 5.1.2.
The KUAL support notes for this are HERE
[edit] gtkMines
a native kindle app using gtk to provide a simple minesweeper game, available from http://www.mobileread.com/forums/showthread.php?p=2198434 Kindle Unified Applications Launcher supported
[edit] Komic
A Kindle comic reader: an app written in html/js to read comics on the Kindle Touch. It can be found at :http://www.mobileread.com/forums/showthread.php?t=182183
Kindle Unified Applications Launcher supported. The KUAL support notes are HERE
[edit] pbchess - chess for Kindle 2,3,DX,4, Kindle Touch, Kindle Paperwhite
Commercial program. The KUAL is supported.
pbchess is a powerful chess training program.
With pbchess you can:
- Solve chess problems (a lot of chess problems you can find on the website)
- Load and review PGN with comments/variations, analyze games, try variations
- Study chess openings, end games
- And of course - play chess (6 most famous free chess engines).
Some videos for Kindle Touch: https://www.youtube.com/playlist?list=PLB130D9CACB03C720&feature=view_all
You can download a version of pbchess for KT here: http://pbchess.vlasovsoft.net/en/index.html
pbchess for KT includes the following bonus games: Sokoban, Othello (Reversi), Checkers.
[edit] Sokoban
Bonus game to pbchess. It must be installed with pbchess. You can download a version of Sokoban for KT.
[edit] Checkers
Bonus game to pbchess. It must be installed with pbchess. You can download a version of Checkers for KT.
[edit] Othello (Reversi)
Bonus game to pbchess. It must be installed with pbchess. You can download a version of Othello for KT.
[edit] Eboard chess
Chess program with several chess engines (Crafty, GNU Chess, Stockfish and Sjeng) and possibility of playing over network on chess servers or directly with other eboard users.
You can download Eboard chess for KT here:
Kindle Unified Applications Launcher supported, the KUAL support notes are HERE
[edit] Audio Recorder and Player
Very simple exension that can record sound using the built-in microphone, and play back the last recorded file.
The KUAL Support notes for this are Here
[edit] Sudoku for the kindle touch
If you have installed ksudoku you notice quickly how much of a pain it is to type in the numbers when the onscreen-keyboard pops up. This is a sudoku game that doesn't require the keyboard to pop up. http://www.mobileread.com/forums/showthread.php?p=2097654#post2097654
Direct Download: http://www.filefactory.com/file/27x130nsxejd/n/ksudoku2_rar
and From MobileRead
Only works on Touch < 5.3.2 - Currently KUAL Untested.
[edit] Tcl/Tk application by using eTcl: Calculator Demo
You can create and run different Tcl/Tk application by using eTcl and the launcher. One example is a simple calculator.
eTcl is required and can be downloaded from http://www.evolane.com/download/etcl/linux/etcl-1.0.1-linux-arm.tar.gz
eTcl does not seem to work on PW2 (5.4.2) - the binary fails with "Illegal instruction".
Direct MobileRead Download HERE
just extract it to /mnt/us
Download the calculator zip from http://www.mediafire.com/download.php?4cwur5266ti6bzi and extract it in the extension directory.
The Calculator can easily be modified if you need additional specific math functions.
The eTcl example below all require the eTcl download HERE
[edit] eTcl: Attax
Following the same procedure described above for the calculator you can play Attax http://en.wikipedia.org/wiki/Ataxx
Download the game from http://www.mediafire.com/download.php?17ezhmaxkdabz2d and put it in the extension directory.
Direct Mobileread Download HERE
[edit] eTcl: Gems
Another Tcl/Tk game using eTcl is the classic gems or Bejeweled as it is called. Download and extract eTcl as explained for the calculator.
Download the game from http://www.mediafire.com/download.php?fklx91ku29bbw2l and put it in the extension directory.
Or Direct from Mobileread HERE
[edit] eTcl: 3DMaze
Another Tcl/Tk game using eTcl is a 3D maze. Download and extract eTcl as explained for the calculator.
Download 3DMaze from http://www.mediafire.com/?773gn53xq5i7pfb and put it in the extension directory.
Direct Mobileread Download HERE
[edit] Leafpad
This is a port of the basic text editor Leafpad. Download the zipped archive and extract it in the extension directory.
http://www.fabiszewski.net/kindle-notepad/
The KUAL support notes are HERE
[edit] Skipstone
Alternative GTK+ browser based on WebKit rendering engine.
Download Skipstone from http://www.fabiszewski.net/kindle-browser/ and put it in the extension directory.
Kindle Unified Applications Launcher supported, The KUAL support notes are HERE
[edit] KOReader
KOReader available at https://github.com/koreader/koreader/wiki is a document viewer for the Linux based eink devices. The formats it supports includes Pdf, DjVu, XPS, CBZ, FB2, TXT, HTML, RTF, CHM, EPUB, DOC, MOBI, and ZIP files.
It is compatible with KUAL and supports PDF reflow, screen rotating and many others.
Installation instructions can be found here: https://github.com/koreader/koreader/wiki/KOReader-User-Guide
[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
Change directory to a temporary working directory:
[root@kindle root]# cd /tmp
Get the latest TZ data from http://www.iana.org/time-zones (WiFi must be enabled on your kindle, otherwise you can copy TZ data-files to /mnt/us, drive visible from Windows/Linux)
[root@kindle root]# wget http://www.iana.org/time-zones/repository/releases/tzdata2014j.tar.gz
Extract timezone data-files
[root@kindle root]# tar xzvf tzdata2014j.tar.gz
Copy/Replace required data to Kindle TZ repository
[root@kindle root]# cp zone.tab /usr/share/zoneinfo/zone.tab [root@kindle root]# cp iso3166.tab /usr/share/zoneinfo/iso3166.tab
Copy related location to Kindle TZ repository, or all of them.
[root@kindle root]# cp europe /usr/share/zoneinfo/europe
Extract TZ location database
[root@kindle root]# cd /usr/share/zoneinfo/ [root@kindle root]# zic europe
Link required timezone to /etc/localtime
[root@kindle root]# zic -l Europe/Berlin
New timezone will be in place, you can verify it with "date", Kindle GUI requires restart in order to show recent modification.
Alternatively, take a look at the settz and setdate scripts that Amazon uses...
[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:
- Install the package found in this thread.
- 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)
- Enable WiFi on your Kindle
- Input ;711 in the search field on your Kindle and press enter;
- Note the IP address listed in section "4-Interface"
- 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] Screen Savers
On non-ad-supported devices, you can change the screensavers to your own ones (or even use the cover of the last book you opened!).
[edit] The Easy Way
The good old ScreenSavers hack has been ported to the K5 (Touch/PaperWhite), so your best bet is probably to check it out ;).
One of the features is the possibility to automatically use the cover of the last book you opened as the current screensaver :).
If your device is subscribed to the Special Offers, you'll have to unsubscribe (before or after installing the hack). If you can't (because you're not in the US), try contacting Kindle CS.
The rest of this section is only kept for historical reference.
[edit] The Old Way (5.0)
Yifan's excellent custom screensaver stuff, implemented as a custom blanket module, was a very nice way to implement this feature. Unfortunately, it won't work on anything other than FW 5.0.
[edit] The Other Way
On Special Offers devices, you might also be able to use your own images as a screensaver, using the same stuff mentionned above.
You'll have to disable the Special Offers first, though.
You have a few possibilities (some of which might be interpreted as somewhat more ethically gray than others... Don't shoot the messenger ;)). If your in a foreign country, where the ads make zero sense, try contacting amazon. They are very nice.
- Pay the $20 fee to unsubscribe to the Special Offers (from the US 'Manage Your Kindle' page)
- Use JBPatch
- Use the Ads Toggler GUI launcher extension
[edit] Custom Fonts
[edit] For FW 5.1/5.2 users
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:
- Antiqua
- Averia
- Bodoni
- DejaVu Serif/Serif Condensed/Sans Condensed/Sans Mono
- Fertigo Pro
- Garamond
- Georgia2
- Museo
- Palatino
- Segoe
- Times Roman
- Trebuchet
- Ubuntu/Ubuntu Mono
- Verdana
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] For PW/FW >= 5.3.x users
A slightly less user-friendly (because of some inherent drawbacks of the newer FW versions) solution is available with this Font Hack.
[edit] Manage Collections
Collections Manager: this isn't strictly a hack, but rather an application which allows to manage collections in a more versatile way than what the Kindle offers by default.
[edit] KindCalc
KindCalc: calculator application.
[edit] System!k Extensions
System!k Extensions: WAF providing quick access to hidden functions Features:
- Run Grayed out installs manually
- Prevent and Allow Screensaver button
- Show and Hide Custom cursors (With installer and un-installer)
- 711 & 411 device info pages.
[edit] Other binaries
- mplayer, mcabber, elinks, screen, tmux, ettercap, vim, strace, mlocate, tintin++ MUD client, ffmpeg, wget Scroll down to the bottom of the page to find these.
- bftpd
[edit]
[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
;fc-cache - updates fontconfig's cache, then restart the framework
;setTime - sets kindle time to unix clock
;st - alias of ;setTime (format: yyyy-mm-dd HH:MM – e.g.: ;st 2012-07-22 17:59)
~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 ";kterm" : "/mnt/us/extensions/kterm/bin/kterm.sh" (after adding a comma to the previously final line) allows you to launch Kterm from the search bar by typing ";kterm".
Note that as usual for modifications to the framework, you will need to restart the framework (e.g. by rebooting) in order for the changes to take effect.
[edit] Kindle Paperwhite Shortcuts
The above list is for the Kindle Touch. The following is an "unredacted" copy of the /usr/share/webkit-1.0/pillow/debug_cmds.json file on a Paperwhite (v 5.3.1). Note that /usr/local/bin/ does not exist on a vanilla production device, so many commands will simply have no effect at all:
";dm" : "/usr/bin/dm.sh", ";dmcc" : "/usr/local/bin/dmcc.sh", ";dh" : "/usr/bin/dh.sh", ";dt" : "/usr/bin/dt.sh", ";wifipopup" : "/usr/local/bin/wifipopup.sh", ";sandbox" : "/usr/local/bin/sandbox.sh", ";sbx" : "/usr/local/bin/sandbox.sh", ";shpm" : "/usr/sbin/shipping_mode", ";lzzl" : "/usr/sbin/shipping_mode", ";urst" : "/usr/sbin/userstore_reset", ";usbnetwork" : "/usr/local/bin/usbnetwork.sh", ";un" : "/usr/local/bin/usbnetwork.sh", ";di" : "/usr/local/bin/indexerdisable.sh", "`stopIndexing" : "/usr/local/bin/indexerstop.sh", "`startIndexing" : "/usr/local/bin/indexerenable.sh", "`disableIndexing" : "/usr/local/bin/indexerdisable.sh", "`indexStatus" : "/usr/local/bin/indexstatus.sh", ";ddc" : "/usr/local/bin/dynconfig.sh", ";resetConfig" : "/usr/local/bin/resetConfig.sh", ";rc" : "/usr/local/bin/resetConfig.sh", ";twoFingerChromeOn" : "/usr/local/bin/altChrome.sh 1", ";homeKeyChromeOn" : "/usr/local/bin/altChrome.sh 2", ";normalChrome" : "/usr/local/bin/altChrome 0", ";debugOn" : "/usr/bin/debugOn.sh", ";debugPaint" : "/usr/bin/debugPaint.sh", ";debugOff" : "/usr/bin/debugOff.sh", ";debugPerf" : "/usr/bin/debugPerf.sh", ";dP" : "/usr/bin/debugPerf.sh", ";311" : "/usr/bin/311.sh", ";411" : "/usr/bin/411.sh", ";611" : "/usr/bin/611.sh", ";711" : "/usr/bin/711.sh", ";setTime" : "/usr/bin/dateTime.sh", ";st" : "/usr/bin/dateTime.sh", "~ds" : "/usr/bin/ds.sh", ";toggleLight" : "/usr/bin/light.sh", ";fc-cache" : "/usr/bin/fc-cache.sh", ";htmlViewer" : "/usr/local/bin/htmlViewer.sh", ";installHtml" : "/usr/local/bin/installHtmlViewer.sh", ";merchant" : "/usr/local/bin/merchant.sh", ";updateCamp" : "/usr/bin/updateCamp.sh"
The following commands have been identified (source post):
;ReadingTimeOff - switches off the reading time display ;ReadingTimeOn - switches on the reading time display ;ReadingTimeReset - resets the reading time computation
[edit] Image Viewer
Only for firmware 5.1 and hopefully, later versions! This still works on Paperwhite running at 5.3.1.
Put some pictures in /mnt/us/images/ and run this command:
lipc-set-prop com.lab126.appmgrd start app://com.lab126.booklet.imageviewer
Alternativly one can call up the shell script:
/usr/bin/imageViewer.sh
Even simpler, if you install Collection Manager and switch images visible (they are by default invisible), then the Image Viewer can be accessed directly by clicking on the images.
[edit] Taking screenshots
- Kindle Touch: Hold down the home button for 2 seconds, tap the screen, and keep holding the home button for another second or two.
- Kindle Paperwhite: Press in the upper right hand corner and the lower left hand corner simultaneously. [3]
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, or use fbgrab (provided by USBNetwork).
[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, unplug the Kindle, 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
There's a button in KUAL's Helper extension that does just that ;).
[edit] Disabling Wifi network validation
By default, Kindles try to verify internet connectivity when they connect to a Wireless network. This may not be desired in various circumstances, for instance when connecting to an Intranet, or to a public hotspot.
To disable the connectivity check, place a file named WIFI_NO_NET_PROBE on the USB partition.
[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 to be written in 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
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] Window manager
awesome is used for windows management.
Related thread on mobileread.com (especially, posts #10, #11 and #13)
[edit] On-screen keyboard
On-screen keyboard is a native compiled application working through sending X Window System events with keypresses.
On-screen keyboard application files includes:
- /usr/bin/kb — executable (just a thin wrapper around of keyboard library)
- /usr/lib/libkb.so — library (implements most of functionality)
- /etc/upstart/kb.conf — for automatic starting of keyboard application
On-screen keyboard configuration files includes:
- /var/local/system/keyboard.conf — JSON file with runtime configuration (all found layouts, enabled layouts, current layout)
- /usr/share/keyboard/<locale_code>/* — keyboard layouts (and, starting from 5.1.0, XT9-related files)
Up to 5.1.0 keyboard layout directory contained three files:
- <locale_code>-600x800.keymap — layouts for portrait orientation
- <locale_code>-800x600.keymap — layouts for landscape orientation
- utils.so — "plugin" with service functions
Starting from 5.1.0 keyboard layout directory contains:
- <locale_code>-600x800.keymap.gz — layouts for portrait orientation
- <locale_code>-800x600.keymap.gz — layouts for landscape orientation
- utils.so — "plugin" with service functions
- libpredictor.so — intermediate library providing typing prediction (stock libpredictor.so uses bundled XT9 engine)
- <locale_code>.kdb / *.ldb — XT9-related files (dictionaries, databases)
- <locale_code>-758x1024.keymap.gz and <locale_code>-1024x758.keymap.gz — unused layouts (it should be artifacts of supporting future models of Kindle with HD screen)
Keymap files are simple JSON files. Their's structure is unchanged in 5.1.0, though some values (default font size, paths to images displayed on some keys) were changed. Obviously, they are gzipped in 5.1.0.
utils.so is mandatory. It is mostly the same between layouts. Only some strings are changed, for example: in utils.so from Italian keyboard these strings are kb-it and Italian. First is a locale code of keyboard with prefix kb- (or, maybe, prefix is unrelevant). It is used as ID of this keyboard. Second is a name of keyboard.
libpredictor.so is optional (even in 5.1.0). Keyboard layout will work fine without it.
[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("Not saying it!!!\n");
return 0;
}
- Get this, compile the GNU Toolchain yourself, or just install gcc-4.6-arm-linux-gnueabi.
- arm-none-linux-gnueabi-gcc helloworld.c -o hello or(on ubuntu) arm-linux-gnueabi-gcc-4.6 helloworld.c -o helloworld
- Send it over to your kindle (I'm not your priest, you know how you transfer your stuff)
- chmod +x hello
- ./hello
See also #GCC_cross-toolchain.
[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] LIPC Lua bindings
The easiest way to write LIPC-enabled program is to use Lua. Here is a sample Lua script:
local lipc_handle, error_message, error_number = lipc.init("com.example.script")
if not lipc_handle then
print("Failed to initialize LIPC: (" .. tostring(error_number) .. ") " .. error_message)
os.exit(error_number)
else
lipc.set_error_handler(function(error) print(error) end)
end
local readonly_property = lipc_handle:register_string_property("readonly", "r")
readonly_property.value = "readonly"
local property = lipc_handle:register_int_property("property", "rw")
property.value = 0
property.listener = function (name, value)
print("Changed property " .. name .. " to " .. tostring(value) .. ".")
end
lipc_handle:subscribe("com.example.otherscript", "some_event", function(ev_source, ev_name, ev_params)
print("Received event " .. ev_name .. " from " .. ev_source .. " with parameters:")
for i, param in ipairs(ev_params) do
print("* " .. tostring(param))
end
end)
-- run event loop with timeout of Infinity seconds
while true do lipc.run_event_loop(math.huge) end
Here is an output of introspection script:
print("lipc namespace members:")
for name, value in pairs(lipc) do
print("* " .. name .. ": " .. type(value))
end
print()
lipc_handle = lipc.init("com.example.introspection")
print("lipc object members:")
for name, value in pairs(getmetatable(lipc_handle)) do
print("* " .. name .. ": " .. type(value))
end
lipc_handle:close()
lipc namespace members:
lipc object members:
|
Example of LIPC Lua bindings usage could be found in /etc/xdg/awesome (on the device) with the command:
[edit] LIPC C bindings
It is also possible to incorporate LIPC functionality into the C source code via the reverse-engineered library header file. The simplest usage might be as follows:
#include <stdio.h>
#include <openlipc.h>
int main()
{
LIPC *lipc;
char *status;
if ((lipc = LipcOpenNoName()) == NULL)
return 1;
if (LipcGetStringProperty(lipc, "com.lab126.powerd", "status", &status) == LIPC_OK)
puts(status);
LipcClose(lipc);
return 0;
}
[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]
- disable WiFi: lipc-set-prop com.lab126.cmd wirelessEnable 0
- enable WiFi: lipc-set-prop com.lab126.cmd wirelessEnable 1
[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:
- lipc-set-prop com.lab126.appmgrd start app://com.lab126.booklet.home -- return to home screen
- lipc-set-prop com.lab126.appmgrd start app://com.lab126.booklet.settings?diagnosticMode=\;411 -- start settings activity. Because of the appended parameter, this goes directly to the 411 diagnostic screen (device info)
[edit] Changing screen orientation
lipc-set-prop com.lab126.winmgr orientationLock L -- use U,D,L, or R to set the desired orientation. Works for me!
[edit]
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]
- disable: /usr/bin/sqlite3 /var/local/appreg.db "update properties set value='hidden' where handlerid='com.lab126.EndActions' and name='viewModes'"
- restore: /usr/bin/sqlite3 /var/local/appreg.db "update properties set value='windowed hidden' where handlerid='com.lab126.EndActions' and name='viewModes'"
More info: http://www.mobileread.com/forums/showthread.php?p=2022528#post2022528
[edit] Showing/hiding Keyboard
- show: lipc-set-prop -s com.lab126.keyboard open <destination>:<mode>:<flag>
mode is one of: abc, Abc, 123, web, pad Flags are:
- 0 - DEFAULT
- 1 - COMPOSITION_ENABLED
- 2 - AUTOCAPITALIZE
- 4 - CLIENT_DISABLED
They coud be unioned through binary OR (for example, flag 3 will enable both COMPOSITION_ENABLED and AUTOCAPITALIZE, as 3 = 1|2). [4]
- hide: lipc-set-prop -s com.lab126.keyboard close <destination>:<mode>:<flag> Note: does not work?
[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.
- To reload much of the configuration, issue restart framework.
- A more brutal way is to killall cvm.
As described above, the Java subsystem provides LIPC handlers both for services, and for providing the UI -- so-called Booklets.
[edit] Remote Debugging
- Easy way: Go to USB mode and mount on the Kindle's USB drive, make an empty text file named "DEBUG_CVM_JDWP". Then restart and switch to usbnetwork mode. You debug with usbnetwork's IP, port 8000. Other file names supported are DEBUG_CVM_JDWP_SUSPEND (suspend on start, waiting for debugger to connect before continuing) and PROFILE_CVM_NB (enable netbeans profiling on port 5140).
- More customizable: edit /etc/upstart/framework directly and tweak there. Might be useful if you need to change MinimumKindletTimeoutMillis.
[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:
- copy all jars from /opt/amazon/ebook/ (and subdirectories) to your computer.
- Install eclipse, jad, and jadclipse, or JD-Eclipse (note: JD-Eclipse does not install or work correctly ATM), or use this update URL directly in eclipse ("Eclipse class Decompiler" by Chao Chen, works smoothly with Eclipse Juno).
- Plug it all together, and you can essentially interactively browse the source code.
- Another helpful strategy is to extract all jars into a common directory, so you can grep etc. on the files.
The KT jars are (as of version 5.0.1) only partially obfuscated -- most importantly, class, method, and many constant names are intact.
A Windows tool (written by member wl.) can be used to de-obfuscated fields and variable names in a class. Download it at http://www.mobileread.com/forums/showthread.php?p=2096039 and run it to de-obfuscate all *.class files in its folder and sub-folders.
For decompiling Java classes, you can try JD-GUI which supports up to Java 7 and it also has plugins for Eclipse and IntelliJ. jad can't decompile some jars from firmware 5.1.2 of Kindle Touch.
[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] Java Code, that will not work
- String-Concatenation via the +-operator
- Generics
[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)
[edit]
In that directory, two html pages can be found, namely:
- The built-in media player
- The built-in Wifi configuration dialog.
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 flexible 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] Over-the-air (OTA) updating internals
- todo process (/usr/bin/todo, /etc/upstart/todo.conf) pulls service info from Amazon server. URL for getting info is built with the help of supporting libraries, through which some parameters are taken from SQLite database at /var/local/appreg.db. There is software revision in service info URL's query string and in separate HTTP request header. Value for query string is taken from table properties from row with handlerId = 'urlbuilder.gparams' and name = 'software_rev'. Value for header is taken from table properties from row with handlerId = 'urlbuilder.headers' and name = 'X-ADP-SW'.
- server checks client KT software version (from HTTP request query string and/or header) and, if needed, adds to service info message about available OTA update
- if service info contains message about available OTA update, todo sends it to lipc service, which is defined by appropriate values in service message (values GET, FWUO). todo is looking for these values in it's internal handler registry (which is built and cached in RAM at todo startup from content of /etc/todo/handler_registry.conf). For legacy.GET.FWUO com.lab126.ota service is defined, so todo sends message to com.lab126.ota by setting lipc property handleToDoItem
- service com.lab126.ota is provided by otaupd process (/usr/bin/otaupd, /etc/upstart/otaupd.conf), so this daemon handles downloading and checking validness of downloaded update bundle
- after downloading and checking for validness of downloaded update bundle, otaupd invokes ota-update upstart script (/etc/upstart/ota-update.conf) with path to bundle as parameter
- on successful/failed OTA update install otaupd reports back to todo, which is sending status back to Amazon (no new information is sent to Amazon here except of fact of success/fail)
[source]
[edit] Blocking Official Updates
This nicely leads us to answer the "How Do I Block Official Updates?" question, which is something you might want to do if you want to avoid official updates breaking compatibility with your stuff (or simply because you're tired of reinstalling everything after a >= 5.3 update).
What's just been explained has been leveraged in the [BackDoor Lock] Hack, which prevents official updates on a wide range of Kindle models, but a simple solution also exists (on pre-5.6.x firmwares only), by simply [reserving the temp download filename]... ;).
You can use both, to be extra careful on firmwares prior to 5.6.x series -- Amazon did get smart and "fixed" the temp download filename block in the 5.6.x series firmare; Hopefully, they won't also "fix" the BackDoor Lock hack in later versions.
[edit] Boot over USB HID serial / USB downloader mode
The Freescale i.MX508 MCU used in the Kindle Touch supports a "USB downloader" boot mode.
When this 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 the Reference Manual. The protocol allows to read/write memory, upload program image into RAM and start executing at given address.
To enable this mode: perform a "hard reset" by holding the power button until the LED turns off. Keep holding the power button, and in addition press the home button. Then wait about a second, release the power button, wait another second and release the home button.
This mode is described in section 6.9.1 (page 473) of the i.MX50 Reference Manual.
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 can 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
[edit] Building U-Boot binaries from Amazon's Sources
Below is essentially a log of the steps that I had to take on Ubuntu 10.04 to build U-Boot. The documentation is not overly verbose, but it's better than nothing at all. As always, your mileage may vary, so adapt this to your setting - meaning: you may need to install other packages, or you may need to skip or adapt a few steps.
# Download the source code from Amazon. Unpack the u-boot part into its own directory. # Download and install the required toolchain: sudo add-apt-repository ppa:linaro-maintainers/toolchain sudo apt-get update sudo apt-get install gcc-4.6-arm-linux-gnueabi # create a required symlink sudo ln -s /usr/bin/arm-linux-gnueabi-gcc-4.6 /usr/local/bin/arm-linux-gnueabi-gcc # Toolchain installation is complete, now configure U-Boot: # Make sure that you are inside the uboot directory. # Before trying to compile U-Boot, copy the file boardid.h # from linux-2.6.31.tar.gz (directory include/) into the include/ subdirectory # of the uboot directory. # # Note: If there isn't a boardid.h in linux/include you can fetch it from a previous # source release. As of Mar 29, 2016 the most recent boardid.h is in Kindle_src_5.6.2.1_2634390002 TYPE=prod make CROSS_COMPILE=arm-linux-gnueabi- imx50_yoshi_config TYPE=prod make CROSS_COMPILE=arm-linux-gnueabi-
[edit] GCC cross-toolchain
Source code archive provided by Amazon contains Makefile for building the same GCC cross-toolchain as was used by Amazon.
It could be found at least in Kindle_src_5.3.7_2004410010.tar.gz on Source Code Notice page. Makefile and instructions (in file BUILD_HOW-TO.txt) are contained in build_linaro-gcc_4.5.4.tar.gz in source code archive.
However, some links in Makefile are outdated. Here is a patch for fixing links:
+++ b/Makefile 2014-01-19 00:00:00.000000000 +0000
@@ -37,7 +37,7 @@
BUILD_SYSROOT = $(CURDIR)/build/sysroot
# Where to fetch the packages from
-MIRROR = http://ports.ubuntu.com/
+MIRROR = http://old-releases.ubuntu.com/ubuntu/
# Set the pre-built headers and libc to build against.
LIBC6_VER = 2.12.1-0ubuntu6
@@ -92,7 +92,7 @@
# Fetch the binutils tarball from Ubuntu archive
$(BINUTILSSRC): $(stamp)init-dirs
- curl $(CURLFLAGS) -o $@ http://archive.ubuntu.com/ubuntu/pool/main/b/binutils/$(@F)
+ curl $(CURLFLAGS) -o $@ http://old-releases.ubuntu.com/ubuntu/pool/main/b/binutils/$(@F)
# Extract
$(stamp)binutils-extract: $(BINUTILSSRC)
BUILD_HOW-TO.txt lists texinfo (Version: 4.13a.dfsg.1-5ubuntu1) as a build dependency. But recent Linux distrubutions contains newer texinfo version, so build (of both binutils and gcc) will fail (example of errors are shown on http://bugs.debian.org/697353).
Most practical solution is to get https://ftp.gnu.org/gnu/texinfo/texinfo-4.13a.tar.gz, compile it, then add binary directory to to $PATH, export $PATH and compile toolchain.
One may instead try to apply patches attached to http://bugs.debian.org/697353#32, http://bugs.debian.org/704586#16 and http://bugs.debian.org/704586#21 (but these are patches for binutils only, similar patches for gcc are required too) or just build newer version of binutils, compatible with newer texinfo (like binutils 2.24).
[edit] Using Clang as a compiler with Amazon's cross-toolchain
Amazon's cross-toolchain could be used with Clang (as tested on Debian clang version 3.4-1 (tags/RELEASE_34/final) (based on LLVM 3.4)).
Use this script as an example of required clang options:
clang \
-target arm-linux-gnueabi \
-mfloat-abi=softfp \
-march=armv7-a \
-mthumb \
-mtune=cortex-a8 \
-mfpu=neon \
--gcc-toolchain="${TOOLCHAIN_DIR}" \
--sysroot="${TOOLCHAIN_DIR}/arm-linux-gnueabi" \
-B"${TOOLCHAIN_DIR}/bin" \
$*
--target is used for enabling cross-compilation. --m* options are used for selecting KT's SoC architecture to compile for. --gcc-toolchain points to toolchain. --sysroot is for constraining headers searching paths. -B option sets path for searching assembler and linker binaries.
To compile with Clang in C++11 standard mode, apply following patch to croos-toolchain (fixes are got from GCC 4.7.2 and adjusted because GCC 4.5.4 used in Amazon's toolchain doesn't support noexcept keyword):
arm-linux-gnueabi/include/c++/4.5.4/exception_ptr.h | 2 +-
arm-linux-gnueabi/include/c++/4.5.4/nested_exception.h | 18 ++++++++++++++----
2 files changed, 15 insertions(+), 5 deletions(-)
diff --git a/arm-linux-gnueabi/include/c++/4.5.4/exception_ptr.h b/arm-linux-gnueabi/include/c++/4.5.4/exception_ptr.h
--- a/arm-linux-gnueabi/include/c++/4.5.4/exception_ptr.h
+++ b/arm-linux-gnueabi/include/c++/4.5.4/exception_ptr.h
@@ -129,7 +129,7 @@ namespace std
operator==(const exception_ptr&, const exception_ptr&) throw()
__attribute__ ((__pure__));
- const type_info*
+ const class type_info*
__cxa_exception_type() const throw() __attribute__ ((__pure__));
};
diff --git a/arm-linux-gnueabi/include/c++/4.5.4/nested_exception.h b/arm-linux-gnueabi/include/c++/4.5.4/nested_exception.h
--- a/arm-linux-gnueabi/include/c++/4.5.4/nested_exception.h
+++ b/arm-linux-gnueabi/include/c++/4.5.4/nested_exception.h
@@ -42,6 +42,10 @@
# error This platform does not support exception propagation.
#endif
+#ifndef __has_feature
+ #define __has_feature(x) 0 // Compatibility with non-clang compilers.
+#endif
+
extern "C++" {
namespace std
@@ -57,13 +61,21 @@ namespace std
exception_ptr _M_ptr;
public:
+#if __has_feature(cxx_noexcept)
+ nested_exception() noexcept : _M_ptr(current_exception()) { }
+#else
nested_exception() throw() : _M_ptr(current_exception()) { }
+#endif
nested_exception(const nested_exception&) = default;
nested_exception& operator=(const nested_exception&) = default;
- inline virtual ~nested_exception();
+#if __has_feature(cxx_noexcept)
+ virtual ~nested_exception() noexcept;
+#else
+ virtual ~nested_exception();
+#endif
void
rethrow_nested() const __attribute__ ((__noreturn__))
@@ -74,8 +86,6 @@ namespace std
{ return _M_ptr; }
};
- inline nested_exception::~nested_exception() = default;
-
template<typename _Except>
struct _Nested_exception : public _Except, public nested_exception
{
@@ -119,7 +129,7 @@ namespace std
// with a type that has an accessible nested_exception base.
template<typename _Ex>
inline void
- __throw_with_nested(_Ex&& __ex, const nested_exception* = 0)
+ __throw_with_nested(_Ex&& __ex, const nested_exception*)
{ throw __ex; }
template<typename _Ex>
Toolchain's C++ standard library doesn't fully support C++11 features, but new syntax should be working. For example, this program compiles and runs without errors (with clang++ -std=c++11 <...>):
#include <vector>
int main() {
std::vector<int> vec = {1,3,3,7};
for (auto v: vec) {
std::cout << v;
}
std::cout << std::endl;
}
With Clang 3.4 and -std=c++1y even this compiles:
auto fun() {
return 1'000'000;
}
int main() {
std::cout << fun() << std::endl;
}
[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.
And here is i.MX Android Firmware Developers Manual (Very Good) (LINK DEAD, try http://blog.sina.com.cn/s/blog_72dcef220100yf9i.html )
Freescale also provides Android demo images for i.MX50: http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=IMX50_SW
[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.
Newer and better alternatives:
[edit] Collections on unregistered devices
NOTE: A much simpler alternative is to use the Collections Manager (see above). It also works when your device is not registered.
NOTE 2: Here is an update package that will fake-register your device. It has been verified to work. Simply unzip it and follow the simple instructions in Readme_eng.txt.
The description below may be overly verbose. To summarize, you simply have to create the file /var/local/java/prefs/reginfo with the info given below.
Also note that this will only work as long as you NEVER turn on network connectivity on the Kindle.
- Question: Elaboration please: what exactly will happen if connectivity is turned on?
- Answer: The reginfo file will be deleted because it is determined to be invalid. This, in turn, will also disable the ability to manipulate collections using the "normal" firmware functionality.
Enter diagnostic mode (create the file ENABLE_DIAGS in the root directory) and reboot. Within the diagnostic mode, enable USB networking. Bring up USB networking on an attached computer. Use SSH to connect to the device at address 192.168.15.244. Login as root with password mario. Execute "vi /var/local/java/prefs/reginfo". Enter and save the following text:
<?xml version="1.0" encoding="UTF-8"?> <response> <user_device_name>WhateverName</user_device_name> <global_device_name>WhateverName</global_device_name> <given_name>WhateverName</given_name> <name>WhateverName</name> <alias>WhateverName</alias> </response>
Disable diagnostics and reboot. Collections are now enabled.
If using a Linux machine to connect to the Kindle, the specific commands after enabling USB networking on the Kindle would be as follows. First, as root:
modprobe cdc_ether #(if necessary) ifconfig usb0 up ifconfig usb0 192.168.15.201 ping 192.168.15.244 #(just to confirm that the network functions)
Now as a user:
ssh root@192.168.15.244 #(provide password mario when prompted)
You're now logged into the kindle, which also runs linux. So:
vi /var/local/java/prefs/reginfo
Vi is a little arcane. Press "i" to enter insert mode. Enter the XML given above. When finished, press "Esc" to exit insert mode. Save and exit with ":wq" (ie command write and quit).
exit (to log out)
Take the Kindle out of diagnostic mode and reboot.
It would be possible to do the above using a Windows computer as well, but you'll need third-party applications for ssh and maybe even usb networking. Sigh: Windows. On a Mac, the terminal commands should be more or less identical, although I'm not sure about the cdc_ether kernel module. Have fun!
[edit] Creating custom packages
To create custom update packages, you'll have to use KindleTool (which itself is a fork of yifan's original KindleTool). For those familiar with K2/K3 hacking, it's the successor of the kindle_update_tool.py Python tool we know and love ;).
This thread is its current home in the forums ;).
KindleTool is designed to run on Unix based systems, so it doesn't always play nice on a vanilla Windows. However, it is easy to set up on Linux and OSX, and even via MinGW or Cygwin on Windows.
These directions may not always be up to date, when in doubt, refer to the COMPILING file ;).
To build it on Linux:
If you're running Gentoo, simply use this portage overlay, or put the ebuild in your local overlay as dev-util/kindletool ;).
If you're running Arch Linux, simply use the kindletool or kindletool-git package from the AUR.
- Make sure you have a viable toolchain setup (
gcc,make,autotools,libtool, ...) - Install
zlib-dev,nettle-devandlibarchive-dev - Get the source code for KindleTool from GitHub, cd to it in shell, and type
make - If gcc throws a fit about libarchive being too old, you'll have to build libarchive-3 yourself, and then put the includes (archive.h & archive_entry.h) in KindleTool/includes, and the static lib (libarchive.a) in KindleTool/lib. Also, you may want to ping your distro maintener to update their libarchive package ;).
(For recent-enough Debian based distro, an all-in-one command for steps 1.-2. is sudo apt-get install build-essential nettle-dev zlib1g-dev libarchive-dev)
- If you just want a binary:
- Download the latest static build for your arch.
- Extract it, and run the tool from shell
To build it on OSX:
- Use Homebrew with this tap ;).
(You can also do it the hard way: install nettle & libarchive via Homebrew, and then build KindleTool via XCode or make).
- If you just want a binary:
- Download the latest osx static build.
- Extract it, and run the tool from Terminal
To build it on Windows:
- Install Cygwin
- Install the required packages for a proper Cygwin toolchain (
gcc4,binutils,autoconf,automake,libtool,make, ...) - Install the packages:
libnettle4/libnettle-devel,zlib/zlib-devel,git,cmake,patch,pkg-config - Compile and install libarchive >= 3.0.3 (I usually use a minimal build configured with
--prefix=/usr --enable-static --enable-shared --disable-xattr --disable-acl --with-zlib --without-bz2lib --without-lzmadec --without-iconv --without-lzma --without-nettle --without-openssl --without-expat --without-xml2) - Get the source code for KindleTool from GitHub, cd to it in Cygwin's shell, and type
make- (For the most adventurous, you can also cross-compile a native binary with a MinGW toolchain ;))
- If you just want a binary:
- Download the latest mingw static build.
- Extract it, and run the tool from your favorite shell (or cmd.exe, but NOT Cygwin's shell)
- Alternatively, if you encounter weird issues with the native build, try the Cygwin build:
- Install Cygwin
- Install the packages:
libgcc1,libnettle4andzlib0 - Download the latest cygwin static build.
- Extract it, and run the tool from Cygwin's shell (NOT command prompt)
[edit] Usage
Run the tool with no arguments for a detailed usage guide, or check the README or the manpage.
[edit] Example
Let's say you want to run a script run.sh on the device which extracts data.tar.gz to the Kindle.
- Move everything to a directory, let's say
~/kindle - cd into
~/kindle - Run the tool (assuming it's in your $PATH):
kindletool create ota2 -d k5w -d k5g -d k5gb run.sh data.tar.gz update_custom_script.bin
This creates an update package that will run on all known Kindle Touch models.
For more detailed examples, you're welcome to check the build-updates.sh script in NiLuJe's hacks.
[edit] Limitations
- Packages created for Kindle 4.0 and above (OTA V2) will not work on Kindle 3.X and below (and vice versa).
- Packages created for Kindle 3.X and below (OTA V1) can only support one device. You must create a separate package for each device.
- Packages created for Kindle 4.0 and above (OTA V2) can support more than one device, but because of a bug (or maybe on purpose) on Amazon's implementation, packages created for Kindle 4.0 cannot run on Kindle 5.0 and vice versa
- Packages created for Kindle 4.0 and above (OTA V2) support having metadata strings, but because of a bug in Amazon's implementation, these packages will not run!
