As the name implies, this is a Launcher application, in which anybody can plug into to provide new buttons and menus through extensions. Those buttons can run pretty much anything, and the backend is powerful enough to make menus dynamic, allowing developers to use KUAL as a configuration UI for their stuff! But the basic principle is: click a button to run stuff!

A number of hacks ship with a KUAL extension, which is why you'll often see KUAL listed as a required dependency .

Moreover, it's universal! It'll run on (pretty much) anything, as long as it's running FW >= 2.3! That said, the situation on the KT2 & KV is currently a bit murky....

Latest Updates (11/25/2014):

KUAL v2.5. Handle FW >= 5.6.1 (w/ the help of the latest JB).

INSTALL:

KUAL itself:

Spoiler:

As pretty much anything here, your device will need to be jailbroken. Please refer to the wiki and/or the stickies & index for the appropriate method for your specific Kindle model .

In addition, you may need to install MKK: if your device runs on FW 5.x, and you're using the K5 JB >= 1.11.N, you don't need to do anything, MKK is bundled with your JB. If you're using an older device, you will need to install MKK yourself .

Finally, you need to install KUAL itself, by putting the appropriate azw2 file somewhere in the documents/ directory tree of your device.
First, unpack the KUAL-v2.5.zip archive attached to this post. Then, if your device runs on FW 5.x, use the KUAL-KDK-2.0.azw2 file. If your device is older, use the KUAL-KDK-1.0.azw2 file.

And that's it for the basics! You should now have a pretty KUAL button/entry on your Homescreen. Right now, it won't be terribly useful, since KUAL ships without any extension, but now you have the tools to change that .
Check the screenshots attached to this post for a quick tutorial on how to actually navigate KUAL's UI .

KUAL extensions:

Spoiler:

Let's take the 'Helper' extension attached to this post as an example. Simply unpack the kual-helper-0.4.N.zip archive attached to this post at the USB root of your device. It'll create an extensions folder, and a helper subdirectory in it. That's it! Each extension lives as its own subdirectory inside the extensions folder. It'll automagically get picked up the next time your start KUAL, and you should see a new 'Helper' menu pop up in the main KUAL screen!

Extensions should always be packaged this way (i.e., simply unpack them at the root of your device), but if they're not, unpack them inside the extensions directory instead.
Developers, see this wiki page for all the gory details on what you can do .

Here are a few other 'quality-of-life' extensions provided by the KUAL dev-team:KUAL+, which extends the KUAL menu with more configuration options for KUAL itself.GNU Awk Installer, which will provide an install button for gawk in the KUAL menu. gawk will then be used by KUAL, instead of busybox awk. Long story short: it'll make KUAL parse your extensions faster .MR Package Installer, which will make installing your favorite set of hacks a breeze .

Q. Halp! Everything is broken, and my device shows me a weird popup when I try to launch KUAL!
The content of the popup might range from "This device is not authorized as a test Kindle by the developer of this item", to "Mobileread Kindlet Kit is not installed"

A. You either fell victim to a silent OTA update, or you unregistered your device since the last time you tried to launch a Kindlet.
The fix is simple: reinstall MKK.

----

Non-Japanese 4GB PW2 models won't run Kindlets at all [you'll get a "The selected application cannot be started. Please try again later" popup], unless updated to 5.4.5 or newer (make sure you're JailBroken before updating).

On a cold boot, even with everything in order, KUAL may sill fail to start on the first try, usually with a "An error occurred while trying to open this item", or a "The selected application cannot be started. Please try again later" or "Kindlet did not shut down properly" popup. This is a known issue, stemming from restrictions of the Kindlet framework, and the way in which KUAL is designed. Simply try again a bit later. (On a sidenote, enabling gawk might help a bit).

Really old firmware versions on the K2 & DX did not support Kindlets, update the firmware to the latest version available.

Frankensteined DXG with FW 3.x won't be able to run Kindlets without further tinkering

You need an up to date JailBreak (>= 1.13.N) in order for your extensions to behave properly on FW >= 5.6.1. If stuff appears to be half-broken, that's probably the case (the breadcrumb line being prefixed with a % is a definite sign that your JB is outdated).

If some buttons mysteriously fail to run, in an apparently random fashion, make sure your host system and/or your unarchiving tools are not messing with the case and the line-endings of files when unpacking the archives... This is sure to lead to hair-pulling mysteries otherwise .

For historical purposes, and because it's much, much more verbose, here's the first post as it stood before the rewrite . That said, everything you need to know should already have been covered earlier .

YOU WILL NEED TO PUT STUFF IN YOUR EXTENSIONS FOLDER FOR THIS TO BE USEFUL.

This is simply a folder called extensions located in the ROOT of the drive WHEN YOU ATTACH VIA USB TO FAT. If you forget to make one in advance of running the program for the first time... This folder will be automatically created for you, containing NOTHING. Simply two buttons:

No Extensions Found <-- Informative message

and Quit

To reiterate you need to put some extensions in the extensions folder.

"What? that really obvious place right where all the other default folders are?"
"Yep, put stuff there.. in the folder called extensions"

BitRot, No Magic, Voodoo (or Unicorns)"What will run, what won't run"

SOME OF THE OLDER PROGRAMS NO LONGER WORK ON THE NEWER KINDLES (nothing to do with this launcher they just dont work properly anymore) SUCH AS MANY IN THIS OLD LIST: SOME OF THESE DONT WORK

Any known misbehaving application will have support notes linked from 3rd Party Support Notes (below) in an effort to save you grief and wasted time. Please read the notes and check your device types is supported to avoid disappointment.

ALSO: Some extensions such as Kterm ARE DEVICE SPECIFIC. This launcher won't MAGICALLY make code that is DEVICE SPECIFIC work on OTHER DEVICES.

If it doesn't normally work on that type of device? It won't work via this launcher either.

Quote:

NOTE: There is a push to provide binaries (or pairs of binaries) that provision for all device types. These gtk-driven releases will fit perfectly into the ecosystem of KUAL. This provisioning is still in it's infancy however. Some working prototypes do, now, exist so perhaps watch this space

Enough shouting. You get the picture by now. It's a launcher of "other things" not an exciting thing in itself...

The new KUAL v2.x series is less forgiving of BROKEN syntax in extension menu.json files... If you find any let us know and we will try to contact the author to get them fixed "at source", there are very helpful details all about the new KUAL error reporting mechanisms and what to do about the issues HERE:http://www.mobileread.com/forums/sho...&postcount=778

ALSO: We have included a few optional helper scripts to get you going:
Called "Helper" (attached - unzip to FAT-ROOT)

In addition, power users might want to take a look at the gawk extension, to boost the parser .

Complete List of Requirements & Their Installation:To install a .bin file place it on the FAT ROOT of your kindle and choose UPDATE YOUR KINDLE from the SETTING page. Actual message text may vary, it will be obvious which one to use. Transferring the .bin files via usb rather than over ssh will ensure the installer is in a ready-to-work state on all device types.

SO TO RECAP:(1) JAILBREAK,
(2) MKK,
(3) PLACE THE CORRECT KINDLET IN THE KINDLES documents FOLDER (folder you put books in)See Running the kindlet section below to determine which Kindlet to use

Running the kindlet:

Spoiler:

Depending on your device:

(DX, K2, K3, K4)
Put KUAL-KDK-1.0.azw2 in documents folder.
Run it by clicking new kindlet document in your list.

(Touch, PW, PW2)
Put KUAL-KDK-2.0.azw2 in documents folder.
Run it by clicking icon.

Expected output:

Spoiler:

It should read through the /mnt/us/extensions folder and build a list of your extensions. Each command will create one button. you then click a button to launch the required application. Results are now paginated, and roll-around for easier scrolling.

NOTE: /mnt/us/extensions is simply a folder called extensions when you connect via normal USB.
Usbnetworking is not required to access this folder.

The "Helper" ExtensionsOptional extra

Spoiler:

(All Devices) If you would like some helpful additional buttons you can get the Helper Extensions package.

Unzip the archive and place the contents in the FAT ROOT. You of course don't need to put the ChangeLog & VERSION file on your device .

The USBNETWORK Extensions only work when usbnetworking app is installed.
The 711 Network report is Touch / PW specific at this time. Silently failing on other devices

Anything I should know?
You should only ever run code on your device from trusted sources. Code run via this launcher is no exception. We accept no responsibility and expect you to be vigilant and mindful of any custom code you choose to run on your machine.

Removing unwanted entries from menu
If you have a menu item you don't want. simply renaming the correct /mnt/us/extensions/<application name>/config.xml and menu.json to config-skip.xml and menu-skip.json will remove them from the lists next load. or delete the offending folders. your call.

Adding things to the menu
Simply construct a pair of config.xml and menu.json in it's own application subfolder under /mnt/us/extensions/<application name>/ just like before. The launcher should now parse it.
At a minimum point the menu.json to run at least one thing (like say a shell script) to be actually useful.

How do I convert my Launchpad scripts?There is a basic guide to converting the launchpad calls to menu items.
Currently we don't auto-parse the launchpad folder. So this process is required to support applications on the older (pre Touch) devices.

How Do I Exit?The kindlet will generally exit when you click a choice
Currently just press the HOME key if you have one or the< icon. Or select an item, the menu is generally self-terminating.
There is an option to make kual non-suicide on a per application basis, configurable in the startup configs. The "USBNetworking suite" demonstrates this in action.

I Have a Keyboard Device... Any Shortcuts?
Key-bindings have been added for devices with keys; PAGE forward and back now do what you expect and the top row (say q, w, e, r, etc.) will SELECT "options" (i.e KUAL BUTTONS) 1, 2, 3, 4, etc. Which is nice.

Since most of the support requests are about the initial installation this section has been expanded to hopefully make it perfectly clear. Before you ask for support: Have you installed the Mobileread Kindlet Kit? It is REQUIRED.

Spoiler:

You MUST install the Mobileread Kindlet Kit!!!!!!!!!!!!!

See the MKK Thread.
It is really required. Like really. You NEED it.
The large error messages will be a clue if you forget this step.
You install it using the UPDATE MY KINDLE option in HOME>SETTINGS

Don't expect support if you haven't installed it other than "Install it!"

So by this point you should be 100% ready to install everything...
Give it a go...

We maintain lists of known issues and other exciting details below. Enjoy the App.

Testing, errata, one last time...

Spoiler:

There are a couple of apps that don't play nicely - xterm for example on the PW & PW2 must be replaced by Kterm. Documenting these corner cases would go a long way towards knowing what needs to be fixed. Some efforts to this end are being made in the 3rd Party Support Notes section below.
Feel free to add comments about amending that as needed.

This is in the Release phase right now for K2, K2i, DX, K3, K4, Touch, PW and PW2 devices, support is confirmed for these devices and it is safe to use the installers on them.

However: DO, Simply un-archive the HELPER package and place the resulting "extensions" folder and it's contents in your FAT ROOT to get started with a few "Helper" links. Get you going with a few buttons.

Programmers details:TODO:

Spoiler:

Make it prettier. - still.
Document everything.

UPDATE HELPER TO BE USEFUL ON ALL DEVICE TYPES

Credits. Twobob, Ixtab, StepK, NiLuJe, KNC1, et al.

Spoiler:

Thanks to KNC1 for download authentication support, support hosting and all his tireless help developing the modules, structure and concepts for kual-system.
wakawakawaka for testing the DX prerequisites.
All the application authors who took the time to provide support.
All those kind users who were good enough to provide extensions for their favourite apps.
Yifan was the original chap whoms configs we parse.
All the unsung demo authors whose work we draw from on a daily basis.
And everyone else along the way.

Known issues:

Spoiler:

ERROR "This device is not authorized as a test Kindle by the developer of this item"SOLUTION Re/Install the MKK bundle.

ERRORKindlet did not shut down properly: Occasionally a seemingly spurious fail message is shown: "Kindlet did not shut down properly... blah.. blah.."

SOLUTION

Spoiler:

This happens generally after:

A change in the install of MKK. (following a failed previous "open" attempt)

A newly installed application ends with a bang.

You restart your kindle while the app is running somehow (ssh, rebootApp, etc)

Just press on "OK" then "Home" IN TIME, or suffer the reboot

Simply opening KUAL again (after you dismissed the message) will work just fine. Very rare. Benign. This is actually the Amazon framework doing it's job correctly and alerting us we had an issue. IIRC there is some way of auto-clearing the notification but this seems contrary. Therefore "Won't fix".

3rd Party Support Notes:

Spoiler:

Extension with serious issues are colored.
Many have no issues but additional helpful run notes etc. check pages for details.

Much of these issues are bit rot of old extensions... not the launchers failing.

NOTES: Are you a user? please report your fails on the relevant threads.
Are you a developer? use the templating system to add yourself as a "known" application.

Probably other apps exist and have issues.... If you find one we missed? Let us know.

HOW DO I UPGRADE FROM AN EARLIER ONE? No need to touch MKK.
Replace the old KUAL-KDK-(1|2).0.azw2 file in the documents folder with the new one.NOTE: If you're upgrading from a version older than 2.3, remove the deprecated KindleLauncher-(1|2).0.azw2 file in the process.
The correct, up to date filename is now KUAL-KDK-(1|2).0.azw2.
That's everything. You can find the new one in the KUAL files below

Just a quick post. Since I was the guinea pig for PW, it works great on PW running at 5.3.3. Will update later with more information.

p.s.: A quick note for installing. When on Windows and using 7zip and WinSCP. You have to extract the azw2 first before drag and dropping into your documents folder. Otherwise dragging out of 7zip and you get a nasty error3. And it took me quite a while to fix that.

Just a quick post. Since I was the guinea pig for PW, it works great on PW running at 5.3.3. Will update later with more information.

p.s.: A quick note for installing. When on Windows and using 7zip and WinSCP. You have to extract the azw2 first before drag and dropping into your documents folder. Otherwise dragging out of 7zip and you get a nasty error3. And it took me quite a while to fix that.

Speaking of the whole 7zip thing: @twobob: You might want to switch to zip, a lot of windows archivers are *really* stupid when dealing with gzipped tarball (two-pass decompression: gunzip, then untar, instead of rolling it all into one...).

Speaking of the whole 7zip thing: @twobob: You might want to switch to zip, a lot of windows archivers are *really* stupid when dealing with gzipped tarball (two-pass decompression: gunzip, then untar, instead of rolling it all into one...).

Let us adopt the habit of having the author always provide a detached signature file that can be checked for authentic with a pgp or gpg public key.

All host OSs support that checking (with either the pgp or gpg applications) - so signature checking can be off-kindle ;
Each provider of an archive can use their own key pair ;
Each provider can post their public key of the pair in a trusted location - here or on a public gpg key server ;

Adopting this sort of policy should be welcomed by the providers of archive packages - it minimizes the liability of "Your application published all my personal data" - - -
If that installed application archive **was not** signed by the author who published it - then s/he didn't do it - sue someone else.

Adopting this sort of policy should be welcomed by the end-users of these archive packages - it gives assurance that they are using an **authentic** copy of the author's archive.

Yes, of course, humans have a tendency to not download and test the signature against the archive -
That only means they have chosen not to protect themselves, their device and their personal information **PRIOR** to running the archived application.
Their loss, their fault, none of us did it to you. Go sue someone else.

Here is a worked example -
My mirrors.minimodding.com domain publishes **copies** of other peoples archives.
You will find a signature file for every archive posted.
In the side-bar you can find two (2) independent sources of the public key needed to check that the archives are authentic. (Which also does a checksum test for corrupted downloads.)

For Linux (any *nix) and probably for MacOSx also, it is just a matter of the user downloading both the archive and the signature - -
Then in their file manager, clicking on "check signature" for the archive.
At which point (if it passes) they know they have a true copy of whatever I posted.

Simple - only adds a couple of clicks to the entire process of installing a new application for the launcher.

For the author - nearly as simple - in your file manager just click the file and pick "sign" then pick the key you are using for this purpose.

First crash. When running kterm and letting pw go to sleep, upon waking up it displays kterm shortly and then back to launcher. No way to get back to the running kterm again. Starting kterm again and runs a new version. When exiting launcher pw will complain that app did not close right and wants restart or cancel. Maybe simply adding an killall everythingthatwasstarted might do the trick.