Instructions for patching firmware 4.17.13694

[geek1011]

This patch thread is for firmware 4.17.13694 (cb7d9876184f6044b6ce1a8677dacef1ec9376c5) and 4.17.13651 (d06673211ea848c626ab33d4a9ff023b28b111fd).

Instructions for patching on Windows, Linux, or macOS with kobopatch:

1. Download the Kobo firmware release
   You can find the download links here here.
2. Download and extract the patch zip
   Download and unzip kobopatch_4.17.13694.zip from here.
3. Copy the firmware file to the src folder
   Copy the original firmware you just downloaded into the kobopatch src folder.
4. Install the firmware if needed
   Install the firmware on your kobo BEFORE proceeding with the next steps. You can do this by extracting the contents of the firmware zip into the .kobo folder and ejecting.
5. Choose your patches from the files in the src folder
   Enable patches in the files in the src folder (or use the overrides in kobopatch.yaml to keep your options separate).
6. Run kobopatch
   Double-click kobopatch.bat on Windows, or run ./kobopatch.sh on Linux.
7. Install the patches by copying KoboRoot.tgz into the .kobo folder of your device
   If the patching succeeded, a file named KoboRoot.tgz will be created in the out folder. Copy it to the .kobo folder of your device. Safely remove your device once you are finished. On Linux, you may have to press Ctrl+H to show the .kobo folder.

Download

This is the largest release (both for the patches and firmware) so far. The work for this release spanned over 3 firmware versions and took many hours of time (it usually only takes ~1 hour) from multiple contributors. A extra large thanks goes to jackie_w and NiLuJe for their extensive (at least 10 hours) of work for this release. Jackie put a lot of work and effort into updating and rewriting nickel patches, and she testing and cross-verified everything I updated. NiLuJe reviewed code for the kobopatch build script, my dotfiles mod for 4.17.13651, and the patch documentation. See the release notes below for full credits.

[geek1011]

Changes to the kobopatch zip:
v66 (2020-08-19): Fixed "Don't uppercase header/footer text" patches not applying to percent read text (geek1011).
v63 (2020-07-08): New "Increase page navigation history" patch (geek1011).
v52 (2019-09-21): Everything (no, really, literally everything changed). This is the largest patches release so far. See here for the details.

Missing patches:
- My 24 line spacing values (waiting for GeoffR to update).
- Custom font sizes (waiting for GeoffR to update).

Patches for other files / patches not in the main zip:
- GeoffR's variant of my toc indentation patch:

Spoiler:

Increase TOC level indentation and fix extra indentation bug (GeoffR's variant):
  - Enabled: yes
  - PatchGroup: TOC Indentation
  - Description: |
      The space indented Table of Contents levels are quite hard to see, as the
      difference is almost too small to easily notice. In addition, this fixes
      the bug where all TOC entries are indented by 1 level extra.
  - BaseAddress: 0x8BE302
  # Clear out existing instructions with NOPs
  - ReplaceBytes: {Offset: 0, FindH: 07 F1 0C 0B, ReplaceH: 00 20 00 20} # put string address in fp
  - ReplaceBytes: {Offset: 4, FindH: 42 00, ReplaceH: 00 20}             # shift level by 1 (multiply by 2) into r2
  - ReplaceBytes: {Offset: 6, FindH: 4F F0 20 01, ReplaceH: 00 20 00 20} # set r1 to 0x20 (space char)
  - ReplaceBytes: {Offset: 10, FindH: 58 46, ReplaceH: 00 20}            # put fp in r0
  # Put new instructions
  - ReplaceBytes: {Offset: 0, FindH: 00 20, ReplaceH: 40 1E}             # decrease level by 1
  - ReplaceBytes: {Offset: 2, FindH: 00 20, ReplaceH: 02 22}             # load multiplier into r2
  - ReplaceBytes: {Offset: 4, FindH: 00 20, ReplaceH: 42 43}             # multiply level, result into r2
  - ReplaceBytes: {Offset: 6, FindH: 00 20, ReplaceH: 20 21}             # set r1 to 0x20 (space char) 
  - ReplaceBytes: {Offset: 8, FindH: 00 20, ReplaceH: 05 A8}             # put string address (sp+20==r7+12) into r0
  - ReplaceBytes: {Offset: 10, FindH: 00 20, ReplaceH: 83 46}            # save r0 into fp
  # Replacement value (multiplier):
  - ReplaceInt: {Offset: 2, Find: 2, Replace: 6}

Notes about this firmware version:
- See the firmware threads for 4.16.13337, 4.17.13651, and 4.17.13694.

New patches in this version:
- See here.

There is also a new interactive demo to test out the different header/footer/margin patches and settings.

[JeanPierre]

Thank you so much.

[geek1011]

For convenience, here are the release notes copied from GitHub (please do not quote this post):

v52
This is the initial release for 4.17.13694 (plus 4.17.13651 and 4.16.13337 which were released the same week). This is one of the largest releases of both the patches and the firmware (the new reader interface, and quite a bit of refactoring since 4.15.12920).

This release would not have been possible without the extensive work of:

• jackie_w (@jackiew1), who did the majority of the testing, rewrote many CSS patches, worked on new patches, and helped find changes in the new firmware.
• GeoffR (@geoffreynolds), who made many of the original patches, and who will probably update a few more patches for the next release.
• NiLuJe (@NiLuJe), who provided help and code review where it was needed (and helped with another kobo-related project which will be made public soon).
• davidfor (@davidfor), who provided some information about the new firmware features on MobileRead.
• geek1011 (@geek1011), who updated the majority of the patches, worked on new patches, wrote the build script, and helped find changes in the new firmware.
• Kobo, who created the new reader interface, and fixed many bugs over the last few firmware releases.

Patch changes (4.16.13162+)
The usual patch updates (i.e. not different than between other firmware versions) are not listed here.

New:

• Allow showing info panel on random screensaver
  Allows showing the info panel while using a random screensaver (see here for how to use it). By @geek1011.
• Remove title from reading header/footer
  Removes the title/chapter name from the new reader's header/footer. By @geek1011.
• Reduce new header/footer height
  Reduces the height of the new reader's header/footer. By @jackiew1.
• Custom navigation menu page number text
  Changes the page number text above the scrubber. By @jackiew1.
• FeatureSettings/PowerSettings/DeveloperSettings patches
  A few patches have been made by @geek1011 to allow setting certain commonly-used configuration file settings as a patch. This is mainly intended for those who have multiple readers and/or want to automate changing settings.

Renamed:

• Increase the view details container size
  Renamed to Increase Book Details synopsis area along with updates by @jackiew1.
• Custom footer (page number text)
  Rewritten by @jackiew1 as Custom header/footer page number text.
• Dictionary text font-family/font-size/line-height - beta
  Updated by @jackiew1 as Dictionary text font-family/font-size/line-height and taken out of beta.
• Increase the cover size in library
  Rewritten by @jackiew1 as Increase library cover size.
• Custom font to collection and author titles
  Rewritten by @jackiew1 as Custom collection/author header title font.
• Enable rotation on all devices
  Renamed by @geek1011 to DeveloperSettings - ForceAllowLandscape because all it does now (it used to be more complex) is change a setting.
• Set slide to unlock
  Renamed by @geek1011 to PowerSettings - UnlockEnabled because all it does now (it used to be more complex) is change a setting.
• Wikipedia Search language
  Renamed to Change Wikipedia search language.
• Dictionary, remove long winded closest match notification
  Renamed to Shorten dictionary entry not found message.
• New home screen increasing cover size
  Renamed to Increase home screen cover size.

Rewritten:

• Increase size of kepub chapter progress chart
  Rewritten by @geek1011 to work with new firmware and make easier to update.
• Both buttons go next:
  Simplified by @geek1011.
• Increase Book Details synopsis area
  Rewritten by @jackiew1 to work with new firmware, add Libra values, and make easier to update.
• Increase library cover size
  Rewritten by @jackiew1 to make easier to update.
• Custom font for Collection/Author header titles
  Rewritten by @jackiew1 to work with new firmware and make easier to update.
• Many more patches have not been rewritten, but offsets have changed greatly compared to previous versions and needed to be found again by @geek1011.
• Other CSS patches have also been simplified and updated for the Libra by @jackiew1.

Removed:

• Clock display duration
  Not needed anymore, as there is now a persistent clock in the top-right of the new status bar (thanks Kobo!).
• Fix three KePub fullScreenReading bugs
  These bugs have been fixed since 4.11.11911, and haven't been seen since then.
• Always display chapter name on navigation menu
  The new reader view does this by default (thanks Kobo!).
• Fix reading stats/author name cut off when series is showing
  Now fixed in the firmware (thanks Kobo!).
• Remove extra space on selection menu
  Doesn't make a difference anymore.
• Set reading footer height
  Only applies to the old reader, not needed for new reader anymore (see Reduce new header/footer height).
• Rename settings
  Was made just to test something, not really used by anyone.
• Custom reading footer style
  Doesn't apply properly to the new reader, and would need to be completely rewritten anyways if it's even needed.
• Disable reading footer
  No effect on new reader view.
• Custom menubar - reduce height by 33/50%
  Not needed anymore.

Other:

• New cross-platform, reproducible, and fast build script
  The build script for the patches has been rewritten by @geek1011 in Go (see #19), and reviewed by @NiLuJe. It now works on Windows, is up to 30% faster, and produces identical outputs on multiple runs.
• Header/footer patch documentation
  A new interactive demo page has been made by @geek1011 (see #21) to help show the behavior different header/footer patches.

There have also been various grammar, spelling, and formatting fixes and improvements to many patches. Comments have also been updated to match the changes in recent firmware versions. Also, values for the Libra H2O (Storm) have been added to a number of CSS patches.

Changelog
This changelog has been somewhat abbreviated due to the large volume of changes. See the commit log for more details. Also, the versions listed are the versions which the change was directly made to. Usually, unless stated otherwise, this means the newer versions also inherited the change too.

Patrick Gaskin (@geek1011):

• 4.17.13651 4.17.13694 Added upgrade confirmation and upgrade blocking patches to a PatchGroup.
• 4.17.13651 4.17.13694 Added header/footer patch interactive demo (fixes #21).
• template Made patch template readme more consistent.
• 4.17.13651 4.17.13694 Updated description for "Reduce top/bottom page spacer".
• 4.17.13651 4.17.13694 Made patch arrangement more consistent.
• 4.17.13651 4.17.13694 Updated most patches for 4.17.13651.
• 4.17.13651 4.17.13694 Added testdata for 4.17.13651 (and it was released the day after we finally finished the previous version...).
• 4.17.13651 Added note about how to prevent Kobo from importing dotfiles/folders (and made a LD_PRELOAD mod for it).
• scripts Fixes, improvements, and refactoring for new build script.
• 4.17.13651 New "Remove title from reading header/footer" patch.
• 4.17.13651 Removed some unnecessary zero offsets from ReplaceZlib instructions.
• 4.17.13651 Added documentation for build and test scripts.
• 4.17.13651 Removed 4.16.13337 (replaced by 4.17.13651, not on any released device anymore).
• 4.16.13337 4.17.13651 Tested 7 libnickel patches, offsets, and numbers.
• 4.16.13337 4.17.13651 Updated TODO list and notes for 4.17.13651.
• 4.16.13337 4.17.13651 Made spacing of patch files more consistent.
• 4.17.13651 Updated most of GeoffR's patches for 4.17.13651.
• 4.17.13651 Ported my patches to 4.17.13651.
• 4.17.13651 Started updating patches for 4.17.13651 based on work for 4.16.13337.
• 4.17.13651 Added testdata for 4.17.13651.
• 4.16.13337 Updated jcn363's patches for 4.16.13337.
• 4.16.13337 Updated jackie_w's libnickel patches for 4.16.13337.
• build Updated Drone script for new build tool.
• scripts Rewrote build script in Go.
• template Make kobopatch.sh executable.
• 4.16.13337 Updated nickel patches for 4.16.13337.
• 4.16.13337 Updated libadobe and librmsdk patches for 4.16.13337.
• 4.16.13337 Added testdata for 4.16.13337.
• 4.16.13162 Added config file override patches (FeatureSettings, DeveloperSettings).
• 4.16.13162 New "Allow showing info panel on random screensaver" patch.
• 4.16.13162 Rewrote "Increase size of kepub chapter progress chart" patch.
• build Set pipefail in Drone script.
• 4.16.13162 Updated more patches for 4.16.13162.
• 4.16.13162 Updated most patches for 4.16.13162.
• 4.16.13162 Added testdata for 4.16.13162.

NiLuJe (@NiLuJe):

• 4.16.13162 Improved "DeveloperSettings - AutoUsbGadget" patch description.

NiLuJe has also done quite a bit of code review and has been helpful in general with updating the patches.

Jackie (@jackiew1, jackie_w):

• 4.17.13651 4.17.13694 Added new "Reduce new header/footer height" patch.
• 4.17.13651 4.17.13694 Updated comments for "New home screen increasing cover size".
• 4.17.13651 4.17.13694 Updated "New home screen increasing cover size" for Libra H2O.
• 4.17.13651 4.17.13694 Updated "Custom synopsis font size" for Libra H2O.
• 4.17.13651 4.17.13694 Updated "Custom synopsis details line spacing" for Libra H2O.
• 4.17.13651 4.17.13694 Updated "Reduce top/bottom page spacer" for Libra H2O.
• 4.17.13651 4.17.13694 Rewrote oren64's "Custom font for Collection/Author header titles" patch.
• 4.17.13651 4.17.13694 Updated "Reduce top/bottom page spacer" for Libra H2O.
• 4.17.13651 4.17.13694 Cleaned up description and comments for "Dictionary text font-family/font-size/line-height".
• 4.17.13651 4.17.13694 Added new "Custom navigation menu page number text" patch.
• 4.17.13651 Tested "Both page turn sides go next".
• 4.17.13651 Updated and improved "Dictionary text font-family/font-size/line-height".
• 4.17.13651 Rewrote "Custom header/footer page number text".
• 4.17.13651 Checked rmsdk patches.
• 4.17.13651 Increased specificity of "Reduce top/bottom page spacer" selector.
• 4.17.13651 Rewrote "Increase library cover size"
• 4.17.13651 Rewrote a few of oren64's patches.

Jackie has also done a lot of testing and debugging over PMs on MobileRead.

Geoff Reynolds (@geoffreynolds, GeoffR):

• Will probably be updating the 24 line spacing values and custom font sizes patches soon.

Simon (@snarkophilus):

• template Added Cygwin support to kobopatch.sh.

[poczynek]

Absolutely perfect! Thanks so much for the team effort.

Just installed and all great - for me the 'Reduce new header/footer height' was exactly the one i was waiting for. Thanks Jackie for that one!

Out of interest, the most annoying thing for me is that it doesn't take much for it to turn upside down when tilted slightly. Is there any way to lock it so that the buttons are always on the right and won't adjust when tilted?

Thanks again.

FYI how good is the demo mode!

[Uncle Robin]

Originally Posted by geek1011

Changes to the kobopatch zip:
v52 (2019-09-21): Everything (no, really, literally everything changed). This is the largest patches release so far. See here for the details.

There is also a new interactive demo to test out the different header/footer/margin patches and settings.

This great, thank you SO MUCH to you and all the Kobo Crafting Crew.

It's great to have advanced controls back for sideloaded fonts, and the interactive demo is a work of genius, thanks! One thing I wasn't sure of, does using the patch for "Book Progress Off" affect the progress bar? At the moment, that's all I have showing anyway, with header and footer off. If I can gain an extra line while keeping the bar, great, if not I'll leave it as is. Thanks again to everyone who worked so hard to get these patches ready for us

[geek1011]

Originally Posted by poczynek

Absolutely perfect! Thanks so much for the team effort.

No problem!

Out of interest, the most annoying thing for me is that it doesn't take much for it to turn upside down when tilted slightly. Is there any way to lock it so that the buttons are always on the right and won't adjust when tilted?

Probably. I'll look into this next week (I need a break from all of these updates).

Originally Posted by Uncle Robin

This great, thank you SO MUCH to you and all the Kobo Crafting Crew.

No problem! And I wonder what Jackie and NiLuJe will think of our new name .

It's great to have advanced controls back for sideloaded fonts, and the interactive demo is a work of genius, thanks! One thing I wasn't sure of, does using the patch for "Book Progress Off" affect the progress bar? At the moment, that's all I have showing anyway, with header and footer off. If I can gain an extra line while keeping the bar, great, if not I'll leave it as is. Thanks again to everyone who worked so hard to get these patches ready for us

Nope, it doesn't affect the progress bar. And thanks for reminding me that it exists (I forgot about it when making the demo), I'll add it in a moment. Update: done.

[MGlitch]

trying to run this on Mac OS X I get

-bash: /Users/Glitch/Downloads/Kobopatch 4.17/kobopatch.sh: /bin/bash^M: bad interpreter: No such file or directory
iMac:Kobopatch 4.17 Glitch$

I renamed the Kobo Patch folder, but this was happening with the original name.

4.17.13694 firmware zip is in the src folder.

[geek1011]

Originally Posted by MGlitch

trying to run this on Mac OS X I get

-bash: /Users/Glitch/Downloads/Kobopatch 4.17/kobopatch.sh: /bin/bash^M: bad interpreter: No such file or directory
iMac:Kobopatch 4.17 Glitch$

I renamed the Kobo Patch folder, but this was happening with the original name.

4.17.13694 firmware zip is in the src folder.

Ok, just run ./bin/kobopatch-darwin-64bit. I'll fix that in a moment. That was a regression in the build script line ending conversions. I've fixed it, and it is currently rebuilding. The updated zips will show up in a minute.

[JeanPierre]

Originally Posted by MGlitch

trying to run this on Mac OS X I get

-bash: /Users/Glitch/Downloads/Kobopatch 4.17/kobopatch.sh: /bin/bash^M: bad interpreter: No such file or directory
iMac:Kobopatch 4.17 Glitch$

I renamed the Kobo Patch folder, but this was happening with the original name.

4.17.13694 firmware zip is in the src folder.

I was getting this too but just copied over the kobopatch.sh from the previous version I was using and everything built ok (kobopatch_4.15.12920_v47).

[MGlitch]

Originally Posted by geek1011

Ok, just run ./bin/kobopatch-darwin-64bit. I'll fix that in a moment. That was a regression in the build script line ending conversions. I've fixed it, and it is currently rebuilding. The updated zips will show up in a minute.

Many thanks, nice to have the full screen back for my text.

Of interesting note, the progress bar doesn't take up a line of usable space (well maybe if you got the text to be as small as it is), but you CAN get text to ride right up to it. At least I was with the available patches, using Deja Vu Serif eink font. I did modify one patch of GeoffR's, reduce top/bottom page space I replaced the 28 value of the One/Forma with 14. Then it was just tinkering with font size / line spacing in the typeface settings until I was satisfied.

I'll probably mess around w/ it more when two missing patches (24 line spacing, and custom font sizes by GeoffR) are added. But this would just be to see if I could fine tune the font size/line spacing. As it is I've got the text to be right to the edge of my Forma, 8" of text? Yes please, and thanks to all you patch writers

[droopy]

thanks for this, Kewl Kobo Krafters !

[NiLuJe]

Yeah, AFAICT, the progress bar is essentially an overlay, it doesn't affect page layout at all. If you check on a cover page, you should be able to see a few lines of the image *below* the progress bar .

(I've mentioned this in a couple of not-quite-relevant places already, but this time it might actually be the right place .)

[MGlitch]

Ah good to know. I mentioned it didn’t seem to affect the lines per page in one of the 4.17 firmware threads but that was of course prepatch when the pesky top and bottom spacing was lingering.

It always surprises me how much space Kobo throws away.

[SusanReads]

This patching business looks interesting, but I would love it of someone helps me explain what I have to do at step 5: Choose your patches from the files in the src folder
Enable patches in the files in the src folder (or use the overrides in kobopatch.yaml to keep your options separate).

How the heck do I do this? Is there a tutorial for not-so-tech-smart people?