View Single Post
Old 01-20-2013, 08:50 AM  
( ͡° ͜ʖ ͡°){ʇ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: 6299991
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
Post KUAL: Kindle Unified Application Launcher (v2.7)

Welcome to Kindle Unified Application Launcher, your /kuːl/ friendly neighborhood Launcher .

What Does It Do?:

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! With a particular caveat on the KT2/KV/PW3, where some early firmware versions won't let you run it... And a fun twist on the KOA/KT3/KOA2, as well as on FW 5.9.x in general, more on that later...

Latest Updates (06/04/2019):

Added information about KOA2/PW4/KT4 support, as well as FW >= 5.9.x in general. Do read the instructions until the end to see which method applies to your specific device.

PSA: All downloads have been moved to the Snapshots thread!


KUAL itself:

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 (or the associated "hotfix"), 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, download the latest KUAL archive from the Snapshots thread and unpack it. 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 Library (on recent FW, make sure you switch to the local Library view. In the same vein, on FW using a dedicated Homescreen page, you will never see KUAL in it). 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 .

Important notice for KOA/KT3/KOA2/PW4/KT4 owners, as well as *anything* that might be running FW >= 5.9.x:

As of right now, and for reasons outside of our control, Kindlets will fail to run on these devices & firmwares, so you can disregard the earlier bit about the azw2 file.

Instead, on these devices, we will have to use the Booklet version of KUAL.

First, the prerequisites: your device of course still needs to be jailbroken, and needs to be running a recent "hotfix" version (the vast majority of you should be covered, only the early adopters might need to update their hotfix). Then, you will have to install MR Package Installer (MRPI). Never mind that it's technically a KUAL extension and that we're in effect doing things in reverse .

Once that's done, put the Update_KUALBooklet_v*_install.bin file (found in the same archive as mentioned earlier) in the mrpackages folder, which you'll find at the root of your Kindle over USB, then eject & unplug you Kindle.

Finally, enter ;log mrpi in the Homescreen's searchbar (in a similar fashion as what you had to do during the Jailbreak), and wait for MRPI to do its thing.
When the UI finishes restarting, you should end up with a KUAL entry in your Library (showing as a personal document).

NOTE for KOA2, PW4 & KT4 owners:
As you already installed it during the JailBreak process, you can disregard the mentions of the "hotfix", yours will by definition be good enough for the job at hand .
Do take a look at the final entry in the FAQ, you will *most likely* need to use @coplate's patched version of the Booklet variant, so you might as well start with it to save you some trouble!

NOTE for PW3 owners:
If you're reading this and you're not yet running FW >= 5.9.x, I'd recommended moving to the Booklet variant ASAP, and then removing the Kindlet version. See the list of known issues for the reasoning behind this recommendation .

KUAL extensions:

Let's take the 'Helper' extension found on the Snapshots thread as an example. Simply unpack the kual-helper archive 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, which is good . It's highly recommended, especially if you use complex KUAL extensions.
MR Package Installer, which will make installing your favorite set of hacks a breeze .

You will find the full list of available extensions here.

FAQs and Known Issues:

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. (On devices where you installed the "hotfix" at some point in time, a simple reboot might do the trick).

Q. I tried installing the Booklet version on my device, but MRPI said it was "Not targeting my FW version" or "Not targeting my device", what gives?

A. It means your device was not yet identified at the time the latest release was tagged. Try using packages from my Snapshots thread instead .
And I do mean that for *everything* you might want that can be found there, from KUAL, to MRPI, to my Hacks.

Q. I'm running on FW >= 5.9.x, and when I tap on KUAL's document, I end up on a blank screen, with just a status bar! I'm forced to hard-reboot my device to get back to my homescreen .

A. Don't fret, this is a known issue on some devices/FW combos (especially on the KOA2, PW4 or KT4, since they all ship on FW >= 5.9.x). On these devices, instead of the original Booklet version from the latest release/snapshot, you'll want to use @coplate's patched version, a (currently) up to date build of which can be found here, in my Snapshots thread.

  • 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).
  • In the same vein, on the KV, the KT2 & the PW3, some early FW versions won't let you run Kindlets at all [you'll get a "The selected application cannot be started. Please try again later" popup].
  • Still in the same vein, do read the dedicated Oasis, KT3 & KOA2 & PW4 & KT4 section if you own one of these devices.
  • Same deal if you're running FW >= 5.9.x. If you're reading this, I'm assuming you've read the specific FAQ entry about it just a few lines earlier.
  • 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 % instead of 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 .
  • On newer FW, if you can't seem to find the KUAL button/entry, make sure you switch to a local Library view. Don't hesitate to filter by "Active Content" if you really can't seem to find it.
  • When upgrading from the Kindlet (KDK) version to the Booklet version on a FW version that stopped supporting Kindlets, you will end up with a stray KUAL icon. This is a known issue (affecting the PW3 in particular). @knc1 has been working on an automated way to get rid of it, see this post for a recap of the current situation.
    If you're reading this before the fact, you can easily avoid the issue by handling your updates smartly: install the Booklet version of KUAL, delete the Kindlet version *from the Kindle's interface* (it'll be the one with an icon), and only then, after verifying that the Booklet version is functional, will you be able to update your FW.


It's available here.


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 .


UPDATE v 2.4:
Kindle K2, K2i, DX, 3, 4, Touch, PW & PW2 supported (all revisions that support Kindlets)

Many thanks to and for their support
NOTICE! Lägg märke لاحظت Beachten AVIS Обратите внимание Προσοχή LET OP 注意 نوٹس

Non-Japanese 4GB PW2 models won't run Kindlets at all, unless updated to 5.4.5 or newer (make sure you're JailBroken before updating).

Really old firmware on Kindle 2's did not support kindlets, update the firmware.

Flashed 3.2.1 Dx's may not show up any kindlets... See Known Issues section for more details

Support: <-- Like read this... At least once
Supporting the K2, K2i, DX, Kindle 3 Keyboard, Kindle 4 Range, Kindle Touch, PW and PW2.

To be able to support and develop for these devices effectively is a LOT easier WITH the devices and cables. Twobob doesn't have a PW2, Aeris doesn't have a Touch.

If YOU choose to support this project please consider either donating a small amount via paypal here (simple 1 click process) It is not mandatory. By any means. But we would appreciate it greatly.

Or you could help us keep the dedicated servers up by giving here, Alternately consider forwarding monies to the project. Any excess project funds will be forwarded there anyway. Thanks for listening. Enjoy the Thing!



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"

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.

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:

ALSO: We have included a few optional helper scripts to get you going:
Called "Helper" (c.f., Snapshots thread) - unzip to FAT-ROOT)

ALSO: highly recommended is: "Additional Menu Items for KUAL 2.x"

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.

Here is the list of things you must have installed. 3 In Total.
[1] Jailbreak:
Select the relevant Jailbreak for your device. You will need one of these.
K5, PW & PW2 (5.0 - Kindle 4 Kindle DX, 2.x, 3.x

[2] Mobileread Kindlet Kit

[3] Install Kindlet:
Copy the relevant azw2 file to the documents folder on your kindle.
See Running the kindlet section, below.
(2) MKK,
(folder you put books in)
See Running the kindlet section below to determine which Kindlet to use

Running the kindlet:
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, KV, KT2, PW3)
Put KUAL-KDK-2.0.azw2 in documents folder.
Run it by clicking icon.

Expected output:
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" Extensions Optional extra
(All Devices) If you would like some helpful additional buttons you can get the Helper extension package from the Snapshots thread.

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

Also highly recommended is: "Additional Menu Items for KUAL 2.x"
This package adds the following items under the KUAL menu entry (with "collation enabled")
- Non-exiting Explorer button - needs the Explorer extension available elsewhere
- Enable/disable collating menus
- Purge menu cache
- Refresh menu
- Replace/restore Store button - KT/PW only
- Sort menu ABC, ABC! and 123 modes

What stage is the project at?
It's at a release stage. Stable.

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.'s_New Contains a whole BUNCH of good information for developers about how to use the new KUAL 2.x menu system. Give that a read too.

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.

So what can you do with this?
Run other applications
For info on supported Known packages visit [KUAL] Extension Support and Versioning

An incomplete list follows, please DO visit the above link for the latest possible extensions:

Anything I might not have read above that I really should have?
Originally Posted by SUPPORT ADVICE

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.

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...
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, PW2, KV, KT2 & PW3 devices, support is confirmed for these devices and it is safe to use the installers on them.

You can follow the project updates and grab the source here: Kindle Launcher Git

See also, as described above, the "Helper" extension package in the Snapshots thread.

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:

Make it prettier. - still.
Document everything.


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

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:
ERROR "This device is not authorized as a test Kindle by the developer of this item"
SOLUTION Re/Install the MKK bundle.

ERROR "Mobileread Kindlet Kit is not installed"
SOLUTION Install the MKK bundle.

ERROR "The selected application cannot be started. Please try again later" on non-Japanese 4GB PW2 models.
SOLUTION Update to FW >= 5.4.5 (after JailBreaking your device).

ERROR Flashed 3.2.1 Dx's may not show up any kindlets...
SOLUTION There is a workaround by TJW <-- tested by wakawakawaka

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

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:
Extension with serious issues are colored.
Many have no issues but additional helpful run notes etc. check pages for details.

FolderToggle NOT SUPPORTED Issues noted HERE

SSmodeSwitcher KT 5.1.2 ONLY Issues noted HERE

gtkSudoku for kindle touch KT 5.1.2 ONLY SERIOUS Issues noted HERE

Hacked up Reader Issues noted HERE

Komic Issues noted HERE

Skipstone Issues noted HERE

Leafpad Issues noted HERE

IRC Client Issues noted HERE

Gnash Issues noted HERE

Kterm Issues noted HERE

Eboard Chess Issues noted HERE

Javascript Games For Skipstone Issues noted HERE

KindlePDFViewer Issues noted HERE

KindleVNCViewer Issues noted HERE

Frotz Issues noted HERE

Fbgnuboy game loader Issues noted HERE

Minesweeper Issues noted HERE

Collections Manager Launcher Issues noted HERE

Set DateTime from Server Issues noted HERE

KUAL flite Speech Synthesiser (talking clock demo) Issues noted HERE

Vague - Voice Activated GUi Extension (TOUCH DEMO) Issues noted HERE

Gmplay (Kindle Silent Movie player) Issues noted HERE

Basic Audio Recorder for Kindle Touch Issues noted HERE

Toggle Light via KUAL for PAPERWHITE Issues noted HERE

BackDoorLock hack - prevents silent updates Issues noted HERE

KUAL Firewall with BBB filter Issues noted HERE

KUAL DevHelp - dmesg->doc button Issues noted HERE

DuokanLauncher Issues noted HERE

FontConfig Issues noted HERE

Broken Screen Scroller Issues noted HERE

Simple Calculator Issues noted HERE

Battery Report Issues noted HERE

Draw - a simple TS drawing application Issues noted HERE

Mplayer GUI Issues noted HERE

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.

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

Attached Thumbnails
Click image for larger version

Name:	KUAL_Icon.png
Views:	41814
Size:	16.1 KB
ID:	124896   Click image for larger version

Name:	KUAL_Homescreen_c.png
Views:	59133
Size:	112.2 KB
ID:	124918   Click image for larger version

Name:	KUAL_Slash_b.png
Views:	60131
Size:	73.3 KB
ID:	124919   Click image for larger version

Name:	KUAL_Buttons_b.png
Views:	47295
Size:	59.4 KB
ID:	124920   Click image for larger version

Name:	KUAL_Checkmark_b.png
Views:	43175
Size:	56.2 KB
ID:	124921   Click image for larger version

Name:	KUAL_Main_c.png
Views:	41641
Size:	110.0 KB
ID:	124922  

Last edited by NiLuJe; 06-04-2019 at 01:37 PM. Reason: Updated first post for KOA2/PW4/KT4 & FW 5.9.x info
twobob is offline   Reply With Quote