The reMarkable 2 Tablet as a Coding & Writing Device

I want to code on my balcony — in the sunlight, without evil blue display light!

We all spend too much time in front of blue screens — and we all get more restless or distracted, when facing with the many options a laptop screen provides. That’s why I love e-paper products like the reMarkable that, as a software engineer, allow me to be productive designing systems, writing or coding without being on a bright screen.

The rM2 provides SSH access in order to alter almost any aspect of its software. There is an awesome community of developers, that is ready to help you in the Discord channel should you face problems. They also have provided a smörgåsbord of apps that you can install as well as a wiki if you are a bit adventurous and don’t mind getting your hands dirty.

However, if you want to use the newest version of the tablet, the rM2, there are some “gotchas” we need to cover if you want to use it as a typewriter / coding tablet.

• The USB-C-connector isn’t powered anymore (compared to rM1)
• Some apps don’t work anymore out-of-the-box.
• Bonus: You might want to use a non-US keyboard layout (see chapter 6)

Below find a schematics, how the Hardware and Software setup for this project will pan out — Let’s get started!

Hardware and Software setup for reMarkable 2 as a Coding & Writing Device

0. Hardware, Prequisites and Disclaimers

First things first: I am not responsible for any damage done to your device, brain, etc. Commands executed here mess with the operating system of the rM2 and while it is unlikely that you will brick your device beyond repair, some reconfigurations (especially in step 1) can make the primary rM2 app “vanish” if executed improperly and can pump your heart rate up until you find a way to reset them to the previous state, so know what you are doing and settle in for some thrill while you mock a shiny 300$ gadget. (Trust me, I’ve been there.)

Speaking of which: while it doesn’t require deep proficiency in it, it helps if you have at least “half-knowledge” of the usual linux tools including “ssh”, “make”, “qmake”, as well as “docker”.

Finally, since software is faster than hardware: in order to connect a keyboard to the rM2, you need to buy or build some sort of USB adapter. So order it before (or while) you work on the software part described below.

There are multiple options: the reMarkable community is currently working on a connector that makes use of the “pogo pins” on the left rim of the tablet. Those carry USB but are de-activated by default. Fashioning an adapter, at least for me, seemed very finnicky.

The easier option seems to me to order a Y-cable like this one (thanks isman7, source) which can power the attached keyboard (as well as the tablet). That assumes that you can connect the USB cable with the red ribbon to a charger, powerbank or similar USB power source whenever you type on the keyboard. You will also need any USB-On-the-Go-adapter in order to attach the contraption to the tablet.

Side Note: Using the “pogo pins” also requires the USB-C-connector to be powered in order to serve the pins with power; the only benefit you would get in using the pogo pins is therefore not having to re-configure the USB-C-connector between “gadget” and “host mode”, see chapter 5.

1. Prepare Your rM2 to host Third-Party Apps

The rM2 runs a custom lightweight Linux distribution called “Codex”. The UI the user will normally see on the e-paper display is a daemon service named “xochitl” which will draw a Qt application directly to a framebuffer. Other apps “hack” into this interface by pausing this daemon service and then drawing on the framebuffer themselves. You can modify almost any aspect of the rM2 by accessing the device via SSH.

Step 1.1: Get SSH access to the rM2 tablet

Follow the instructions at https://remarkablewiki.com/tech/ssh in order to SSH into the rM2 tablet. Note that you void the warranty when ssh-ing into the tablet, you will probably not brick your device, but make sure that you know what you’re doing!

Step 1.2: Install the toltec toolchain

The toltec package manager is an application that lets you load other applications onto the reMarkable using the command “opkg”. Follow the instructions to “Install Toltec” after you ssh-ed into your rM2 tablet.

Step 1.3: Install rm2fb-client

The framebuffer handling changed between the earlier “reMarkable” and the newer “reMarkable 2” tablet. In order to use most apps under rM2 you need to

opkg install rm2fb-client

(Edit: this used to be rm2fb , now rm2fb-client .)

Step 1.4: Install an App Launcher: remux

Remux is a launcher that lets you switch between apps. There are others, like draft, but I found that to be not quite working with rM2 out-of-the-box. Draft and remux both manage which launchable apps to display by interpreting files in /opt/etc/draft/*.draft on the device.

opkg install remux

2. Connect your rM2 Keyboard

How to connect the USB-Y-Cable & USB-OTG-Adapter

Use the Y cable from Chapter 0. as well as an USB-On-the-Go-Adapter and connect them to the keyboard as follows:

• male with red ribbon goes into the power source
• male without red ribbon goes into the USB-On-the-Go-Adapter
• USB keyboard goes into female

Then, via SSH on your reMarkable, execute:

echo host > /sys/kernel/debug/ci_hdrc.0/role

Test it: If you now click the “Search” icon on your rM2 main app, you should be able to type with the keyboard!

Side Note: above command puts the USB-C-Connector into USB-On-the-Go mode. If you plan to connect your reMarkable to your computer later, in order to, e.g., transfer files back and forth, you will have to re-run above command with “gadget” instead of “host” or re-start your rM2 tablet. Consequently, in order to use your keyboard without clumsily entering this command every time, we will have to automate the execution of the command above— see chapter 5.

3. A Markdown Editor for Your rM2: “Keywriter”

A portion of this article was written with keywriter on the reMarkable 2

“Keywriter” is a simple markdown editor which you can use with a keyboard and the rM2 in landscape orientation.

Step 3.1: Download Keywriter to your rM2

According to the Github readme, downloading the binary should work, so on your rM2 do:

wget https://github.com/dps/remarkable-keywriter/raw/master/prebuilt/keywriter
mv keywriter /opt/bin/keywriter
mkdir ~/edit  # default directory expected by keywriter
touch ~/edit/scratch.md  # default file expected by keywriter

Step 3.2: Set up a keywriter.draft file

In order to launch keywriter from remux, create an keywriter.draft file:

cat /opt/etc/draft/keywriter.draft <<EOF
name=keywriter
desc=Markdown Editor
call=/opt/bin/keywriter
term=:
imgFile=keyboard
EOF

Step 3.3: Try it out

If you connected your keyboard and activated USB host mode (see chapter 2) you can bring up keywriter by swiping up on the right rim of your tablet. Select “keywriter” to launch keywriter. Esc switches between edit and markdown preview mode, Ctrl+K lets you switch to another *.md file.

4. A Console For Your rM2: “Fingerterm”

Fingerterm in action

There is a ready-made console for remarkable tablets called fingerterm. It’s actually an old Nokia app which was ported over to the reMarkable platform.

Step 4.1: (Attempt to) Install Fingerterm via opkg

Install it like this:

opkg install fingerterm
cat /etc/draft/fingerterm.draft # check whether *.draft file was written

Now you should be able to see this new application in remux: bring up the remux launcher by swiping up on the right side of your rM2 and touch the entry “fingerterm”.

Unfortunately at time of writing this article fingerterm didn’t work with the most current firmware updates so we have to do some more manual work: we are going to build it from scratch using the toltec-dev toolchain.

Step 4.2: Check out the fingerterm-reMarkable sources

Having git installed, check out fingerterm-reMarkable sources to

git clone https://github.com/dixonary/fingerterm-reMarkable.git fingerterm-reMarkable

Step 4.3: Set up the toltec-dev toolchain (Docker required)

There are multiple “toolchains” in order to develop for the rM2. Since I like to compartementalize everything I do on my machine as much as possible, I am a huge fan of Docker. This tutorial assumes that you have Docker installed, e.g. for Ubuntu start here. After installing it, downloading the toltec toolchain v2.0.1 is as easy as:

docker run -it --rm --network host -v `pwd`/fingerterm-reMarkable:/src ghcr.io/toltec-dev/qt:v2.0.1 bash

Note that -v `pwd`/fingerterm-reMarkable already mounts the repo you checked out above into the docker container.

Step 4.4: Inside Docker, build fingerterm

After executing the command above, you find yourself dropped into the toltec-dev docker. Here, execute:

cd /src
qmake -project fingerterm.pro
make
exit

Step 4.5: Copy Artifacts over to your reMarkable

On your rM2, create the following directories:

mkdir -p /usr/share/fingerterm/icons
mkdir -p /usr/share/fingerterm/data

Then, from from your computer, copy over the artifacts you built in Step 4:

cd fingerterm-reMarkable
scp qml/*.qml root@remarkable:/usr/share/fingerterm
scp data/* root@remarkable:/usr/share/fingerterm/data
scp icons/* root@remarkable:/usr/share/fingerterm/icons
scp fingerterm root@remarkable:/opt/bin/fingerterm

Step 4.6: Try that it works

Finally, you should be able to open up fingerterm via remux (bring it up by swiping up on the right side of your screen) — then tapping “fingerterm”. In case you have problems opening it, kill all running applications in remux by tapping on the memory metrics shown next to them, and then, via ssh, execute:

/opt/bin/fingerterm

… you should see something like:

EPD platform plugin loaded!
QStandardPaths: XDG_RUNTIME_DIR not set, defaulting to '/tmp/runtime-root'
Framebuffer has wrong id: "mxs-lcdif"
QFSFileEngine::map: Mapping a file beyond its size is not portable
Framebuffer initialized: QImage(QSize(260, 1408),format=QImage::Format_RGB16,depth=16,devicePixelRatio=1,bytesPerLine=1040,sizeInBytes=1464320) 33554432
file:///usr/share/fingerterm/Main.qml:312:13: QML Connections: Implicitly defined onFoo properties in Connections are deprecated. Use this syntax instead: function onFoo(<arguments>) { ... }
file:///usr/share/fingerterm/Main.qml:245:13: QML Connections: Implicitly defined onFoo properties in Connections are deprecated. Use this syntax instead: function onFoo(<arguments>) { ... }
file:///usr/share/fingerterm/Keyboard.qml:130:5: QML Connections: Implicitly defined onFoo properties in Connections are deprecated. Use this syntax instead: function onFoo(<arguments>) { ... }
Creating window

5. Automatically turn on USB-On-the-Go / Host Mode

The remux launcher with the additional “…-keys” launch configurations that configure the keyboard.

Until now, we need to execute

echo host > /sys/kernel/debug/ci_hdrc.0/role

manually after each re-start of the rM2 in order to bring it into USB-On-the-Go mode. A simple way to “automate” that is to create a *.draft file that automatically executes this command before starting “fingerterm” or “keywriter”.

Step 5.1: Create a helper script that sets up the keyboard

The following snippet creates a setup_keys.sh script that executes the USB host setup routine:

cat > ~/setup_keys.sh <<EOF
#!/bin/bash
echo host > /sys/kernel/debug/ci_hdrc.0/role 2>/dev/null
EOF
chmod +x ~/setup_keys.sh

Step 5.2: Create a wrapper script for fingerterm and keywriter

Now, create a script that launches the setup_keys.sh script before it launches the actual application

cat > ~/fingerterm_keys.sh <<EOF
#!/bin/bash
. ~/setup_keys.sh
/opt/bin/fingerterm
EOF
cat > ~/keywriter_keys.sh <<EOF
#!/bin/bash
. ~/setup_keys.sh
/opt/bin/keywriter
EOF
chmod +x *_keys.sh

Step 5.3: Create a draft launch config for the wrapper scripts

In order to launch those scripts from remux, we still need *.draft files:

cat /opt/etc/draft/keywriter.draft <<EOF
name=keywriter-keys
desc=Markdown Editor (with Keyboard Setup)
call=/home/root/keywriter-keys.sh
term=:
imgFile=keyboard
EOF
cat /opt/etc/draft/keywriter.draft <<EOF
name=fingerterm-keys
desc=Fingerterm Terminal (with Keyboard Setup)
call=/home/root/fingerterm-keys.sh
term=:
imgFile=keyboard
EOF

Step 5.4: Try it out

Open remux by swiping up on the right rim of the screen. Even after a rM2 restart, you should be able to launch keywriter-keys and fingerterm-keys, connect your keyboard paraphernalia and start hacking!

6. Bonus: Using a Different Keyboard Layout

In order to get your ultimate writing-/coding-peace-of-mind you might want to have your native keyboard layout setup. Setting the keyboard to another language, however, is tricky:

Turns out that the Qt applications in the reMarkable don’t use the keyboard layout set on the command line (via loadkeys / localectl) neither do they use an X-Server (so setxkbmap doesn't work either). Like other embedded systems, they access the keyboard directly as described here (thanks to developers @Eeems and Alex0809 for the hint).

You’ll need to do two things:

Step 6.1: Get a qmap file for your keyboard layout

First, on any linux system, create a kmap file from your layout (mine is German, i.e. de ):

ckbcomp -layout de > my-layout.kmap

Then, get the tool kmap2qmap from Qt. I did that by building Qt (more specifically, qttools/src/kmap2qmap) from sources — building Qt from source is a bit involved, but you can start here: https://doc.qt.io/qt-5/build-sources.html

Once you have the kmap2qmap binary, create a qmap file (you can ignore the warnings about undefined symbols), and copy it over to your remarkable:

./kmap2qmap my-layout.kmap my-layout.qmap
scp my-layout.qmap root@remarkable:/home/root/my-layout.qmap

Step 6.2: Modify the setup-keys.sh script to load your keyboard map

Change the setup_keys.sh script — add at its end:

export QT_QPA_EVDEV_KEYBOARD_PARAMETERS="/dev/input/event3:grab=1:keymap=/home/root/my-layout.qmap"

Caveat: You need to “kill” when switching between applications

The grab=1 leads to the keyboard being dedicatedly reserved for the launched application until the application itself is terminated. This means, that you will manually need to kill the application before switching to another application that uses the keyboard (e.g. if you use the keyboard in two separate applications, like fingerterm-keys and keywriter-keys). In remux you do that by tapping the memory stats displayed next to the application when switching, e.g., between fingerterm-keys and keywriter-keys .