The standard way of installing custom software to a Kindle device is by using its update*.bin installer files. In the old days (K2/K3) you had the help of kindle_update_tool.py by jyavenard. But for Paperwhite we got help from the kindletool by NiLuJe. There is a whole thread about packing/unpacking the Kindle update files written by NiLuJe here. Please be sure to read this thread to understand how the tools used for this tutorial work.

 

Overview

  1. Read thread about packing/unpacking Kindle update*.bin by NiLuJe here
  2. Download ressources (see below)
  3. Prepare environment
  4. Create update_*.bin file

 

Tutorial

1. Read thread about packing/unpacking Kindle update*.bin by NiLuJe


2. Download ressources

Download and unzip this files somewhere on your system


3. Prepare environment

3.1 Setup PATH

To use kindletool from anywhere in your system you best add it to the PATH variable. On Mac OS X this might look as follows

export PATH=$PATH:/Volumes/Data/dev/kindle/kindletool-v1.5.5.1-osx


4. Create update_*.bin file

After you added kindletool to the PATH you can run the build-updates.sh script from the kindle-dummy project. This creates a basic installer bin with a script attached. By default this script does really nothing but generates more of a logfile of the device.

On my MacBook I had to change the build-updates.sh according to this

--- build-updates.sh     2009-05-08 17:22:51.000000000 -0700
+++ build-updates_orig.sh        2009-07-19 14:44:08.000000000 -0700
@@ -21,0 +21,0 @@ # We also need GNU tar
-TAR_BIN="tar"
+TAR_BIN="gnutar"
...

--- build-updates.sh 2009-05-08 17:22:51.000000000 -0700 +++ build-updates_orig.sh 2009-07-19 14:44:08.000000000 -0700
@@ -29,0 +29,0 @@ # Create the utils tarball
-${TAR_BIN} --owner root --group root -cvzf utils.tar.gz consts ui
+${TAR_BIN} --owner root --group 0 --numeric-owner -cvzf utils.tar.gz consts ui

After a successful build you can try to install the update_dummy_0.0.N.bin file by uploading it to /mnt/us. After the "update" process you should then see the file dummy_testupdate.log in /mnt/us.

 

Credits

  • Original tutorial by NiLuJe
  • Amendments for Kindle Paperwhite (K5) / FW 5.3.5 / API 2.2 by Kim Hauser

Other articles in this category

Background

This tutorial was made with the following environment

Dev Environment MacBook Pro, OS X Mountain Lion
Eclipse, ANT
Kindle Device Paperwhite (K5)
Firmware version 5.3.5
API version 2.2 (Kindlet-2.2.jar)

 

I wanted to start with a Hello World example for my own Kindlet. So I asked Google and it pointed me to http://cowlark.com/kindle/getting-started.html. Even though this page seems to provide a good basic knowledge about Kindle development it is about Kindlet-1.2.jar - so the example didn't work out of the box for me. I had to ask Google a little more to get all the changes for Kindle API 2.2. That's why I wrote this Hello World V2 Example. It is basically a copy of the Hello World example from cowlark.com with all changes needed for Kindle API V 2.2 (Kindlet-2.2.jar). In addition it shows you the usage of KMenu (Kindle Menu) and KOptionPane.showMessageDialog (Message Box). This tutorial also explains how to do some automated tasks manually as the installers from cowlark are all for older Kindles and do not work on the Paperwhite. But for the understanding please be sure to read and understand http://cowlark.com/kindle/getting-started.html before you go through this tutorial.

 

Overview

  1. Read and understand http://cowlark.com/kindle/getting-started.html
  2. Extract libraries from Device
  3. Create developer keys and merge keystores
  4. Amend source code to compile against Kindlet-2.2.jar
  5. Compile, pack and sign source
  6. Upload azw2 to device

 

Tutorial

1. Read fundamentals

Please read http://cowlark.com/kindle/getting-started.html first!

 

2. Extract libraries from Device

To build your source against the Kindle API you first have to get some files from the device. You can do this manually or (with older Kindle versions) with a little help of the library extractor tool of cowlark.

The kindle library extractor from http://cowlark.com/kindle/getting-started.html didn't work for me as it had no installer.bin for Paperwhite (also none of the other ones worked). But getting the libs manually is no problem. The Main KDK jar is located at /opt/amazon/ebook/lib/Kindlet-2.2.jar. cowlark.com advises you to copy all the jars in this folder - but until now I never used more than the Kindlet-2.2.jar. It depends what you want to do ;) Anyhow for this tutorial you only need Kindlet-2.2.jar. Later on you then have to include this jar into the project build path of your project so the compiler/linker can build against.

 

3. Create developer and public keys and merge keystores

To successfully run your Kindlet on a device you have to sign the project with your developer key. The public key must also be installed on the device you want to run the Kindlet. You can create the keys by yourself.

We use the keygen-0.1 tool (from http://cowlark.com/kindle/getting-started.html) to generate a key pair for our user. This tutorial assumes you use a password of password for your keystores. Just execute the keygen script and follow the advice on the screen. As a result you should get two files. A developer.keystore and a public.keystore - use these files for signing the project (developer part) and upload to target device (public part)

 

3.1 Local installation of keystore

Copy new developer.keystore to ~/.kindle/kindle.keystore

 

3.2 Install keystore on remote

Because the keygen creates no installer.bin for the paperwhite you have to merge the keystores manually. This involves a few more steps than the local installation but we got help from a tool. This is done by the Java keytool (keytool-Key and Certificate Management Tool). Basically the steps are simple.

  1. Download developer.keystore from Device (/var/local/java/keystore/)
  2. Make a backup copy of the .keystore files (original and new one)
  3. Merge remote developer.keystore and new public.keystore locally with keytool (See syntax below)
  4. Upload the merged keystore to /var/local/java/keystore/ (Replace or better rename old developer.keystore)

Syntax keytool:

keytool -importkeystore -srckeystore public.keystore -destkeystore developer.keystore

Important!

You have to restart the device after you changed the keys

  

4. Amend source code to compile against Kindlet-2.2.jar

You can download the final product of this tutorial below (Source & Downloads) or you can download the original HelloWorld from http://cowlark.com/kindle/HelloWorld.zip and amend the source to compile against Kindlet-2.2.jar.

 

4.1 Detailed amendments

4.1.1 Main.java

Basically the only thing you have to change here is the KTextArea. In API 2.2 it does not exist anymore. But we can safely use JTextArea. Your source could look something like this:

 

import com.amazon.kindle.kindlet.KindletContext;
import javax.swing.JTextArea;
import com.cowlark.kindlet.KindletWrapper;

public class Main extends KindletWrapper {
  JTextArea kta = null;
  
  @Override
  public void onKindletStart() {
      KindletContext context = getContext();
      kta = new JTextArea("Hello World V2 example for Kindlet-2.2.jar");
      context.getRootContainer().add(kta);
  }
}

 

4.1.2 Manifest file

The projects manifest file for API 2.2 has 3 more properties you have to set. If you fail to you get a compiler error. The manifest should read as follows:

 

Manifest-Version: 1.0
Main-Class: ch.kimhauser.kindle.helloworldv2.Main
Implementation-Title: HelloWorldV2
Implementation-Version: 1
Implementation-Vendor: Kim David Hauser
Extension-List: SDK
SDK-Extension-Name: com.amazon.kindle.kindlet
SDK-Specification-Version: 2.1

 

4.1.3 Extension: Usage of KMenu and KOptionPane.showMessageDialog 

Adding a menu to the top left standard menu is a piece of cake. Use a new KMenu and add MenuItems to it in onKindletStart. When you're done you can use the setMenu function on the KindletContext. The menu then will be appended to the existing one(s). You can use an ActionListener on the menu items to catch the selection event. This example shows you the Action command of the selected menu item with a message box (KOptionPane.showMessageDialog). The source looks like this:

 

public class Main extends KindletWrapper implements ActionListener {

@Override
public void onKindletStart() {
    KindletContext context = getContext();

    KMenu mnu = new KMenu();
    mnu.add("Example Menu", this);
    context.setMenu(mnu);

...

@Override
public void actionPerformed(ActionEvent arg0) {
    KOptionPane.showMessageDialog(getContext().getRootContainer(), "Action command: " + arg0.getActionCommand());
}

 

5. Compile, pack and sign source

To compile the project you can either import the ant build.xml into Eclipse (via menu New > Project > Java > Project from existing Ant Buildfile) and build it with Eclipse (Create a new builder: Project properties > Builders > New > Antbuilder) or run the makekindlet script directly from within console if you have ant installed on your system

 

5.1 Makefile

The makekindlet script will compile the project and create a signed azw2 file you can upload to your device. It looks like this

 

#!/bin/sh
FILENAME=HelloWorldV2
KEYSTORE=$HOME/.kindle/kindle.keystore
JAR=$FILENAME.azw2
MANIFEST=$FILENAME.manifest

ant jar

cp $FILENAME.jar $JAR

jarsigner -keystore $KEYSTORE -storepass password $JAR dk$USER
jarsigner -keystore $KEYSTORE -storepass password $JAR di$USER
jarsigner -keystore $KEYSTORE -storepass password $JAR dn$USER

 

6. Upload azw2 to device

If everything has gone well you now should be ready to upload the created azw2 file to the device at /mnt/us/documents. For example you can use the following commands to modify the above script

 

ssh This email address is being protected from spambots. You need JavaScript enabled to view it. rm -f /mnt/us/documents/$JAR
scp $JAR This email address is being protected from spambots. You need JavaScript enabled to view it.:/mnt/us/documents

 

Source & Downloads

 

Credits

  • Original tutorial by http://cowlark.com
  • Amendments for Kindle Paperwhite FW 5.3.5 by Kim Hauser

Other articles in this category

Kindle Paperwhite
I was inspired by my sister as she had one for her studies and pleasure. One day I saw her playing around with it and asked her to show me what this all about. She showed me everything and I soon came to the conclusion that this little e-reader might be capable of more than just reading books so I started to investigate in the net. I found a whole community about kindle development. I was overwhelmed by the sheer amount of information about this topic out there. Unfortunately most of the articles for making you own Kindlets and such where obsolete and made for older versions of the Kindle API.

Here you see a collection of my and also others or amended tutorials and information about Kindle Paperwhite development.

 

Tutorials

 

Tips & Tricks

 

Resources (Development)

 

Other Tools

 

Original Post

Amazon is getting regular logs / sysinfos from all Kindle devices. This is done by the device it self. It collects information about your doings and syslogs and then from time to time it will send a compressed file with all this collected data to Amazon. I came across this by reading this article by ebs. The post also shows you what for example the Kindle device sends to Amazon. It tracks what you read, at which position you are in the book and where you are physically - just to name a few samples.

 

090719:144532 cvm[26415]: I BookletManager:SwitchingBooklets:from=Home,to=Bookworm:
090719:144532 cvm[26415]: I Reader:BOOK INFO:title=Kindle DX User's Guide,authors=Amazon.com,ASIN=B0026P3LT
E,content type=ebook,publisher=Amazon.com,publication date=4/25/2008,sorted title=Kindle DX User's Guide,display a
uthors=Amazon.com,length=MobiPosition_ 211399,last access=1980-01-01 00.00.00 +0000,last read position=MobiPositi
on_ 12977,isEncrypted=false,isSample=false,isNew=false,path=/mnt/us/documents/Kindle_Users_Guide.azw,isTTSMetda
taPresent=false,isTTSMetadataAllowed=true:
090719:144534 cvm[26415]: I ReaderGUI:SWITCH VIEW:name=com.amazon.ebook.booklet.reader.gui.lf:

...

090719:161519 wand[1661]: I e725:diag: t=4a644ff6,SID=4183,NID=87,
Base ID=744,Network Svc Type=EVDO,Bars=5,
Latitude=37.321441,Longitude=-122.030612,
RSSI dBm=-125,Active Set EC IO dBm=-31.500000,Active Set PN Offsets=264,
HDR Latitude=37.334167,HDR Longitude=-122.031113,
EVDO RSSI dBm=-65,ASET Pilot Energy=-0.53,
HDR Active Set PN Offsets=264,DRC=2,n=1:

(Example content of log sent to Amazon)

 

Solution

Ebs provided a way to suppress this log file exchange. He disables the creation of the log files on the device through patching the file /usr/bin/showlog. However, the file looks different on a Paperwhite than in the post of ebs so I investigated a little. I found that if you want to apply this patch on a Paperwhite (FW 5.3.5) you have to change the files according to this.

 

--- showlog     2009-05-08 17:22:51.000000000 -0700
+++ showlog_none        2009-07-19 14:44:08.000000000 -0700
@@ -291,8 +291,8 @@
- print_stream_header $NUMFILES >> "$OUTFILE" - $GZIP_HEADER_TYPE $ALLFILES >> "$OUTFILE" + print_stream_header 0 >> "$OUTFILE" + $GZIP_HEADER_TYPE "" >> "$OUTFILE" rm -rf $KINDLE_STATUS_MESSAGE_LOG_ZIP rm -rf $KINDLE_STATUS_MESSAGE_LOG

Credits

  • Original tutorial by ebs
  • Tutorial amendments by Kim Hauser

Other articles in this category