JBPatch

This page contains information about JBPatch. JBPatch is an open source framework which allows to modify Java Bytecode. At this time, only the Kindle Touch and Kindle Paperwhite are supported out of the box, and a bare-bones JBPatch works on the Kindle Keyboard (not officially supported though), but the general idea is applicable to all Kindle models, and possibly even other OSGI- or Java-based devices.

This page is (hopefully) continuously under construction. This Wiki page should ideally contain much, if not all, information relevant to users. In particular, everybody is invited to contribute by adding missing information, like new patches, or new localizations for patches, or any other relevant information. In other words: You are more than welcome to modify this page.

Of course, this page does not replace the forum thread, but rather both are meant to complement each other: The forum is for ongoing discussions, questions and announcements, while this page is meant to consolidate the information.

Note: You are more than welcome to ask questions about JBPatch in the Forum thread. However, before doing so, please carefully read this Wiki page, and the first post of the forum thread - your question may have been answered before. Thank you!

Version Information

Please refer to the forum thread for downloads, version history, and notes about upgrading.

Framework and User Interface

Version 1.x

JBPatch started as a simple proof-of-concept hack, meant to demonstrate that it is possible to modify Java bytecode (and therefore, device functionality) without having to overwrite the actual Java class files on the device. Original patches consisted of a single file which was able to modify class definitions. It soon became apparent that a single file might not be enough to provide all the required patch functionality, and that the patched behavior should be configurable. The former problem was solved by allowing jar (zip) files to contain patches. The solution to the latter was not terribly user-friendly, as it required to manually change text files inside the actual patches' files.

Version 2.x and higher

Starting with version 2 of JBPatch, a user-friendly interface is available. It allows to enable or disable patches interactively, and it provides a visual interface for the configuration of individual patches.

Localization

JBPatch is completely localizable. Up-to-date translations for all supported languages are always available from here. To enable or update a localization, simply copy all the contained files to opt/jbpatch on your Kindle, then restart the Kindle.

This page contains detailed information about the translation status. Further information about how you can help with the translations is contained in this post. If a translation for your native language is not yet available, then please create one -- thank you!

Patches

As this does not seem to be clear enough, I'll repeat it again: all changes that you make to patch settings generally require a restart of the framework before they come into effect.

How to install new patches, in a nutshell:

1. Plug the Kindle to your computer
2. Copy the patch into the opt/jbpatch directory on the Kindle
3. Safely remove the Kindle from your computer
4. Restart the Kindle. You can either reboot it, or use the "Restart Framework" button on the System tab of the JBPatch UI.

For more in-depth information, see the sections below.

Note: Many of the patches below are already bundled with JBPatch and are not available as separate downloads. If the latest patch version has been bundled with a JBPatch distribution, the easiest way to install it is to simply install the respective JBPatch version. Otherwise, you can (at your own risk), extract the patch from the distribution's src/install/patches.zip file, and install it manually.

Firmware 5.3.x users: Not all of the patches are available for Firmware 5.3.x. Some of the patches simply do not make sense on a Paperwhite (like the Cover Views or TTS patch), and others have not been ported. Do not try to install a patch for an older firmware, it won't work.

Enable All Screen Rotations

Available for: Firmware 5.1.x

This patch allows all screen rotations to be used for the Java-based parts of the Kindle Touch UI. Note that it will not affect the browser and other WAF applications.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Modify Collection Count Behavior

Available for: Firmware 5.1.x

This patch modifies the way that the collection content is counted and displayed on the home screen. This is only relevant if you are using nested collections. If this patch is enabled, the total number of items reachable from a collection (and its subcollections) is displayed. If it is disabled, only the items directly contained in a collection are counted.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Enable Cover View Mode

Available for: Firmware 5.1.x

This patch allows to switch between the default list mode, and a cover view mode, while browsing the home screen and collections.

Note:: This patch does not, and cannot, change the default image used for collections.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Install mobileread Developer Certificates

Available for: Firmware 5.1.x

Kindlets must be signed with a developer certificate. This patch will automatically install a set of known certificates used by mobileread developers (Version: 2012-10-02), if required.

Note: If you are having problems launching specific Kindlets ("Your device is not authorized" message or so), try to de-register and re-register your Kindle. This will remove the developer certificates and reinstall the latest version. If the problem persists, then the application in question is indeed signed with an unsupported certificate; ask the developer of the application to sign it with one of the well-known certificates then.

• Version 2013-04-13: bundled with JBPatch >= 2.4.1

Enhance Dictionary Lookup

Available for: Firmwares 5.1.x, 5.3.1, 5.3.2, 5.3.3, 5.3.4

This patch allows to consult all dictionaries, instead of only one.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Modify Reader Font Sizes

Available for: Firmwares 5.1.x, (5.3.1, 5.3.2, 5.3.3)

Select the font sizes available in the reader application.

Note: This patch may not work properly if your device is running with a custom localization. It only supports the languages officially shipped with the Kindle.

Because of the issues mentioned below, this patch is not officially supported on 5.3.x firmwares anymore. It is entirely discontinued as of FW 5.3.4. You can still install it manually on FW 5.3.1, 5.3.2, and 5.3.3 - but be aware of the possible problems mentioned below.

Known UI issues (FW 5.3.x only): Your device may actually select a different font size than what you tapped on in the "Aa dialog". It's hard to explain, but for instance tapping on the 6th item will select the 8th, the 5th will select the 7th, etc. You actually can select all entries, but you may need to tap somewhere to the left of it to do so. This is a UI glitch, and the reason for it is unknown. However, the patch as such does work correctly, as do the pinch gestures to change the font size. In addition, selecting some font sizes has no visible effect. More info here and here. This probably won't be fixed.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0 (FW 5.1.x only)

Fix Reader Layout and Hyphenation

Available for: Firmwares 5.1.x, 5.3.1, 5.3.2, 5.3.3, 5.3.4

This patch fixes the block adjustment of the E-Book reader. Moreover, books in languages for which hyphenation rules exist will be properly hyphenated.

Notes:

1. Since three pictures say more than a thousand words: look at the screenshots in this post and you'll see what this patch is all about.
2. This patch supports hyphenations for .mobi and .azw books ONLY. KF8 (.azw3) books, and other formats like .pdf or .doc are NOT supported, and never will be. Just convert your files to mobi format.
3. This patch is released under the terms of the Affero GNU GPL. It uses a minimally modified subset of the iText code to support hyphenation. The hyphenation rules are subject to various licensing terms, please check the individual files in the download.
4. If you are having problems with hyphenation for a particular book:
   • Make sure that the book's language is correctly set, and that hyphenation rules for the language in question exist. You can check the JBPatch log file ("System" tab in the UI) for any anomalies.
   • There have been reports about some books which are exported from Kindle Previewer not being hyphenated at all (that is because they are in KF8 format). See this post and the followup discussion for problem description and solution.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Modify Reader Margins

Available for: Firmwares 5.1.x, 5.3.1, 5.3.2, 5.3.3, 5.3.4

This patch allows to change the margins around reader content.

Note: changes to the left and right margins for non-PDF files only become visible once you have changed to a different setting, then back to the desired one. Example: you have changed the "fewer words per line" margin, but you don't see any effect in the reader. Temporarily set the display option ("Aa" button) either to "default" or "few" words per line, then change back to "fewer". The technical explanation is that the margin widths are read from a cached file, which only gets updated with the new values when you change the margin setting.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Password-protect Items

Available for: Firmware 5.1.x

This patch can be used to add a simple password protection for items such as books, collections, or applications.

Notes:

1. Because the JBPatch UI can be used to disable this patch (thus rendering all items accessible), it is still relatively easy to get access to the protected items. You can password-protect the JBPatch UI for additional security.
2. Items are not encrypted in any way. They can still be accessed from a computer that the Kindle is connected to.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Customize Progress Indicator

Available for: Firmware 5.1.x

This patch allows to customize the appearance of the progress indicator displayed at the bottom of the E-Book reader. In addition to the default mode, three other options are available: "full" mode (always showing all information, including page number), a progress bar similar to the one displayed on the Kindle 3, and a graphical progress bar which displays the progress within the currently read chapter.

Starting with version 2012-08-26, the indicator style can also be changed at runtime (i.e., while reading). Simply use the "%" entry that appears next to the "Aa" button.

Note: changing the style while reading PDF files is currently not supported.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Make Scrollbars usable

Available for: Firmware 5.1.x

The default scrollbars are too tiny to be usable with a finger. In addition, menus in portrait mode may be too long to fit on the screen. While a scrollbar is displayed, it is not functional. This patch fixes both of these issues.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

Enable Text-to-Speech

Available for: Firmware 5.1.x

This patch unconditionally enables Text-to-Speech (regardless of language or DRM), and allows to customize the description of the voices.

• Version 2013-04-13: bundled with JBPatch >= 4.0.0

End-user Documentation

Introduction: important files and directories

JBPatch consists of multiple components. Some of them reside on the internal partition of the device, while others reside on the "USB" partition of the device. The internal files are not normally accessible by the end user, while the external files are accessible when the device is plugged into a computer. "USB" files are hereafter named using their relative path on the USB partition. For instance, documents/jbpatch.azw2 refers to the file visible inside the documents folder of the USB drive; internally, its full path on the device would be /mnt/us/documents/jbpatch.azw2.

• JBPatch core (internal) - /opt/amazon/ebook/lib/jbpatch.jar: This contains the core of jbpatch. Do not mess around with this file, unless you really know what you are doing.
• JBPatch log file (internal) - /tmp/jbpatch.log: This is the log file of jbpatch. Its content can be displayed on the system tab of the JBPatch UI.
• JBPatch UI (USB) - documents/jbpatch.azw2: This is the Kindlet that can be used to enable, disable, and configure patches. Do not delete this file. If you do accidentally delete it, you can copy it back there from the file src/install/jbpatch.azw2 in the installer package.
• Patches, configurations, and localizations (USB): opt/jbpatch/*.* : These files constitute actual patches, and their configuration and localization files. Further details are given below.
• Patches, configurations, and localizations (internal): /var/local/jbpatch/*.*: This directory is (more or less) a copy of the abovementioned directory. It is required for technical reasons. More information about when and how the two directories are synchronized is given below.

Patch installation, Configuration and Localization

Patches can be installed, and their configuration and localization can be changed, by modifying the files in the USB directory opt/jbpatch. File types:

• <patch-id>.jar or <patch-id>.class: These files are actual patches. To install a new patch, simply copy the respective file(s) to this directory.
• <patch-id>.txt: These files are configuration files for the respective patch.
• <patch-id>-<language-code>.txt: These files are localization files for the respective patch and language.
• CONFIG.txt: This is the configuration file for JBPatch itself, and defines which patches are enabled or disabled. You normally don't have to mess with this file, because the configuration can be performed through the UI.

Generally, all changes that you make to this directory will require a restart of the framework before they are considered. Please eject the Kindle device from the computer, then wait at least 5 seconds, before restarting the framework using the button on the System tab of the JBPatch UI.

How to use JBPatch

I've never found info on how to actually use JBPatch, so here it goes:

1. Download and install JBPatch
2. You can verify your installation by following this instruction from Readme file: "Go to Menu > Settings, Menu > Device Info. You should see a new entry telling you how many patches are currently active, and how many are available, along with the version of jbpatch that you have installed."
3. Now let's actually use JBPatch! Push your Home physical button and look among your books for "JBPatch". Tap on it. It starts a User Interface.
4. If you, like me, want to change margins, tap on "Modify Reader Margins" in the center (not on a check box).
5. Scroll up to Left and Right margins for PDF files. Tap on them and change them for 0 (zero). Also make smaller margins for non-PDF books (might be necessary). Tap on Enter to exit the screen keyboard.
6. Go Back, then Save. Leave the application using Back button on top left.
7. Now Menu > Settings, Menu > Restart
8. Open any non-PDF book. Tap on top margin. Aa > Spacing > fewer > default - this needed for margins to pick up your changes.
9. Close Fonts dialog box.
10. Push Home button (physical) and open PDF file - you should see smaller margins on left and right.

Directory synchronization

As previously mentioned, there are actually two directories containing the patches and their configuration/localization: one on the USB drive, and one on the internal partition (we'll call this the "working directory" from now on). This is needed for technical reasons.

I'll first describe the normal "background" synchronization, before going into details about how you can manually influence the procedure.

Background Synchronization

The USB directory is continuously scanned for new .class, .jar, or .txt files. If any of these files is found to be new, or changed, it is copied to the working directory. However, no further action is taken. A restart of the framework is thus required for the changes to come into effect. An exception is the localization file of the UI itself (com.mobileread.ixtab.jbpatch.ui.kindlet.JBPatchUI-*.txt), for which it is sufficient to only (re)start the JBPatch UI. Note that CONFIG.txt is not considered during normal background synchronization.

Manual Synchronization

The background synchronization is a "one-way street", in that changes from the USB directory are propagated to the working directory, but not the other way around. The files in the working directory may change because of configuration changes performed from the JBPatch UI, and for a few other reasons.

The JBPatch UI provides two buttons to manually control the synchronization.

Sync

This button performs a "reverse synchronization". In short, all files from the working directory are copied to the USB directory (overwriting existing files). The result is that the USB directory will contain the same state as the working directory, at the time when the synchronization was performed.

Cleanup

This button performs a "normal" synchronization (from the USB directory to the working directory), but with two major differences:

• CONFIG.txt is synchronized as well. Contrary to background synchronization, the CONFIG.txt (if present) is also synchronized during cleanup.
• Obsolete files are deleted from the working directory: This is the real reason why it's called "cleanup". While background synchronization only copies new or changed files from the USB directory to the working directory, a Cleanup will also remove any files present in the working directory, but not in the USB directory.

In other words: after performing a cleanup, the working directory will be an exact copy of the USB directory.

Use Case: Permanently Removing A Patch

This is only to show, by example, how the Sync and Cleanup operations could be used. Suppose that you want to permanently remove the patch whose file is com.example.SamplePatch.class.

1. perform a Sync operation.
2. plug the Kindle to your computer
3. remove ALL the com.example.SamplePatch*.* files from the opt/jbpatch/ directory.
4. unplug the Kindle from your computer
5. perform a Cleanup operation
6. restart the Kindle.

Notes:

• You don't need to worry about the CONFIG.txt file. Lines concerning nonexistent patches (such as the com.example.SamplePatch one after the cleanup) are automatically removed.
• You could also simply disable the patch (using the UI), instead of permanently removing it.

Advanced Documentation

How does JBPatch actually work?

This post may not answer all questions, but it at least gives a little bit of insight.

Configuration and Localization files

Encoding

All files are expected to be in UTF-8 encoding. This is particularly important for the localization files, as they may contain special characters outside of the ASCII character set. If your localization file isn't working, check the log file on the System tab of the UI: chances are that you used a wrong encoding, such as the anachronistic Windows-1252 one.

Example for quickly fixing all files in a particular directory (this can be run on any Linux machine, or even on the Kindle):

for i in *.txt; do iconv -f WINDOWS-1252 -t UTF-8 -o $i.2 $i; mv $i $i.wrong; mv $i.2 $i; done

Formatting and Escaping

The files are generally very similar to normal .ini files. Lines starting with a # character, and empty lines, are ignored. All other lines are expected to contain a key/value pair, separated by a = (equals sign). Be careful not to surround the equals sign with whitespace (unless you want the value to start with a whitespace).

The only supported escape sequence is \n, which produces a newline.

Developing new Patches

JBPatch is only a framework for patches, and everybody is more than welcome to develop new patches. I will happily include such patches into the base distribution, if they are found to be useful. Here is a minimal description of how the general procedure to develop a new patch could look like:

1. Identify an aspect of the Kindle which can be improved.
2. Find out where exactly the code pertaining to that aspect is located in the Java classes. This is arguably the most difficult part of the entire procedure, as it requires to reverse engineer the existing Java classes. A few hints about this are linked from the first post of the JBPatch thread, and a few more can be found on the Kindle Touch Hacking page.
3. Write a minimal patch to change some functionality at the previously identified locations. This is the second-most difficult part of the procedure, and will probably require a few iterations to get it right. You may want to test your changes on your development computer first (by modifying the "TestCurrentGoal" JUnit class, and by verifying that the output looks correct indeed), and then to test it on the Kindle by copying the patch to the device and restarting it, while watching the JBPatch log (/tmp/jbpatch.log). Hint: don't worry about localization, or about configurability, at this point.
4. Once your patch is working correctly, the difficult part is over. You can now turn to the localization aspects (to make the patch appear correctly in the user interface; that's pretty easy), and possibly to configuration as well. Allowing for configurable settings isn't terribly difficult, it just requires a few more lines of code. You can always look at the source code of existing patches for examples. The hyphenation patch is a particularly good example to see how localization works, but the Cover View patch, the TTS patch, or the margins patch may be worthwile as well.
5. Announce your patch in the forum thread!

Miscellaneous

JBPatch development uses the excellent ej-technologies JProfiler for profiling. Thanks a ton to ej-technologies for providing free licenses to open source developers!

Please do not alter or remove the above sentence or the link.