rM2 version 3.20 installation

[timower]

I've been using 3.20 for a while, and it's been quite stable. So I thought I'd write down some installation notes, based on #32 so others can try as well.

Warning

As with any modification there are risks of boot loops. Make sure you have remarkable2-recovery working before trying!

Installation

I'm assuming you're already on 3.20, if not install it using codexctl.

0. Manual test

First you should verify that the rm2fb server works, and that xochitl can use it. For this download the install.tar.gz package from the v0.1.3 release.
Then transfer opt/bin/rm2fb_server, opt/lib/librm2fb_client.so and opt/bin/yaft (or any other app to test. To the device, I'm assuming all the binaries are in /home/root:

# First stop xochitl
> systemclt stop xochitl
# Next start the rm2fb server
> ./rm2fb_server
Trying to dlopen libqscepaper
Finding build ID
Build ID: 0x0f 0x18 0xb6 0x39 0xf6 0x05 0x2d 0xdb 0xf5 0x89 0x35 0x62 0x45 0xdb 0x66 0xc9 0x96 0x96 0xbe 0xe7
# < ... >
rm2fb-server started!
# The screen should have refreshed and be blank.

Now, in another terminal, start xochitl using the rm2fb client:

> env LD_PRELOAD=/home/root/librm2fb_client.so /usr/bin/xochitl
Build ID: 0x4f 0xa0 0xe9 0x51 0x3d 0x15 0x53 0xf3 0x4d 0xdc 0x89 0xba 0x65 0xbd 0xd5 0x69 0x92 0x92 0x93 0x9a
Hooking!
Hooking 73a3c0 with b6a4a2fc
Hooking 7919c8 with b69534dc
Hooking 739c80 with b6a49edc
debug: 2025-06-23T10:40:46Z heads/releases/3.20-lillipup 782f1ce
debug: we're running on an epaper device

Exit xochitl (either by pressing power off in the UI, or Ctrl-C in the terminal).
Now try yaft, to make sure other apps also work correctly:

> env LD_PRELOAD=/home/root/librm2fb_client.so /home/root/yaft
# The terminal should now show on the screen.

If everything worked, exit yaft (type exit on the reMarkable), and kill the rm2fb server by pressing Ctrl-C.

1. Making sure /home is mounted

Important

Data encryption is not supported, make sure it's disabled before continuing.

Newer xochitl versions support disk encryption, so /home is not mounted on startup, but only after entering the pin in xochitl. This won't work with toltec or the modifications we're going to do.
Modify /etc/fstab and comment out the line that starts with /dev/unknown, and add a new line that mounts /dev/mmcblk2p4 on /home:

/dev/mmcblk2p1       /var/lib/uboot/      vfat       defaults,nofail              0  2
# /dev/unknown         /home                ext4       defaults,nofail,noauto,x-systemd.after=xochitl.service,x-systemd.device-timeout=0 0  3
/dev/mmcblk2p4         /home                ext4       defaults,nofail 0  3

Now reboot and make sure everything is still working. Check systemctl --failed to make sure there are no failed units.

2. Re-enable or install toltec

Warning

Toltec on anything 3.3+ is not officially supported. Packages will break, and the toltec maintainers won't offer support.

Install toltec in the usual method, or re-enable an existing install. Make sure to disable any package that could cause issues (older rm2fb servers, anything that installs services, ...).
Also use the testing channel, as that has an updated wget that works correctly on 3.20:

> wget https://raw.githubusercontent.com/toltec-dev/toltec/refs/heads/testing/scripts/bootstrap/bootstrap
> bash bootstrap

3. Install the ipks

First stop xochitl again:

> systemctl stop xochitl

Download the rm2display.ipk (and any other apps you want) from the v0.1.3 release.
Install them using opkg:

> opkg install rm2display.ipk yaft.ipk rocket.ipk

Now you can test the rm2fb server:

> systemctl start rocket

If everything worked correctly, the rocket launch screen should show up.
Stop rocket, and make sure xochitl also still works:

> systemctl stop rocket
> systemctl start xochitl

Verify that the LD_PRELOAD was set correctly by checking journalctl:

> journalctl -u xochitl
# ...
Hooking!

You can now disable xochitl and enable rocket so it starts on boot:

> systemctl disable xochitl
> systemclt enable rocket

Next steps

I've only verified that xochitl, rocket, yaft, tilem and koreader work. I've not verified any other launchers, or packages from toltec.
The system changed significantly (move from Qt5 to Qt6) so expect many toltec packages to break.

[ngvt1n]

Hello, thank you for your work!

What happens when Toltec just gives

reMarkable: ~/ toltecctl reenable
ERROR: Unable to fetch updated version compatibility information, make sure you have a stable Wi-Fi connection
WARN:  Using outdated cached version compatibility information
ERROR: You’re running an unsupported OS version: 3.20.0.92
ERROR: Please monitor Toltec releases for upcoming support

when trying to reenable? I've downgraded to 3.3.2.1066 to install Toltec and upgraded to 3.20 again...

[donut-but-a-brain]

I may be wrong, but this looks like either you not having Toltec’s latest compatibility table or both that and Toltec’s main compatibility table not including 3.20 because it is experimental (remember, testing channel). In either case, the best mode of action is not to downgrade to 3.3 to install Toltec but rather to use the newer wget just on 3.20 as it says in the instructions.

[ngvt1n]

I did so, but installing Toltec on 3.20 still gives

ERROR: You’re running an unsupported OS version: 3.20.0.92
ERROR: Please monitor Toltec releases for upcoming support

because even testing channel's compatibility table doesn't support 3.20
https://github.com/toltec-dev/toltec/blob/b4888f13bf5112e6c24e3c6a9ab09af24718642c/package/Compatibility#L70C1-L70C15

[ngvt1n]

Ah nevermind, I just had to run bash bootstrap --force

[Eeems]

Ah nevermind, I just had to run bash bootstrap --force

This is not supported. Anybody reading this, this flag can and will result in broken systems, and is only meant for maintainers to work on adding new OS version support. Which is why it's not documented.

[Cyrus-Harding]

I tried following this guide. I have been running 3.8 with rm2fb for a while. My Remarkable 2 is now stuck at "reMarkable Paper tablet is starting". I can't connect via SSH.

I guess I have to get a pogopin adapter now. The fault is all mine, I should have looked into remarkable2-recovery beforehand.

[timower]

That sucks, I tried to warn you with the message at the top.
If you ever figure out what went wrong, let me know as I'd be happy to investigate!

[Cyrus-Harding]

It was my fault for ignoring that warning. It's all good. Hopefully when I get my parts in the post I'll be able to recover the device and maybe be able to report what was wrong.

[Cyrus-Harding]

I managed to restore my ReMarkable. I don't think I will try this again. Most of the functionality I got out of using KOReader is now in ReMarkable's OS.

When I followed the tutorial, my ReMarkable suddently restarted while doing the steps and that's when the bootloop started. I hope that helps somewhat. It happened on the third-to-last step.

[Cyrus-Harding]

Alright. I forgot that I still needed KOReader for some things and started retrying things.

The issue was that librm2fb_client.so is a symlink. Copying librm2fb_client.so.1.1.0 and renaming it to librm2fb_client.so seems to work.

I also forgot to edit etc/fstab last time 🤦.

The bootloops now started at "3. Install the ipks"

[timower]

Interesting, the symlink is expected, as some toltec package depend on the version specific so.
I think I just copied both, as that should work.

When during step '3.' did stuff start failing exactly.?

Ps, if you're feeling adventurous, I found a way to get koreader to work without modifying the system partition, by using nix.
More info here, but if you're not familiar with nix at all it might be even more daunting.