Instructions for patching firmware 3.12.0

[tshering]

Originally Posted by frostschutz

Have you ever tried/considered porting this to the Kobo so the device would patch itself after placing patch files in the USB storage?

At a certain point, I also considered doing this, but then decided against it on the following reasons:
I is a bit cumbersome to edit the patch files on the kobo. If one therefore has to involve a pc anyway, one can as well run the conversion script on it. But maybe many users do not need to modify the patch files. I do know know.

You can apply a patch only once. Otherwise you need a copy of the original file on the reader. If the script is supposed to make the back-up of the original file, it has to decide whether the current version on the reader is the original or already a patched version. Of course the user can still herself provide the back up. There would also be the possibility to back up the relevant files (if they are already known at that point) from the update package before the update package gets installed and deleted. But this seems to me also not very convenient from the perspective of the user.

[frostschutz]

Originally Posted by tshering

I is a bit cumbersome to edit the patch files on the kobo.

You mean using telnet and vi? :-)

Originally Posted by tshering

If one therefore has to involve a pc anyway

That's an interesting idea, actually... a patch selection screen on the Kobo itself? I didn't think that far. I won't be able to implement that part myself, not right away in any case; haven't figured out the frontend side of things yet.

Originally Posted by tshering

You can apply a patch only once. Otherwise you need a copy of the original file on the reader.

But that's the easy part. Kobo's busybox already has the necessary tools to create/apply/revert minimal binary patches that do not change size/offsets.

Originally Posted by tshering

it has to decide whether the current version on the reader is the original or already a patched version.

Yes, it'd probably have to track files with timestamps and checksums.

I'm aware of issues; I still think it's worth a try, so I'll see what I can come up with over the weekend.

[tshering]

Originally Posted by frostschutz

You mean using telnet and vi? :-)

Actually, I was thinking of the text editor that comes with KoboLauncher. Evidently,when I said that editing the files on the Kobo would be cumbersome, I had another group of users in mind then you had.

[GeoffR]

Originally Posted by Jellby

I wonder if "body>*" would work. "body>div, body>p" misses h1...h6 and blockquote at least.

I don't use kepub, sideloaded or not, so my interest is purely academical

Thanks again, I've updated the patches in post #57 to use this selector. I've also made the default padding 0.2em.

[GeoffR]

Here is a patch to make the line spacing and justification settings selected from the reading settings (Aa) menu take effect in some epubs where they wouldn't work before.

It works by changing the built-in epub stylesheet so that the line spacing and justification settings are overridden at body and paragraph <p> level, instead of just body level. This is similar to what the kepub reader does.

Note: It still won't work on those books where the publisher has used <div> instead of <p> for paragraphs.

Also note: This is not the ideal way to get these settings to take effect, as it can result in some line spacing or justification settings in the book being overridden when they really shouldn't be. The only way to get perfect results is to edit the book and fix the problems at source.

See the note in the patch about commenting out a line if you are using the `ePub adjustable top/bottom margins` or `ePub fixed top/bottom margin` patches, as this patch changes the same part of the stylesheet used by those patches.

Spoiler:

<Patch>
patch_name = `Enforce user line spacing and justification in ePubs`
patch_enable = `yes`
#
# This patch causes the line spacing and justification settings selected from
# the reading settings (Aa) menu to be applied at body and paragraph level,
# instead of just at body level. This will result in the settings taking effect
# for some books where they wouldn't before, but there will still be some books
# where they still won't take effect, and there may also be some books where
# they do take effect when they shouldn't. (The only way to get perfect results
# is to edit the epub and fix the problems at source.)
#
replace_string = C99AD0, `b\x00o\x00d\x00y\x00 \x00{\x00\n\x00`, `b\x00o\x00d\x00y\x00,\x00p\x00{\x00`
#
# Comment out the following line if the `ePub adjustable top/bottom margin` or
# `ePub fixed top/bottom margin` patches are enabled.
#
replace_string = C99B8E, `p\x00a\x00d\x00d\x00i\x00n\x00g\x00-\x00b\x00o\x00t\x00t\x00o\x00m\x00:\x00 \x00%\x001\x00e\x00m\x00 \x00!\x00i\x00m\x00p\x00o\x00r\x00t\x00a\x00n\x00t\x00;\x00\n\x00`, `}\x00 \x00b\x00o\x00d\x00y\x00 \x00{\x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00 \x00\n\x00`
</Patch>

[GeoffR]

These two patches can be applied individually or both together, and have the following effect on epub and/or kepub books:

The font sharpness value set by the weight/sharpness slider on the advanced font menu is ignored when setting the font sharpness for the book, and the fixed sharpness value set by the patch is used instead. This means the slider now only sets the font weight, and sharpness is set by the patch.

The sharpness values set by the slider range from -0.4 to 0.2 (default is -0.0666). The patch can be used to set one of three fixed values: 0.0, 0.1, or 0.2. (0.2 is maximum sharpness.)

The sharpness set by the slider is still shown in the preview window and recorded in the .conf file, it is only when viewed on the book page that the patch value is used. I haven't tested this much, I actually find it a bit difficult to tell the difference between normal sharpness and maximum sharpness, so let me know if you think you are getting a different result than when setting the sharpness manually in the .conf file.

Spoiler:

<Patch>
patch_name = `ePub fixed font sharpness`
patch_enable = `yes`
#
# This patch causes a fixed value for font sharpness to be used in epub books,
# instead of the value set by the advanced font sharpness/weight slider. The
# slider sharpness values range from -0.4(min.) to 0.2(max.), default -0.0666.
# This patch allows one of three fixed values: 0.0, 0.1, or 0.2.
#
replace_string = C99C10, `\x20\x00%\x001\x00`, `0\x00.\x000\x00`
#
# Replacement sharpness value: `0` = 0.0, `1` = 0.1, `2` = 0.2.
#
replace_string = C99C14, `0`, `2`
</Patch>


<Patch>
patch_name = `KePub fixed font sharpness`
patch_enable = `yes`
#
# This patch causes a fixed value for font sharpness to be used in kepub books,
# instead of the value set by the advanced font sharpness/weight slider. The
# slider sharpness values range from -0.4(min.) to 0.2(max.), default -0.0666.
# This patch allows one of three fixed values: 0.0, 0.1, or 0.2.
#
#     body { -kobo-font-sharpness: %1; -kobo-font-thickness: %2; }\n
# --> body{-kobo-font-sharpness:0.0/*%1*/;-kobo-font-thickness:%2}\n
replace_string = DB41F0, `b\x00o\x00d\x00y\x00 \x00{\x00 \x00-\x00k\x00o\x00b\x00o\x00-\x00f\x00o\x00n\x00t\x00-\x00s\x00h\x00a\x00r\x00p\x00n\x00e\x00s\x00s\x00:\x00 \x00%\x001\x00;\x00 \x00-\x00k\x00o\x00b\x00o\x00-\x00f\x00o\x00n\x00t\x00-\x00t\x00h\x00i\x00c\x00k\x00n\x00e\x00s\x00s\x00:\x00 \x00%\x002\x00;\x00 \x00}\x00\n\x00`, `b\x00o\x00d\x00y\x00{\x00-\x00k\x00o\x00b\x00o\x00-\x00f\x00o\x00n\x00t\x00-\x00s\x00h\x00a\x00r\x00p\x00n\x00e\x00s\x00s\x00:\x000\x00.\x000\x00/\x00*\x00%\x001\x00*\x00/\x00;\x00-\x00k\x00o\x00b\x00o\x00-\x00f\x00o\x00n\x00t\x00-\x00t\x00h\x00i\x00c\x00k\x00n\x00e\x00s\x00s\x00:\x00%\x002\x00}\x00\n\x00`
#
# Replacement sharpness value: `0` = 0.0, `1` = 0.1, `2` = 0.2.
#
replace_string = DB4228, `0`, `2`
</Patch>

[JSWolf]

I have a small amount of blank space at the top of the screen on my H2O. It's less then a line of blank space. Is there any way to get rid of this? I cannot say if it's a result of patching or not as I never used 3.12.0 unpatched.

[GeoffR]

Originally Posted by JSWolf

I have a small amount of blank space at the top of the screen on my H2O. It's less then a line of blank space. Is there any way to get rid of this? I cannot say if it's a result of patching or not as I never used 3.12.0 unpatched.

The viewport in the epub reader doesn't quite reach the top of the screen, there is a 15 pixel gap on the Glo, maybe different on other devices. I don't know of any way to get rid of it, other than to use full-screen reading mode.

The main problem for me is that it makes the screen look uneven when there is a coloured background, the 15 pixels at the top remain white and it looks ugly.

[JSWolf]

Originally Posted by GeoffR

The viewport in the epub reader doesn't quite reach the top of the screen, there is a 15 pixel gap on the Glo, maybe different on other devices. I don't know of any way to get rid of it, other than to use full-screen reading mode.

The main problem for me is that it makes the screen look uneven when there is a coloured background, the 15 pixels at the top remain white and it looks ugly.

When I took a screenshot of that PDF with the squares, the bit at the top came out black instead of just empty background. Yes, the H2O also has the 15 pixel dead space at the top. It is less noticeable in normal usage because of the smaller pixels.

I might try a negative @page for the top margin or a negative top margin in the body style and see what happens. My guess is it won't work. But I've nothing to lose by trying.

[GeoffR]

Originally Posted by JSWolf

When I took a screenshot of that PDF with the squares, the bit at the top came out black instead of just empty background. Yes, the H2O also has the 15 pixel dead space at the top. It is less noticeable in normal usage because of the smaller pixels.

That didn't happen when I took a screenshot, there was no top gap at all with pdfs on my Glo. There is a gap in the epub reader, but it doesn't show up as black in a screenshot. Perhaps it is a difference between the different models.

[JSWolf]

Originally Posted by GeoffR

That didn't happen when I took a screenshot, there was no top gap at all with pdfs on my Glo. There is a gap in the epub reader, but it doesn't show up as black in a screenshot. Perhaps it is a difference between the different models.

I don't recall a block space in a screenshot with ePub. But this is PDF. So maybe PDF is different.

[GeoffR]

I've updated the patch32lsb program from v0.7 to v0.10 to add these new features:

1. New keyword base_address = ADDRESS.

This allows the various replace_* keywords to use an address relative to ADDRESS. e.g. replace_string = OFFSET, OLD_STRING, NEW_STRING will replace the string at ADDRESS+OFFSET. (if not specified, then it defaults to base_address = 0, in which case OFFSET will just be an absolute address, as in previous versions.)

2. New keyword find_base_address = STRING

This searches for STRING and if it is found, and is unique, then base_address is set to point to the beginning of STRING. This allows patches which modify a unique constant string (such as the `Custom reading footer style` patch) to be applied without the address being specified, which means they don't need to be edited to work with different firmware versions (as long as the unique string is the same in the different versions.)

3. New keyword find_xor8_mask = STRING

This searches for a unique 8-bit xor mask for the unique string STRING. This allows the xor8 encoding for the patch to be set without specifying it explicitly with the encode_xor8 keyword. When used before the find_base_address keyword, this means that patches which modify a unique constant string (such as the `Custom reading footer style` patch) can be applied without the need to know either the address or xor encryption used.

4. New escape character: '\0' is now recognised as a synonym for `\x00`


Edit: Updated to version 0.10 which has a much more efficient implementation of find_xor8_mask. Windows and Linux executables should run at about the same speed as memmem() is no longer used.

The find_xor_mask function isn't actually needed at the moment because Kobo have not encrypted the strings we patch, but you can test it by uncommenting the #find_xor8_mask line and check the messages to see that it finds the xor mask value 00.

Edit2: The complete patch package for firmware 3.12.0 using the new version patch32lsb v0.10 is attached, which includes the patches from post #1 and the extra patches in post #2.

[alin72]

Hi, I'm having trouble adjusting the fixed top margin. It's set at 10px, and I tried to change it to 25px by editing replace_string = C99B8C, `\x20\x00p\x00a\x00d\x00d\x00i\x00n\x00g\x00-\x00b\x00o\x00t\x00t\x00o\x00m\x00:\x00\x20\x00%\x 001\x00e\x00m\x00\x20\x00!\x00i\x00m\x00p\x00o\x00 r\x00t\x00a\x00n\x00t\x00;\x00\n\x00`, `}\x00\n\x00@\x00p\x00a\x00g\x00e\x00\x20\x00{\x00 m\x00a\x00r\x00g\x00i\x00n\x00:\x001\x000\x00p\x00x\x00\x20\x000\x00\x20\x000\x00\x20\x000\ x00}\x00\n\x00b\x00o\x00d\x00y\x00\x20\x00{\x00`
# to 2\x005.
But it kept telling me there is an error...Could you help me out? Thank you & Happy new year!

[GeoffR]

Originally Posted by alin72

Hi, I'm having trouble adjusting the fixed top margin. It's set at 10px, and I tried to change it to 25px by editing replace_string = C99B8C, `\x20\x00p\x00a\x00d\x00d\x00i\x00n\x00g\x00-\x00b\x00o\x00t\x00t\x00o\x00m\x00:\x00\x20\x00%\x 001\x00e\x00m\x00\x20\x00!\x00i\x00m\x00p\x00o\x00 r\x00t\x00a\x00n\x00t\x00;\x00\n\x00`, `}\x00\n\x00@\x00p\x00a\x00g\x00e\x00\x20\x00{\x00 m\x00a\x00r\x00g\x00i\x00n\x00:\x001\x000\x00p\x00x\x00\x20\x000\x00\x20\x000\x00\x20\x000\ x00}\x00\n\x00b\x00o\x00d\x00y\x00\x20\x00{\x00`
# to 2\x005.
But it kept telling me there is an error...Could you help me out? Thank you & Happy new year!

Set the margin size by changing the very last line of the patch. The example changes it from 10px to 25px:

# Replacement value: a 2-digit number (margin size in pixels) seperated by \x00
# E.g. 25 = 2\x005, 30 = 3\x000, etc.
replace_string = C99BAC, `1\x000`, `2\x005`

If you wanted it bigger, say 40px, then change the last line to:

replace_string = C99BAC, `1\x000`, `4\x000`

[alin72]

Originally Posted by GeoffR

Set the margin size by changing the very last line of the patch. The example changes it from 10px to 25px:

# Replacement value: a 2-digit number (margin size in pixels) seperated by \x00
# E.g. 25 = 2\x005, 30 = 3\x000, etc.
replace_string = C99BAC, `1\x000`, `2\x005`

If you wanted it bigger, say 40px, then change the last line to:

replace_string = C99BAC, `1\x000`, `4\x000`

Do I have to comment out the alternative 1 since it sets the margin to 10px? Does this look right now if I want to change it to 25px? Sorry I'm terrible at codes and this is my very first Kobo device..
<Patch>
patch_name = `ePub fixed top/bottom margin`
patch_enable = `yes`
#
# If enabled, this patch sets the top/bottom page margins for ePubs to a fixed
# value by adding a line @page {margin:10px 0 0 0} or @page {margin:10px 0}
# to the built-in stylesheet.
# Note that it has the side-effect of overriding any existing @page margins
# set in the book's stylesheet and removing the pre-existing padding-bottom
# from the built-in stylesheet's body rule.
#
# Alternative 1: Custom top, zero bottom margin: @page {margin:10px 0 0 0}
#replace_string = C99B8C, `\x20\x00p\x00a\x00d\x00d\x00i\x00n\x00g\x00-\x00b\x00o\x00t\x00t\x00o\x00m\x00:\x00\x20\x00%\x 001\x00e\x00m\x00\x20\x00!\x00i\x00m\x00p\x00o\x00 r\x00t\x00a\x00n\x00t\x00;\x00\n\x00`, `}\x00\n\x00@\x00p\x00a\x00g\x00e\x00\x20\x00{\x00 m\x00a\x00r\x00g\x00i\x00n\x00:\x001\x000\x00p\x00 x\x00\x20\x000\x00\x20\x000\x00\x20\x000\x00}\x00\ n\x00b\x00o\x00d\x00y\x00\x20\x00{\x00`
#
# Alternative 2: Custom top and equal bottom margin: @page {margin:10px 0}
#replace_string = C99B8C, `\x20\x00p\x00a\x00d\x00d\x00i\x00n\x00g\x00-\x00b\x00o\x00t\x00t\x00o\x00m\x00:\x00\x20\x00%\x 001\x00e\x00m\x00\x20\x00!\x00i\x00m\x00p\x00o\x00 r\x00t\x00a\x00n\x00t\x00;\x00\n\x00`, `}\x00\n\x00@\x00p\x00a\x00g\x00e\x00\x20\x00{\x00 m\x00a\x00r\x00g\x00i\x00n\x00:\x001\x000\x00p\x00 x\x00\x20\x000\x00\x20\x00\x20\x00\x20\x00\x20\x00 }\x00\n\x00b\x00o\x00d\x00y\x00\x20\x00{\x00`
#
# Replacement value: a 2-digit number (margin size in pixels) seperated by \x00
# E.g. 25 = 2\x005, 30 = 3\x000, etc.
replace_string = C99BAC, `1\x000`, `2\x005`
</Patch>