Register Guidelines E-Books Search Today's Posts Mark Forums Read

Go Back   MobileRead Forums > E-Book Readers > Amazon Kindle > Kindle Developer's Corner

Notices

Reply
 
Thread Tools Search this Thread
Old 08-08-2013, 06:20 AM   #1
Hotrootsoup
Junior Member
Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.
 
Posts: 6
Karma: 44444
Join Date: Aug 2013
Device: Kindle Paperwhite (5.3.4 JB)
Kindlet writing guide for the absolute beginner [PW]

Welcome! You may have noticed that it's easier to find reliable information about Atlantis than it is to find info on writing kindlets. I'm here to remedy that. After scrubbing through outdated wiki's and forum posts that assume you can read the author's mind, I have emerged triumphant.

Legal/moral note: I am not responsible if you crash, ruin, etc. your Kindle. These steps have worked for me, but they may not work for you. I do not believe that jailbreaks or further hacks void your warranty, but they very well may.

1. Prerequisites:
  • Above all else, I'm expecting you to be somewhat "techie". If I tell you to SSH somewhere, you should know or be able to figure out what that means.
  • You must know Java.
  • You must have Java installed.
  • You must know your OS. Linux isn't a requirement, but if you are on Windows, you need to know how to use the commandline, etc. Also if on Windows, use a text editor that uses unix line endings. If in doubt, download Geany and do Edit->Preferences->Files and set "Default end of line characters" to "Unix (LF)". Hit "Apply" then "Okay" and make sure to use Geany for editing all Kindle-related files. Also if on Windows, remember to replace my "/"'s in file paths with "\"'s.
  • Your Kindle should be a Paperwhite, and should be updated to one of the newer versions (I'm at 5.3.4). I say "should" because it's what I've tested; in reality this probably works on any Kindle that uses kindlets, and on most update versions.
  • Your Kindle must be jailbroken. If you haven't already,here is the link to do so.

2. Setting it all up

2-1. Setting up the folders.

Somewhere on your computer make a folder called "dev", or "kindleDev", or whatever you want. It doesn't matter. Just remember that I will be calling it "dev".

Inside of dev, make a folder named "testProject". Inside testProject, make another folder that identifies you. Username is a common choice, and indeed I will be calling it the "username" folder. Inside that, another named "test".

So mine is [dev]->[testProject]->[hotrootsoup] ->[test]

Seemingly excessive for a test project, but good habits die young, or something like that.

2-2. Grabbing and preparing the KDK jar.

We need the .jar file that holds the KDK's Java classes. There are actually quite a few jar files in the same folder as it that may have some fun classes. Don't feel obligated to grab those though, I don't even know if they are useful, so I just grabbed the main jar (Named below).

It is located in /opt/amazon/ebook/lib/ on your kindle, and will have a name similar to (probably exactly) "Kindle-2.2.jar" Any way you want to fetch this is fine, but here are a few ideas:
  • Install USBnetworking and grab the file by using that (SSH or FTP over USB). I haven't installed USBnetworking yet, but the instructions are here. That same link tells you how to FTP in.
  • Do the super lazy thing that I did. Install KTerm on your Kindle, and make sure you have ncat installed on your computer. (netcat called "nc" may work, but I used ncat.) Make sure your firewall is allowing port 8000 (or whatever) in, and run "ncat -l 8000 > Kindle-2.2.jar" on your computer, and in KTerm on your kindle, run "cd /opt/amazon/ebook/lib/" and then "cat Kindle-2.2.jar | yourLocalIPAddress 8000".

    This opens a TCP server on your computer that writes incoming data to Kindle-2.2.jar. Don't worry, it looks hacky but TCP ensures correct packet order and checksums and whatnot, so it will be the same file.

    Obviously replace "yourIPAddress" with your computer's local IP address. You can find KTerm here.

Now, open the .jar file we just grabbed in your archive manager. (not in Java) If yours can't open .jar's, use 7zip.

Drag the "com" folder from the .jar to inside the dev folder we made before.

2-3. Downloading the dev keys.

Go to this page and download the newest key set (*.2012-11-06.zip as of writing) Unzip it, and drag "developer.keystore" into the dev folder.

2-4. Creating the manifest file.

Make a new file in your dev folder called "test.manifest". Make sure you have file extensions visible, this can't be "test.manifest.txt".

Open it in your (unix line-ending friendly) text editor. We are about to put some text inside it, but before you do, remember: Do NOT customize the text I'm about to post. Copy what is inside the following code tags verbatim. Just leave it alone.

That being said, copy this text exactly into test.manifest:

Code:
Manifest-Version: 1.0
Main-Class: <your.package.and.Class>
Implementation-Title: <Your Kindlet Title>
Implementation-Version: <your version>
Implementation-Vendor: <Your Name or Nickname>
Extension-List: SDK
SDK-Extension-Name: com.amazon.kindle.kindlet
SDK-Specification-Version: 2.1
Toolbar-Mode: persistent
Font-Size-Mode: point
Save it, and make a copy in the same folder called "template.manifest"

You should now have a test.manifest in the dev folder, and a template.manifest in the same dev folder.

3. Creating the kindlet

To preface: I'm sure this is much easier if you set it all up with Eclipse or NetBeans, but NetBeans wont run properly on my PC, and I would rather pour salt in my eyes than use Eclipse, so these instructions will assume neither program. Also, I'm a Java noob, so don't look to me for good practices.

3-1. Creating the files

Create a file named "Main.java" in the path [dev] -> [testProject]->[username] -> [test]

Now, open up the test.manifest file that resides inside "dev", and make the following edits.
  • Change
    Code:
    <your.package.and.Class>
    to
    Code:
    testProject.username.test.Main
  • Change
    Code:
    <Your Kindlet Title>
    to whatever you want. "Hello". "Testing". "Pootie Tang".
  • Change
    Code:
    <your version>
    to 1 or .1, I don't know. Who am I to decide the status of your kindlet? =P
  • Change
    Code:
    <Your Name or Nickname>
    to, well, again, you should know this.

3-2. Writing the code

[Preface]
You can test out this upcoming information with a premade "Hello World" type kindlet I wrote if you want to check your environment before writing code. The kindlet is a blank screen that pops up an alert when you tap it. MAKE SURE that
Code:
Toolbar-Mode:
is set to "persistent"
in your manifest file, or you will have no way to exit the app, and your kindle will be crashed.

The code is here, but heed the above warning, and remember to replace "username" with whatever you used as your username folder in the package line at the top of the code.
[/preface]


Obviously I'm not going to teach you Java, but I will explain the environment you are dealing with.

Here is a link that explains the limits put on you compared to "normal" Java. It shows what classes you can use, and a link to the variant of Java SE that you are allowed that describes the bits of the core language that are different. (Certain things about generics I believe are restricted, etc.)

Here are the classes that Amazon offers you.

Those should explain it pretty well, and make sure to study the "AbstractKindlet" and "Kindlet" classes before reading any further. "KindletContext" is also important if you want to accomplish anything.

Yes, I see you not reading what I just said to read. Seriously, read this page before doing anything else. It explains the life cycle of a kindlet, and what you need to do to get your main class to run. Don't forget, you're going to want to extend AbstractKindlet with your main class. And since you can't do much without it, make sure to read this page on KindletContext, which is the class of the object that gets passed to create().

Also, set
Code:
Toolbar-Mode:
to "persistent" in the manifest file so you have a way to exit your app. If you do not, there will be no way to exit and your kindle will be crashed. The line should be:

Code:
Toolbar-Mode: persistent
Start off the code in your Main.java with
Code:
package testProject.username.test;
To import the amazon classes (assuming you used my folder structure) you can use the form
Code:
import com.amazon.kindle.kindlet.(class);
3-2. From code, to a kindlet.

So yep, write your code inside the Main.java we created before, and run
Code:
javac testProject/username/test/Main.java
from the "dev" folder in the terminal. If you are using Windows, remember to write the "/"'s as "\"'s. It should be fairly obvious if this succeeds or not. Hopefully you got a Main.class file out of it.

While still in the "dev" folder, run
Code:
jar cvmf test.manifest Test.jar testProject
You should get a Test.jar as a result. Now run:

Code:
jarsigner -keystore developer.keystore -storepass password Test.jar dktest
then

Code:
jarsigner -keystore developer.keystore -storepass password Test.jar ditest
then

Code:
jarsigner -keystore developer.keystore -storepass password Test.jar dntest
We just signed the .jar with the shared developer keys. It is a huge pain when people use their own keys, so the current jailbreak auto-installs these on the kindle. The one everyone now uses is called "test" with a password of "password".

Now rename Test.jar to Test.azw2 and put it in your kindle's "documents" folder. "documents" in the folder you've been dragging your fanfiction and whatnot into, and it is in the main folder you see when you plug in your kindle via USB. If I recall, it is technically /mnt/us/documents/ on the kindle's filesystem.

Now eject and unplug your kindle, and click on the brand new kindlet shining you in the face =)
Hotrootsoup is offline   Reply With Quote
Old 08-08-2013, 06:29 AM   #2
twobob
( ͡° ͜ʖ ͡°){ʇlnɐɟ ƃǝs}Týr
twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.twobob ought to be getting tired of karma fortunes by now.
 
twobob's Avatar
 
Posts: 6,586
Karma: 6029103
Join Date: Jun 2012
Location: uti gratia usura (Yao ying da ying; Mo ying da yieng)
Device: PW-WIFI|K5-3G+WIFI| K4|K3-3G|DXG|K2| Rooted Nook Touch
Nice one.

Thanks
twobob is offline   Reply With Quote
Old 08-08-2013, 08:12 AM   #3
brianinmaine
Evangelist
brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.brianinmaine ought to be getting tired of karma fortunes by now.
 
brianinmaine's Avatar
 
Posts: 456
Karma: 1287375
Join Date: Jan 2013
Location: West Gardiner, Maine
Device: Touch (5.3.7)
Makes me want to learn Java just to try this out. Thanks for spending the time to teach!!
brianinmaine is offline   Reply With Quote
Old 08-08-2013, 09:04 AM   #4
knc1
Ex- Helpdesk Junkie
knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.knc1 ought to be getting tired of karma fortunes by now.
 
knc1's Avatar
 
Posts: 10,710
Karma: 10423610
Join Date: Feb 2012
Location: Central Texas
Device: Nothing KV or newer, not interested.
And a worked example of how to automate a lot of that in an Ant makefile:

https://bitbucket.org/ixtab/ktcollec...=master#cl-157

But the write-up is nice, it will help a lot of people learn about the process.
knc1 is offline   Reply With Quote
Old 08-08-2013, 12:24 PM   #5
NiLuJe
BLAM!
NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.NiLuJe ought to be getting tired of karma fortunes by now.
 
NiLuJe's Avatar
 
Posts: 6,697
Karma: 6154617
Join Date: Jun 2010
Location: Paris, France
Device: Kindle 2i, 3g, 4, 5w, (PW) & PW2; Kobo H2O
Awesome! Feel free to cross-ref to this in the stuff you found on the Wiki!
NiLuJe is offline   Reply With Quote
Old 08-08-2013, 07:37 PM   #6
Hotrootsoup
Junior Member
Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.Hotrootsoup has never been to obedience school.
 
Posts: 6
Karma: 44444
Join Date: Aug 2013
Device: Kindle Paperwhite (5.3.4 JB)
Quote:
Originally Posted by knc1 View Post
And a worked example of how to automate a lot of that in an Ant makefile:

https://bitbucket.org/ixtab/ktcollec...=master#cl-157

But the write-up is nice, it will help a lot of people learn about the process.
I hate build scripts for learning. If you can't write your own, you don't know enough about the process to make it okay. Even in this guide I abstracted too much.


Quote:
Originally Posted by NiLuJe View Post
Awesome! Feel free to cross-ref to this in the stuff you found on the Wiki!
That reminds me: Much credit to the wiki, ixtab, various forum posts, Java docs, and many others for helping me learn all this.
Hotrootsoup is offline   Reply With Quote
Reply

Thread Tools Search this Thread
Search this Thread:

Advanced Search

Forum Jump

Similar Threads
Thread Thread Starter Forum Replies Last Post
The absolute n00b guide to installing applications Adam B. iRex 90 08-30-2013 07:01 AM
Free Aquarium Beginner's Guide pagansoul Deals, Freebies, and Resources (No Self-Promotion) 0 02-04-2009 01:00 PM
LifeHack Beginner's Guide to E-Books Bob Russell News 12 06-02-2008 04:09 PM
How To Read eBooks: A Beginner's Guide Bob Russell Deals, Freebies, and Resources (No Self-Promotion) 0 07-09-2005 11:13 PM


All times are GMT -4. The time now is 05:17 PM.


MobileRead.com is a privately owned, operated and funded community.