Toltec

I've been spending a lot of time in the unofficial reMarkable Discord server.

Because of this, I've had the privilege of being able to work alongside other members on a joint project; the toltec repository.

matteodelabre, LinusCDE, raisjn, and I were all starting to work on building an opkg repository that hosted packages for the reMarkable (Since we could already use entware). Well, to be fair matteodelabre had a repo almost complete. raisjn and I were starting to explore what options there were, and if it would make sense to use opkg or pacman. Due to this we decided to work together on matteodelabre's project instead of duplicating effort.

The BHAG that I have for the reMarkable community, is to create an ecosystem that is simple for end users. This includes developers. I want the ecosystem to solve all the hard problems, so that developers and power users can focus on creating user focused applications, or simplifying their workflow. That's a lot to ask for, but I do think we are on the right path with a central repository to handle installing applications from. That along with nao, a UI for opkg written in bash + SAS, makes it so that users can easily install applications on their device with the tap of a button. Pair that with Oxide and you've got a fairly feature-rich environment to start hacking in.

So that's cool, how do I use/install it?

Installing toltec is fairly simple. It can be installed on both the original reMarkable tablet, and the reMarkable 2. If you install on the reMarkable 2, you will need to make sure to install the rm2fb package (now named display) for applications to be able to use the screen.

1h video recording of "Discovering how to install software on the reMarkable with Eeems using Toltec/opkg/entware" from RemarkableTablet

_{You can also watch Utopiah and myself talking through installing and using toltec in this reddit post}

1. Connect to your device

The first thing you'll need to do is to connect to your device over SSH. On Linux or macOS it's as simple as doing the following:

ssh root@remarkable

For Windows users, a good option for an SSH client is PuTTY.

I highly recommend using a ssh key so that you don't have to keep entering your password. On Linux or macOS, assuming you already have a ssh key generated it's as simple as using the following command:

ssh-copy-id root@remarkable

2. Backup

While installing toltec is a fairly risk free endeavour, it's always good to make sure that you have your data backed-up. The simplest way to do that is to copy the contents of /home/root/.local/share/remarkable/xochitl/ from your reMarkable to your computer. This can be done with scp on macOS / Linux, or with a tool like WinSCP on Windows.

mkdir -p remarkable-backup/files
scp -r root@remarkable:~/.local/share/remarkable/xochitl/ remarkable-backup/files/

You may also want to grab a copy of your configuration file, or at the very least keep a copy of the ssh password of your device somewhere safe.

scp root@remarkable:~/.config/remarkable/xochitl.conf remarkable-backup/remarkable.conf

3. Install Toltec

This section is out of date. Please go to the toltec website to get the latest instructions and warnings.

We've tried our best to make the installation of toltec as simple as possible, while remaining security conscious. The first thing you'll need to do is SSH into your device. After you've connected, you'll need to download the bootstrap script with the following command. You'll also need to make sure your reMarkable is connected to the internet.

wget http://toltec-dev.org/bootstrap

This script is used to install entware on the device, and get it set up with the toltec repository. After you've downloaded the script, you'll want to confirm that nothing happened to it while it was in transit to your device:

echo "cbe83d1ae2d3ef6291a2b57202bb59aace14f2f1849bbdb09552a7419995294a  bootstrap" | sha256sum -c

You'll want to grab the latest copy of this line from the toltec website itself. Please read the up-to-date instructions and warnings from the official site.

This will tell you if the file has been modified while it was being downloaded. If everything checks out, you will then need to run the script:

bash bootstrap

After it's finished running, entware will be installed and configured to use the toltec repository.

4. Interacting with toltec

Now that you've got everything setup it's fairly easy to install new applications:

opkg install <application>

Removing applications that you've installed is just as simple:

opkg remove <application>

Updating your installed applications is slightly more complex:

opkg update
opkg upgrade

Now, all of this requires you to be at a computer, or to have a terminal application like fingerterm or yaft installed on your device. Instead, you can install nao alongside a launcher (like Oxide, remux, or draft) to manage applications.

opkg install draft
opkg install nao
systemctl stop xochitl
systemctl start draft

I've recorded a short video of using nao on the reMarkable that you can watch below: