View Single Post
Old 01-20-2013, 07:50 AM   #1
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,552
Karma: 6021142
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 (v 2.3)

UPDATE v 2.3:
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:
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:
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)

ALSO: highly recommended is: "Additional Menu Items for KUAL 2.x"
http://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.
Spoiler:
[1] Jailbreak:
Quote:
Select the relevant Jailbreak for your device. You will need one of these.
K5, PW & PW2 (5.0 - 5.4.2.1) Kindle 4 Kindle DX, 2.x, 3.x

[2] Mobileread Kindlet Kit

[3] Install Kindlet:
Quote:
Copy the relevant azw2 file to the documents folder on your kindle.
See Running the kindlet section, below.
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" Extensions Optional 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


Also highly recommended is: "Additional Menu Items for KUAL 2.x"
http://www.mobileread.com/forums/sho...1&postcount=15
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

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.


http://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
Spoiler:
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?
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.
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.

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

Also Attached as described above is the "Helper" extensions package.

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.

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

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.."

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.

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.


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
Attached Thumbnails
Click image for larger version

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

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

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

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

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

Name:	KUAL_Main_c.png
Views:	398
Size:	110.0 KB
ID:	124922  
Attached Files
File Type: zip KUAL-v2.3.zip (267.2 KB, 7261 views)
File Type: zip kual-helper-0.2.N.zip (6.5 KB, 1361 views)

Last edited by NiLuJe; 07-04-2014 at 09:43 PM. Reason: Released v2.3 :)
twobob is offline   Reply With Quote