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