Index to the Metazoa firmware patches

[GeoffR]

Instructions for patching firmware (by firmware version):

• 4.10.11655 (9f844e0935) [Mk 6/7 devices only]
• 4.10.11591 (374ecc0783) [Mk 6/7 devices only]
• 4.9.11314 (8c2fd38797) [Mk 4/5 devices only]
• 4.9.11311 (112578920c) [Mk 6/7 devices only]
• 4.8.11090 (bee5052c41) [ClaraHD only]
• 4.8.11073 (b628114af7)
• 4.8.10956 (daee2c4220)
• 4.7.10413 (168741200a)
• 4.6.10075 (2240799f12)
• 4.6.9995 (5c036c4fb5)
• 4.6.9960 (161d1adc5a)
• 4.5.9587 (c77383d7d1)
• 4.4.9344 (6f700792a0) and 4.4.9349 (6f700792a0)
• 4.4.9298 (1614b85db3)
• 4.3.9084 (59faa7bc47)
• 4.3.8966 (9c8144b8c0)
• 4.3.8945 (14b5a0d83e)
• 4.3.8871 (eec21f5563)
• 4.3.8842 (ed3f655eae)
• 4.2.8432 (fbb9e8f61b)
• 4.2.8283 (530afa6716) [MK6 devices only]
• 4.2.8110 (4f749ed9be) [MK6 devices only]
• 4.1.7729 (8bedc76ce7) [Mk6 devices only]
• 4.0.7523 (c213e8a341) [Mk6 devices only]
• 3.19.5761 (0e028f3185)
• 3.19.5613 (4b76aa47bd)
• 3.18.0 (b88456ee3d)
• 3.17.3 (407d48ba86)
• 3.17.0 (60588a39fd)
• 3.16.10 (f9fa4bfb12)
• 3.16.0 (f56b42a2e1)
• 3.15.0 (d60578c5e1)
• 3.13.1 (60d72c68d5)
• 3.12.1 (c1198635ca)
• 3.12.0 (563a2baefd)
• 3.11.0 (4d8eac1207)
• 3.8.0 (048bb0b071)

Patching makes small changes to the Kobo firmware in order to: customise appearance or settings, fix bugs, remove restrictions or unwanted features, and (rarely) to add new features.

Patching does not require jailbreaking or rooting, as Kobo e-ink devices are not locked. None of these patches add any extra files to the firmware, but they are applied by installing modified versions of existing files. This means that all these patches will disappear when the firmware is updated, and new patches must be created to apply to each new firmware version.

For this reason, when patching it is VERY IMPORTANT TO USE THE CORRECT PATCHES FOR THE FIRMWARE VERSION ON YOUR DEVICE! If you apply the patches for the wrong firmware version the device might not boot, and it will probably require a full factory reset. You can check the firmware version your device is using in the Settings > Device information page:



These patches are completely unofficial, so if you have a problem with your patched device don't complain to Kobo. The best place to ask for help is in the instruction thread above for the firmware version you are using.

(I refer to these as the Metazoa patches because most were originally created by metazoa at www.the-ebook.org, and as a way to distinguish them from other patches and mods.)


Description of what the patches do (all firmware versions):

• `Custom page refresh options`

• `Freedom to advanced fonts control`

• `Custom reading footer style`

• `My 15 line spacing values`

• Stylesheet priority patches:
  `Force user line spacing in KePubs`
  `Force user line spacing in ePubs`
  `Un-force font-family override p tags (std epubs)`
  `Un-force user font-family in KePubs`
  `KePub full justification default`

• Margin patches:
  `Custom left & right margins`
  `Custom kepub default margins`
  `ePub fixed/adjustable top/bottom margins`

• Fixed font sharpness
  `ePub fixed font sharpness`
  `KePub fixed font sharpness`

• Work-arounds for kepub problems in full-screen mode
  `KePub zero body margin/padding`
  `Fix kepub side bearing font cut-off bug`

• Custom keyboard patches
  `Cyrillic keyboard`
  `Arabic keyboard`
  `Hebrew keyboard`
  `Turkish keyboard`

• `Default ePub monospace font`

Obsolete patches:

• `ePub unitless line height` (2.8.1 - 3.15.0)

(This thread is a work in progress. I'll add links here as I create a post about each patch.)


This thread is intended to eventually be useful to those trying to decide whether or not to bother with patching. To avoid it becoming long and confusing for those new to patching, please don't post comments or questions about specific firmware versions here. The place to do that is in one of threads listed at the top of this page.

[GeoffR]

The unpatched firmware allows the page refresh interval to be set from 1 to 6 pages. It is also possible to edit the numPartialUpdatePageTurns entry in the [Reading] section of the device's configuration file to change the value to something larger than 6.

The `Custom page refresh options` patch allows the Reading Settings menu itself to be changed, so you can select from a custom set of values without the need to edit the configuration file. There are two patch alternatives: an arithmetic progression (default 1,2,3,4,5,6,7,8,9,10,11,12); or a geometric progression (default 1,2,4,8,16,32,64).

The screenshots attached (Glo, 3.15.0) show the first page of the Reading Settings menu, with the Refresh menu popup activated. From left to right:
1. Unpatched.
2. Patched, alternative 1 (default).
3. Patched, alternative 2.

[GeoffR]

The unpatched firmware restricts the advanced 'TypeGenius' font menu (which allows adjustment of font weight and sharpness) to a subset of the built-in fonts. The `Freedom to advanced fonts control` patch removes this restriction, making it available for sideloaded fonts too.

It is possible to set the weight and sharpness for sideloaded fonts without patching by adding readingFontWeight and readingFontSharpness entries to the [Reading] section in the device's configuration file. For example, readingFontWeight\Georgia=0.8 sets the weight of the Georgia font to the maximum value selectable from the advanced menu slider. This patch allows the convenience of adjusting these settings onscreen without the need to edit the configuration file.

Both OTF and TTF format fonts can be adjusted, but the adjustments might not take effect in the EPUB reader unless the font is in TTF format. In recent firmware versions this patch can no longer be used with Japanese language books or Japanese locale settings.

The screenshots attached (Glo, 3.15.0) show the font options for a sideload TTF font used in a sideloaded EPUB book:
1. Unpatched, Aa menu.
2. Patched, Aa menu; note that the 'Advanced' menu is now available for this font.
3. Patched, Advanced menu, weight/sharpness increased.
4. Patched, after tapping 'Apply'.

[GERGE]

One more thing about TypeGenius. Let's say that you raised weight slider 2 steps, you can't turn the type back to the original weight and sharpness by lowering two steps. You have to edit Kobo's config file under .kobo/Kobo/Kobo eReader.conf (if you are using Linux or OS X dot before the file or folder name means the file or the folder is hidden, I have no idea if they are also hidden in Windows, never used it) and remove sharpness and weight lines for the font you want to reset.

And a recommendation, before playing with weight, you should check optical sizes and the book styles of your typeface if there are any. You also have to reboot the device after installing different forms of the same typeface. Caption usually works well with eInk with its lessened details and high x-height.

[GeoffR]

The reading footer is the area at the bottom of the screen where the page number or other progress indicator is displayed. The `Custom reading footer style` patch allows the following properties of the footer to be changed:

• Footer height (the amount of screen reserved for displaying the footer),

• Font size used for the progress indicator,

• Vertical position of the progress indicator within the footer.

(In some firmware versions it is also possible to change the font face used for the progress indicator, although that can sometimes be problematic.)

In general, the default values for the patch result in a footer of about half the height of the one in the unpatched firmware. The same footer is used for both the EPUB and KEPUB reader, but as the KEPUB reader has a large header matching the large original footer, the smaller patched footer will probably look too small when reading kepubs.

Note that other factors in the book's stylesheet can affect the size of the gap between the text and the progress indicator: line spacing, paragraph spacing, @page margins, widows/orphans settings, and others.

The screenshots attached (Glo, 3.15.0) show a sideloaded epub with the line spacing adjusted to get the text close to the footer in both cases:
1. Unpatched
2. Patched (default values for Glo)

[GeoffR]

The unpatched firmware allows adjustment of the line spacing via a slider with 15 positions. However most people use only the lowest few settings, as the highest settings are far too wide to be useful. The `My 15 line spacing values` patch allows the 15 stock choices to be replaced with your own 15 custom values.

The final line spacing on the page depends on a number of factors, including choice of font face, publisher's settings in the book's stylesheet, and whether the EPUB or KEPUB reader is used (see the `ePub unitless line height` patch to fix a problem affecting line spacing in the EPUB reader's stylesheet.)

My understanding is that the line spacing value set by the slider is a scale factor by which the device multiplies the base line height. The scale factors used by the unpatched firmware range from 1.0 - 3.0. The default values in the patch change this range to 0.7 - 1.1, but you can choose any custom range you want.

The screenshots below (Glo, 3.15.0) show 5 out of the 15 line spacing settings with a sideloaded epub using the Amasis font. From left to right, line spacing values are: 0.7, 0.8, 0.9, 1.0 (unpatched minimum), 1.1:



And if you are wondering why anyone would need a line spacing value as small as 0.7, it is because some fonts come with an extremely large base line height: the screenshots below (Glo, 3.15.0) show an EPUB with the Kobo Nickel font selected, line spacing values of 0.7 (default patch minimum) and 1.0 (unpatched minimum):



Beware that the KEPUB reader has a limitation which affects the use of small line spacing values. The screenshots below (Glo 3.15.0) show pages of an EPUB and a KEPUB respectively, using a line spacing value of 0.8. Note the dots at the bottom of the KEPUB page: these are the ascenders of the top line of text from the following page. How narrow you can make the KEPUB line spacing before this problem shows up depends on which font face is used. There is currently no fix for this problem, other than increasing the line spacing or switching to the EPUB reader.

[Nick_1964]

Very,very clear this !

[GeoffR]

(This patch is available for firmware versions 2.8.1 - 3.15.0 but is no longer needed in current firmware as the problem described below was fixed in firmware version 3.16.0)

The Kobo firmware has separate built-in stylesheets for the EPUB and KEPUB readers where the default line height is set. There is a long-standing fault in the EPUB stylesheet which causes the line height to be set in proportion to the font size set from the font size slider, instead of in proportion to the final font size on the page as is done in the KEPUB reader. The `ePub unitless line height` patch fixes this fault.

(This problem might not be very noticable in books which don't use a wide range of font sizes, or where headings don't span multiple lines, or where the publisher forces a fixed line height instead of using the default set by the reader.)

The screenshots below (Glo, 3.2.0) show a page from a demonstration epub which has three different font sizes set in the book (xx-large, medium, xx-small), with the line spacing adjusted via the slider to suit the medium font size:
1. Unpatched,
2. Patched.

[GeoffR]

The firmware comes with built-in stylesheets which set the default styles for books according to the reader's preferences, and can in some cases override the styles set by the publisher in the book. There are separate stylesheets for EPUB and KEPUB books.

In an ideal world, the publisher would respect the defaults set by the device and only override those styles which shouldn't follow the reader's preference. For example, the publisher should let the reader choose the line spacing for the main body of text, and only override the reader's preference for special elements such as headings, dropcaps, etc.

But in practice there are many books where the publisher overrides the default settings to force their particular choice of line spacing or other style to be used throughout the book. So when designing the built-in stylesheets, the device maker has a choice:

• Take a light-handed approach: Just set the reader's preferences as defaults, and hope the publisher will respect them.

• Take a heavy-handed approach: Force the reader's preferences to override the publisher's, on the assumption that the publisher will not respect the defaults.

The main problem with the heavy-handed approach is that it overrides both the good and the bad choices made by the publisher. For example, forcing full justification might also affect some headings or images that should be centred.

In general on Kobo devices the EPUB reader takes the light-handed approach (with a few exceptions), while the KEPUB reader takes the heavy-handed option (again with a few exceptions).

There are a number of patches that can modify the EPUB or KEPUB built-in stylesheets to use the heavy-handed instead of light-handed approach, or vice versa:

Patches to use a heavier hand:

• `Force user line spacing in KePubs`

• `Force user line spacing in ePubs`

• `Enforce user line spacing and justification in ePubs`

Patches to use a lighter hand:

• `Un-force font-family override p tags (std epubs)`

• `Un-Force user text-align in div,p tags in KePubs`

• `Un-Force user font-family in KePubs`

No amount of patching will give ideal results in all situations however, so I recommend readers take control of their reading experience by learning a bit about CSS stylesheets, removing DRM, and using tools such as Calibre to fix the publisher's bad choices at the source.

[GeoffR]

The following three patches can be used individually or in any combination:

1. `Custom left & right margins`

The margin adjustment slider has nine settings which allow the left/right margins to be increased by a percentage of the screen width. The increase is in addition to any @page or body margin set in the book by the publisher.

In the unpatched firmware the increments are 0%, 2%, 4%, 6%, 8%, 10%, 12%, 14%, 16%. At the highest setting almost one third of the screen is margin! The `Custom left & right margins` patch allows these nine values to be changed, the default patched increments are: 0%, 1%, 2%, 3%, 4%, 5%, 6%, 7%, 8%.


2. `Custom kepub default margins`

The KEPUB reader has an extra default left/right margin of 20px (25px on the Glo/Aura) which is added to the margin set in the book and by the adjustment slider. The `Custom kepub default margins`patch allows the size of this default margin to be changed. The default patched value is 5px.

The following screenshots (Glo, 3.15.0) show a synced KePub with the margin adjustment slider set to minimum:
1. Normal reading mode, without patch.
2. Normal reading mode, patched.
3. Full-screen reading mode, without patch
4. Full-screen reading mode, patched.

(Note that all screenshots are with the `Fix kepub side bearing font cut-off bug` patch applied, which makes the left/right margins an extra 0.2em larger.)


3. `ePub fixed/adjustable top/bottom margins`

(Note that in some firmware versions there were separate `ePub fixed top/bottom margins` and `ePub adjustable top/bottom margins` patches.)

This patch modifies the built-in EPUB stylesheet to set the top and bottom @page margins to either a fixed number of pixels, or to a variable size depending on the position of the margin adjustment slider. The left/right @page margins are set to zero. The margins set by this patch override the @page margins set in the book by the publisher.

The patch has three options, which can be changed independently:
1. Choose the top margin to be adjustable, or set a fixed size in px.
2. Choose the bottom margin to be adjustable, or set a fixed size in px.
3. Choose the adjustment multiple, a size in px that the adjustable top/bottom margins change by for each percent of screen width of the left/right margins set by the adjustment slider.

In full-screen reading mode the KEPUB reader sets the top/bottom margins to be equal to the left/right margin, so when you move the adjustment slider all four margins change. The adjustable top/bottom option of the `ePub fixed/adjustable top/bottom margins` patch adds a similar feature to the EPUB reader. However, unlike the KEPUB reader, the patch affects epubs in both normal and full-screen reading modes.

The images below are each a composite of nine screenshots showing a rectangle drawn to the maximum size available at each position of the margin slider:
1. Normal reading mode, default patch settings (adjustment multiple = 6px.)
2. Full-screen reading mode, adjustment multiple = 7px.


These screenshots were taken from the first page of this test book: margintest.epub on my Glo with firmware 3.15.0 and the `Custom reading footer style`, `Custom left & right margins` patches (with default patch settings) in addition to the `ePub fixed/adjustable top/bottom margins` patch.

Getting the most out of this patch might take a bit of trial and error, as the best choice of adjustment multiple depends not only on device type but on whether you use normal or full-screen reading mode.

In full-screen mode the adjustment multiple should be about 1% of the screen width (6px for Touch/Mini, 7-8px for Glo/Aura, 10-11px for AuraHD/H2O/GloHD), assuming there is no left/right body margin set in the book.

But in normal reading mode, because of the footer and small built-in top margin, it is impossible to get a value for the adjustment multiple that results in the top/bottom margin being proportional to the left/right at all slider settings unless a body margin is added to the book (which then messes with the proportionality in full-screen reading mode.) A value slightly less than 1% should give reasonable results except at the lowest slider positions.

[cramoisi]

Hi !
For this last one, can i enable the patch to have a adjustable top margin and add a body bottom-padding in the kobo_extra.css to enable it again ?

# Note that this patch has the side-effect of removing the body bottom padding
# from the built-in stylesheet, which means that there will no longer be a line
# of padding added automatically at the end of chapters.


Then, if I understand correctly, if I just want the top margin to be adjustable, I have to leave the top-margin line ( #replace_string = B82BBE, `%\01`, `2\05`) commented and uncomment the bottom-margin one and set it to 0px ?

[GeoffR]

Originally Posted by cramoisi

For this last one, can i enable the patch to have a adjustable top margin and add a body bottom-padding in the kobo_extra.css to enable it again ?

Yes. The built-in stylesheet has the style body { padding-bottom: %1em !important; } (where %1 is the current selected line height) which is removed to make space for the patch. You can get almost the same effect by adding body { padding-bottom: 1em !important; } to your kobo_extra.css.

Then, if I understand correctly, if I just want the top margin to be adjustable, I have to leave the top-margin line ( #replace_string = B82BBE, `%\01`, `2\05`) commented and uncomment the bottom-margin one and set it to 0px ?

Yes. But any fixed value will do, it doesn't have to be 0px.

[cramoisi]

Originally Posted by GeoffR

Yes. But any fixed value will do, it doesn't have to be 0px.

Ok, but if I leave it à 0px, the classic footer large footer will stay untouched, no ? (I want the footer to stay as it is in the default config)

[GeoffR]

Glyphs are drawn on the screen using an anti-aliasing technique that can make curves and diagonal lines look smooth, avoiding the jagged look caused by the individual pixels. This is acheived by adding shaded pixels to the glyph to give the illusion of partial pixels, but this also reduces the perceived sharpness of the glyph. Therefore, for a given pixel size, increased sharpness is gained only by a reduction in smoothness, and vice versa.

The TypeGenius feature allows the weight and sharpness of each font to be adjusted. (See the `Freedom to advanced font controls` patch to enable TypeGenius for sideloaded fonts.) Adjustng the sharpness allows the ideal balance of smoothness vs sharpness to suit individual preferences.

The table in the following screenshots (Glo 3.15.0) shows the range of weight and sharpness values that can be set from the slider. This is only a sample of the possible values, the slider actually allows much finer adjustment. (These screenshots were created from this demonstration kepub using the built-in Georgia and sideloaded Tex Gyre Bonum fonts, and are best viewed at 100% zoom to see the increase in sharpness from left to right):


In firmware versions up to 3.1.1 the advanced fonts menu had separate sliders for weight and sharpness which allowed any combination of values to be selected. But from firmware version 3.2.0 there is only one slider which sets both weight and sharpness, so an increase in weight results in an increase in sharpness too. In effect this means only the combination of values along a diagonal from the lower left to upper right of the above table can be selected.

The `ePub fixed font sharpness` and `KePub fixed font sharpness` patches allow a fixed sharpness value to be chosen, e.g. 0.0, 0.1, or 0.2, so that the sharpness value selected by the adjustment slider is ignored and only the weight value used. In effect this means that the slider can be used to select combinations from a vertical column instead of from the diagonal of the table above.

It is also possible to set the weight and sharpness independently without patching by editing the device's configuration file and changing the values of readingFontWeight and readingFontSharpness in the [Reading] section. While these patches only allow one fixed sharpness value to be selected, they avoid the need to re-edit the configuaation file after adjusting the weight via the slider.

[GeoffR]

The kobo firmware has some undocumented or experimental features that are not active by default, but which can be enabled in the [FeatureSettings] section of the device's configuration file .kobo/Kobo/Kobo eReader.conf.

The configuration file is a plain ASCII file with unix line breaks. When editing it, it is important to use an editor that doesn't change the file type or line break style. Most Linux and Mac text editors should be okay, but don't use Notepad or Wordpad in Windows: use an editor such as Notepad++ instead.

(Enabling these features doesn't require patching at all, but some patches work in conjunction with undocumented features, so I've included this post here for reference.)

An example of an undocumented feature is FullScreenReading which, once enabled, adds the following option to the Reading settings menu:


To enable a feature, e.g. FullScreenReading, edit the configuration file and add the new feature to the [FeatureSettings] section. (If there is not already a [FeatureSettings] section, then add that too.) The result should look like:

[FeatureSettings]
FullScreenReading=true

Additions to [FeatureSettings] will remain in place after a firmware update. If you want to disable the feature you can edit the configuration file again and change its setting from true to false.