|
( ͡° ͜ʖ ͡°){ʇlnɐɟ ƃǝs}Týr
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
|
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...
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!
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 (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 .
Spoiler:
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 .
Spoiler:
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.
Spoiler:
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.
==============================
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 .
Spoiler:
UPDATE v 2.4:
Kindle K2, K2i, DX, 3, 4, Touch, PW & PW2 supported (all revisions that support Kindlets)
Many thanks to Hackaday.com and lifehacker.com for their support
Quote:
NOTICE! • Lägg märke • لاحظت • Beachten • AVIS • Обратите внимание • Προσοχή • LET OP • 注意 • نوٹس
BEFORE YOU CAN USE THE KINDLET: You MUST have installed MKK.
|
NOTES:
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
Spoiler:
Supporting the K2, K2i, DX, Kindle 3 Keyboard, Kindle 4 Range, Kindle Touch, PW and PW2.
Quote:
|
Originally Posted by A WORD FROM THE DEVELOPERS ABOUT DONATION
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) kual@null.net. 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 http://www.dreamhost.com/donate.cgi?id=16490, Alternately consider forwarding monies to the http://laosliteracyproject.org/ project. Any excess project funds will be forwarded there anyway. Thanks for listening. Enjoy the Thing! |
OKAY THAT'S IT FOR THE DONATION INFORMATION - NOW READ ON...
UPSTREAM SOURCE: https://bitbucket.org/ixtab/kindlelauncher
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:
https://www.mobileread.com/forums/sho...&postcount=778
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"
https://www.mobileread.com/forums/sho...1&postcount=15
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.
Running the kindlet:
Expected output:
The "Helper" Extensions Optional extra
FAQ:
Spoiler:
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.
https://wiki.mobileread.com/wiki/KUAL_What'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
Anything I might not have read above that I really should have?
Quote:
|
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.
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, 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:
TODO:
Credits. Twobob, Ixtab, StepK, NiLuJe, KNC1, et al.
Known issues:
3rd Party Support Notes:
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
Changelog
https://bitbucket.org/ixtab/kindlela....txt?at=master
Last edited by NiLuJe; 06-04-2019 at 12:37 PM.
Reason: Updated first post for KOA2/PW4/KT4 & FW 5.9.x info
|