GUI Launcher for Kindle Touch

[yifanlu]

This Kindle Touch (only) mod adds a new menu option "Launcher" to the menu on the home screen and the reader screen (when you press the "Menu" button). When you choose the "Launcher" menu item, you can presented with a list of customizable items with customizable actions. Using either Java or JSON, you can easily add items to this menu. You can add items that run shell commands/scripts, items that run Java code, or submenus that contain more items. To see how to add your own items, check out the two examples I've provided. Also, check the Javadocs (http://yifanlu.github.com/KindleLauncher/), the classes "ExtensionsLoader", "JSONMenu", and "Menuable" provides some insight to what to put in config.xml file and the menu files. (Also read this post for the java system: https://www.mobileread.com/forums/sho...34&postcount=6)

Included menu extensions:
-Change screen orientation (orientation changes show up in browser and reader only)
-Turn usbnetwork on/off (the option text does not change if you turn usbnet on/off without using the launcher)

Download
http://yifan.lu/p/kindlelauncher/

Updated version for Firmwares 5.1.0-5.1.2
Download here.


Archived content:
===================================

Since we no longer have a keyboard on the Kindle Touch, it's a bit difficult to launch scripts and such. So, I decided to make a GUI launcher that hooks onto the menu system.



Now what I need are input from developers for what features they want in something like this.

To give an idea of what is to be implemented, here's a sample config file:
http://pastebin.com/EEPrSbDY
and a sample JSON menu:
http://pastebin.com/aTZ9Xf5B

I don't want to do an extensive package management system right now, because that's too much work, but I don't want to make something that limits developers from doing what they want. I also want to make sure hacks installed should not need to make their own startup scripts and hooks.

After taking a look at many of the current Kindle hacks that could be ported to the touch, I figured that most only do one or more of the following:
1) Start a daemon on startup/stop it at shutdown
2) Bind mounts certain files/folders on startup
3) Launch a kindlet
I think for those things, what I have is enough. However, I would like examples (either ideas or actual hacks) of things that would require more features to do.

Oh, and finally, I am only targeting Kindle Touch with this, as the Kindle 4 and below's java code is obfuscated and I don't have an older device to test with anymore. Also, here's the source code for the WIP, note that it won't run without some modifications yet: https://github.com/yifanlu/KindleLauncher

[NiLuJe]

Yay!

That sounds good to me, and, off the top of my head, has everything that I could possibly wish for . Would the keys of the config file(s) be passed to the 'action' scripts' ENV? That'd be neat (and help with the whole clunky 'trigger' file design I'm currently using in the ss/fonts hack, *and* the user-mistake unfriendly bash file source'ing in usbnet. [bascially, we get a proper config file parser for free without hacking something up in bash scripts]).

[yifanlu]

Sorry, what do you mean by "keys"? Currently, if you implement the JSON menu system, you can choose the arguments passed to the scripts. If you write a C application that generates JSON menus then it could be dynamic, like "Choose the screensaver you want to use". If you use the Java menu system, it would be even easier.

[NiLuJe]

Sorry, I meant propagating the key/value pairs from the config file to the scripts (either via env vars, or, yeah, args, or something ^^) .

On the other hand, if I get what you were just saying about the menus, that would mean that (provided something builds/update them), they could be dynamic, they're not loaded once at startup and 'frozen'?

[yifanlu]

Originally Posted by NiLuJe

Sorry, I meant propagating the key/value pairs from the config file to the scripts (either via env vars, or, yeah, args, or something ^^) .

On the other hand, if I get what you were just saying about the menus, that would mean that (provided something builds/update them), they could be dynamic, they're not loaded once at startup and 'frozen'?

Correct. By default, once the json menu is loaded, it is cached, but if dynamic="true", it will re-read the JSON file each time it is called. You are free to cache or not cache the menus if using java.

[yifanlu]

The Java hook system is almost complete. Here's what the process of making a Java extension is like:

1) Create an "action". An action holds both the menu item itself (text and icon) and what to do when tapped. Here is an example of a class that logs it's name when tapped:

package com.yifanlu.Kindle.Test;

import com.yifanlu.Kindle.KindleLauncher;
import com.yifanlu.Kindle.LauncherAction;

/**
 * This sample action logs the menu item's text value when tapped
 */
public class TestAction extends LauncherAction {

    /**
     * TestAction logs itself when it is called.
     *
     * @param name  The menu item's display text
     * @param priority  The order to display the item.
     *                  If two items have the same priority, they are sorted by name.
     */
    public TestAction(String name, int priority){
        super(name, priority);
    }

    /**
     * This method is called when the menu item is tapped. It will always run in a new thread.
     * Note that we have access to all of the Kindle's Java classes.
     */
    public void doAction() {
        KindleLauncher.LOG.info("Tapped " + getValue() + "!");
    }
}

2) Now we create a class that implements the Menuable interface. The config file will tell the launcher app to load this class. Then whenever the user opens the Launcher, every extension's Menuable class is called to add their menu items into the main launcher.

package com.yifanlu.Kindle.Test;

import com.yifanlu.Kindle.LauncherAction;
import com.yifanlu.Kindle.LauncherMenu;
import com.yifanlu.Kindle.Menuable;

import java.util.ArrayList;
import java.util.Iterator;

/**
 * This Menuable class will add two new options into Launcher's main menu
 */
public class TestMenu implements Menuable {
    /**
     * This ArrayList will store the menu items for our TestMenu
     */
    private ArrayList mItems;

    public TestMenu() {
        mItems = new ArrayList();
    }

    /**
     * Here we create the menu items and add them to the array.
     */
    private void createItems(){
        // The first menu item will be a TestAction that logs when it's tapped.
        // The second parameter in the constructor shows the order to put these items.
        // If two items have the same priority, they are sorted by their name
        TestAction action = new TestAction("Menu Item 1", 5);
        // The next item is a submenu
        LauncherMenu subMenu = new LauncherMenu("Submenu 1", 5);
        // Here we make another TestAction
        TestAction action2 = new TestAction("Submenu Menu Item 1", 0);
        // We add the second TestAction into the submenu
        subMenu.addMenuItem(action2);
        // We add the first TestAction into the main menu
        mItems.add(action);
        // We add the submenu into the main menu
        mItems.add(subMenu);
    }

    public void addItemsToMenu(LauncherMenu menu) {
        // In this example, we only generate the menu items once,
        // but you can do it every time by removing the if statement
        if(mItems.isEmpty()){
            mItems.clear();
            createItems();
        }
        Iterator arrayListIterator = mItems.iterator();
        while(arrayListIterator.hasNext()){
            LauncherAction action = (LauncherAction)arrayListIterator.next();
            // This method is usually called by the main launcher so all the items placed into mItems will show up
            // in the main menu when the user taps "Launcher". If all extensions place multiple menu items into the
            // main menu, it could get messy, so it is recommended that each extension place one submenu menu option
            // into the main menu.
            menu.addMenuItem(action);
        }
    }
}

In this example, the extension "TestMenu" adds two menu items into the launcher. One of them is a TestAction, which logs its name and the other is another menu that shows another TestAction item when clicked.

3) We put these two classes into TestMenu.jar and create a config file (config.xml)

<?xml version="1.0" encoding="UTF-8"?>
<extension>
	<information>
		<name>Test Menu</name>
		<version>1.0</version>
		<author>Yifan Lu</author>
		<id>testmenu</id>
	</information>
	<menus>
		<menu type="java" jar="TestMenu.jar">com.yifanlu.Test.TestMenu</menu>
	</menus>
</extension>

4) We create a folder named "testmenu" and place the two files "config.xml" and "TestMenu.jar" into it. Now we copy "testmenu" to the "extensions" folder on the Kindle and the new menu options will show up in the launcher.

I'll write more about using JSON and native apps to add menu items when I finish the JSON parser.

[yifanlu]

Ok, the launcher thing is 99% done. The last thing to do is to create a startup/shutdown loader system. So far, it requires one file to be patched (for the launcher menu to show up in the home screen). It uses the readersdk to hook onto the menu when you're reading. I won't be able to release it until I finish writing the new updater system. It doesn't seem like there's much interest in this, so I may put it off for a while. Meanwhile, it's great for my personal use. I wrote some nice tweaks for the Touch (rotate screen, enable/disable screensaver, enable/disable usbnet, etc) that I can access easily.

If anyone wants to know how I patched the home screen's menu system. I took JBE (Java Bytecode Editor) and opened up "com.
amazon.kindle.home.view.browse.BrowseDisplayContro ller.$BrowseMenuManager" (found in /opt/amazon/ebook/booklet/home.jar) and under the initMenu() method, I added the following bytecode after line 25:

aload_0
getfield com/amazon/kindle/home/view/browse/BrowseDisplayController$BrowseMenuManager/B Lcom/amazon/agui/swing/MenuDialog;
invokestatic com/yifanlu/Kindle/KindleLauncher/getInstance()Ljavax/swing/Action;
invokevirtual com/amazon/agui/swing/MenuDialog/addActionWithIndicator(Ljavax/swing/Action;)Ljavax/swing/AbstractButton;
pop

Then I made sure all the gotos and jumps afterwards were corrected with the new line numbers.
I saved the class and added it into my KindleLauncher.jar and added that jar into /opt/amazon/ebook/lib, since it's in the lib folder it gets loaded before home.jar.
Then I edited /opt/amazon/ebook/config/reader_plugins.xml and added my reader plugin in it.

[geekmaster]

Originally Posted by yifanlu

I won't be able to release it until I finish writing the new updater system. It doesn't seem like there's much interest in this, so I may put it off for a while.

Really? What gives you that idea? This is a new thread and already has almost 600 views. And your previous Touch jailbreak thread has over 85K views. You had similar feelings about donations from the Kindle Support Team before I started that thread.

Or... it is just the "updater system" that you are referring to? By "updater system", do you a method to install new hacks? If so, it would be nice to have some kind of organized method to keep collections of hacks from needing tweaking to coexist on a kindle. As it is, we can have folder and file name conflicts, and even launchpad hotkey definition conflicts, where hacks can fight over who gets to use a particular definiton. Perhaps we need a "central registry" thread where people can reserve a set of hotkeys and an installation folder for their hack, not to be hijacked by later different hacks. Or, is that just hoping for too much on my part?

Regarding a lack of interest (in general), you are not alone. A lot of "lurkers" are following you, waiting anxiously on your progress. People are busy this time of year, but there are people studying your code.

In my case, I have only had my Touch for one day, and I am gathering resources. I prefer starting at the "bare metal" and building upon a firm foundation. Until I write eInk driver replacements, the lowest level I am using at this point is the framebuffer and /proc/ files.

What we are going to need here is a clean API definition so the code us low-level guys write can cleanly interface the the high-level GUI code.

And, please don't feel so all alone here. There is a LOT more interest in your progress than you think. You have a large fan base.

[yifanlu]

There's also a lack of interest on my part. I have it working with everything I want it to do, so that's enough for me. If I have free time, I would expand it to work with other hacks, but there is no "other hacks" right now.

[geekmaster]

Originally Posted by yifanlu

There's also a lack of interest on my part. I have it working with everything I want it to do, so that's enough for me. If I have free time, I would expand it to work with other hacks, but there is no "other hacks" right now.

That's one big problem with open source projects in general. The primary developer moves on to other interests when a project is "good enough" for his own personal use, but not necessarily polished enough for "noobs". Many open source projects have stalled at that "almost done" state. The projects that really survive are the ones that grow enough to take on a life of their own, independent of the original developer.

And the Touch has some architecture changes that add complications to porting hacks from previous kindles, such as missing or different /proc/ ports, and different ioctl calls (for framebuffer display updates, at least). IMHO, we need some simple way to write portable native code that works on all kindles (a portable API that replaces the non-portable framebuffer updates, and provides GUI support to native apps).

[yifanlu]

I'm changing the goals for this project. It would no longer be a package system and startup script manager. It's going to do one thing and do it well, which is parse and display menu options. However, some of the hacks I wrote I don't plan on releasing because they're proof of concept stuff that Amazon may not like. Until I come up with some better hacks or something, I'll hold off this project. Meanwhile, I have to get back to finishing the kindle update tool.

[geekmaster]

I agree that solid (do one thing and do it well) components are much less fragile and should be much less sensitive to amazon updates (and interference from other hacks), than monolithic "do all" systems. Your new plan is a good one.

At some point, we will still need a simple and robust way to organize and manage our component collections, but we are a *long* way off from needing a one-stop shop "app store" or "maketplace".

[yifanlu]

Well, if there are more hacks there would be more need for a package manager, but I can't even name 20 hacks for the Kindle right now.

Anyways, I wrote some documentation: http://yifanlu.github.com/KindleLauncher/

Just in case I forget what I did when I come back to it later.

[seaniko7]

Did you know, that there's also builtin app launcher ?
For example :

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

launches draw app.

[yifanlu]

Originally Posted by seaniko7

Did you know, that there's also builtin app launcher ?
For example :



launches draw app.

Yes, but you need SSH. One of the extensions I wrote makes use of that to launch browser, facebook, gmail, and draw.