Using SSH & SCP to Add Custom Remarkable Templates

Photo by Claudio Schwarz | @purzlbaum on Unsplash

Remarkable is an e-ink reading and writing tablet. It runs Codex, a custom Linux OS, and has a growing community of hackers and template creators.

I use mine for reading PDFs, doing sudoku puzzles, taking notes, planning my week, and tracking my daily tasks. For the later two I built two custom templates based on how I best organize my tasks.

Here's how I upload my custom templates and make them available on my tablet:

Download or create an .svg and .png copy of each template that you want to add. Other than the file extensions, you want both of these files to have the same name. I made mine with Sketch, but you can also download ones from the community, buy some from folks on Etsy, or email yourself a pdf from your tablet that you've drawn. Make sure that if you're creating your own that they do not have transparent backgrounds, which cause erase issues.

Look up your shh password & IP address. You'll find these on your tablet under Settings > Help > Copyrights and licenses > on the first page at the bottom.

We're going to use ssh, the SecureSHell program to connect to the tablet over usb. If you look at the tablet's Copyrights and licenses section, the sentence with the password gives an explanation of what we're doing: "This device acts as an USB ethernet device, and you can connect using the SSH protocol using the username 'root' and the password 'your password'". Put another way, the operating system on your computer will see the USB connection between your tablet and itself as a network connection just like it would between itself and any other network connection, such as your wifi router.

Lets test this connection. Attach your device to your computer via usb. Open terminal and type ssh root@10.11.99.1 and then when prompted your password. You should be rewarded with some pretty colors:

Take a few minutes to explore the file structure. We will be copying the template images to ../../usr/share/remarkable/templates/. Look around this folder and you'll see that there's a .png and a .svg for each of the templates. There's also some with an LS or P file name prefix, which denotes Landscape or Portrait, for templates with different layouts for each orientation. Exit your ssh session with control + D.

Let's get to copying! Navigate in Terminal to the folder that your template images are saved in. From here we are going to copy both of the template files to the tablet with scp, the Secure CoPy program. To do so we need to know the source of the files and the destination for the files. Since we navigated to the folder with the template images, the source directory is ./. In order to copy both .svg and .png in one go, we'll use .* as our file type. Together with the file name, this makes the source ./TemplateFileName.*. The destination is on our tablet, so we first need to use the username and IP address we used to shh, root@10.11.99.1. This address is followed up with the file path at that location where scp should put the copied files, ../../usr/share/remarkable/templates/. This makes the destination root@10.11.99.1:../../usr/share/remarkable/templates. The whole scp command is:

scp ./TemplateFileName.* root@10.11.99.1:../../usr/share/remarkable/templates

Confirm that your files copied by connecting back to your tablet with ssh root@10.11.99.1. The .svg and .png files should be in the usr/share/remarkable/templates/ directory. 🎉 The party isn't quite done yet, it's time to edit the file the tablet uses to know which templates are there.

In the templates folder you'll see the file templates.json. We're going to edit it with vi. Type vi templates.json and you'll open the vi text editor. The first object in the list of templates looks like this:

{
    "name": "Blank",
    "filename": "Blank",
    "iconCode": "\ue9fd",
    "landscape": true,
    "categories": [
        "Creative",
        "Lines",
        "Grids", 
        "Life/organize"
    ]
},

Let's break it down. "name" is the display name, this can have spaces in it and it doesn't need to match the filename. "filename" is the name of the template, without the .png or .svg extensions. "iconCode" refers to which thumbnail will be displayed with that template. You can pick which one you want for your template with this guide. "landscape" is true unless this is a portrait-only template, then it's false. "categories" lists which categories you'd like to have the template show up under.

For our template to show up we need to add a JSON object that will represent it. Bust out your Vim moves, copy the Blank object, paste a copy back in, and then edit it to that it matches your template's name, filename, and other properties. Save & exit Vim.

Now we need to tell our tablet to restart so it will re-read the templates.json file and "see" our new template. The Codex systemd is called xochitl. We'll tell it to restart with the command systemctl restart xochitl. While the tablet restarts exit your ssh with cmd+D. Once your tablet is up and running you can find your custom template among all the others.