rmkit

rmkit + fbink = more kobo (2024)

Fri, 16 Feb 2024 00:00:00 -0800

My new year’s project for 2024 was to add Kobo support to rmkit. If this is giving you deja vu, that’s because I had the same project for 2022 :-D

Thanks to help from NiLuJe, elinkser, pgaskin, sherm_p and others, rmkit now supports FBInk as a backend. What this means is that rmkit will support many more Kobo devices out of the box. In fact, rmkit now has the potential to support other devices that are supported by FBInk.

If you have a kobo, you are able to use the KoboRoot.tgz on the build server to easily install remux and other applications.

See remux and other apps in action on the Libra H20

See the announcement post on MR here

Supported platforms

All platforms that fbink supports should now work with rmkit, minus a few exceptions (f.e. the KA1)

What it took to get working

In order to get Kobo support working, a few things had to happen:

Use FBInk as a framebuffer
Use FBInk’s rotation quirks to set the alignment of the display and input
Add support to the build actions for compiling FBInk and linking against it

Installation

To install it, copy KoboRoot.tgz to KOBOReader/.kobo after mounting the device as USB storage, then eject the drive.

It will install remux + a few applications (but not simon tatham’s puzzles yet). After rebooting, you will be able to swipe up the side of the Kobo to bring up remux. To disable remux, edit KOBOReader/.adds/rmkit/ and remove the file “enable_remux”.

News update: January 2024

Mon, 01 Jan 2024 00:00:00 -0800

community happening

rmkit has adopted the puzzles repo from mrichards42
Eeems has been working on some awesome display server ideas
rmAnki is an app for anki flash cards
regenda is an app for displaying read only agendas
mb has been working on an alternative to ddvk-hacks for xochitl 3.X

rmkit happenings

General improvements:

Add support for scene stacks: this allows dropdowns within dialogs and more
Fix image handling (yet again) to properly use 4 channels
Add an API to remux for common actions (thanks Eeems!)
Fix sporadic diacritic crashes for non ASCII characters

Kobo support stuff:

Add support for Kobo Elipsa 2E stylus
Add touch support to harmony when stylus is not available

News update: August 2023

Sat, 12 Aug 2023 00:00:00 -0700

Community Happening

sill is an editor and terminal emulator that supports handwriting
folly is an interactive fiction interpreter
an anki trainer

rmkit happening

add Tables to iago
Many fixes from Eeems: build fixes, nao fixes and more
Add swipe-up and swipe-down to genie
rpncalc upgrades

E-ink is so Retropunk

Tue, 01 Aug 2023 00:00:00 -0700

I’ve long been struggling to describe why e-ink is so much fun for me, but I think I’ve finally realized what it is: e-ink is just so so so retropunk.

An e-ink device is a hacker’s dream - or at least, this hacker’s dream. They are a return to the magical feeling of computers of the 80s and 90s. It’s a world where ~~Microsoft~~ Windows and ~~Apple~~ Mac OS X never existed and we don’t have to suffer with abstractions on top of abstractions. It’s DOS for the 2020s. It’s graphing calculators for grown-ups.

Features

The e-ink devices I favor are low powered ARM devices running linux without a display server or gigabytes of RAM. Let’s break down why that’s so awesome:

e-ink: The display is visible in the light of day :-D
Low Powered: They can last for weeks on a single charge
ARM is a simple architecture with a low instruction count and even lower cost
Linux: as much as I like it, Android is a complicated mess
Apps are simple: they talk to the kernel to read input and draw directly to the framebuffer
Low RAM and slow CPUs: There’s no room to build complicated stacks of software, which means no window managers, no browsers and definitely no electron apps

As similar as they are to the computers of the early 90s, they are different in some tangible ways:

The resolution is much higher than an old computer - The PPI is between 200 - 300
All devices supports touch events, some even support a pen stylus
They are super portable, weighing between 200 - 400 grams, with displays ranging from 6” to 10”

The Software

Since the devices are niche, the software ecosystem is way more homebrew (as in the Homebrew Computing Club): people write and share their apps and the community is tight knit. The people who use eink devices are enthusiasts: they’ve given up the joys of color displays to work on these under-powered devices that are devoid of app stores, tracking pixels, pay to play features and constant distractions. There’s no email on these devices, there’s no chat or social networks, there’s only simple applications.

Don’t be fooled though: the device constraints lead to interesting and quirky software. In the reMarkable eco-system, there’s dozens of applications, including:

multi-tasking application launchers like oxide and remux
terminal emulators
an interactive fiction interpreter
an experimental editor & shell that you can write into
a procedural drawing app with layers
alternative ebook readers like koreader and plato
a simple app script for building applications that follows the unix philosphy
a chess board
even a port of doom
and so much more - like much, much, more

For the Kobo, that’s also some interesting things going on - with NiLuJE, pgaskin and others hacking away:

InkBox - an alternative OS with many built in applications
KoReader - koreader is supported on almost all eink platforms, no surprise it works on Kobo
NickelMenu - an augment to the Kobo’s UI system that adds many features

Since eink is currently niche, it also means green fields: there are lots of opportunities to write applications that fills out the ecosystem. In short, a hacker’s playground.

How to get started

Convinced that you should hack on eink devices? Grab a reMarkable or Kobo and get hacking ;) Join the reMarkable discord server or browse the Mobile Read Kobo Forums.

remarkable

The toltec repository is a good place to get started

one of the maintainers, Eeems, has written a great tutorial. Another good start is the awesome reMarkable repo.

kobo

The main piece of software to get started hacking is KoboStuff from NiLuJE which includes a tarball for getting SSH up and running instead of having to use telnet.

Turn devmodeon to be able to telnet in,then turn on SSH. It looks complex, but it isn’t so bad

Caveats

These devices are not all rosy fun times, though:

the rM2 uses a proprietary display driver (SWTCON) that’s hosted within their UI (Xochitl). In order for applications to work on the rM2, a shim was built that lets us repurpose the driver within Xochitl. Unfortunately, the shim needs to be updated for every release to give it the correct binary addresses to hook. There’s an alternative display driver that is in development.
the rM1 is preferable to the rM2 for that reason, but the rM1 battery life is not as good! It seems they didn’t connect the peripherals (wacom display) to regulators, so the device only gets a few days of idle battery life.
the Kobo does not have strong package management: to install software, typically a KoboRoot.tgz is provided and that gets unpacked after the next reboot. To uninstall software: you better hope the dev supplied instructions or an uninstall script ;)

Why write a post now?

Several years ago, I started hacking on e-ink devices and had an enormous amount of fun writing applications and seeing what others have built. Unfortunately, I’ve had several false starts with writing about e-ink: whether it was about what I’ve actually done, or the lessons learned along the way or even a set of things to consider when developing e-ink apps, the posts would lay half finished because they just never felt compelling - my enthusiasm for e-ink just wasn’t coming through.

Instead of trying to push any of those posts to completion, I’ve decided to try to articulate what is so cool about e-ink to me.

Appendix: Hacker unfriendly devices

Kindles

The Kindle requires a jailbreak to use and is running a modified version of Android OS (Kindle Fire). Newer FW versions may be JB resistant. The Kindle Scribe is still secured, though. For this reason, I don’t particularly recommend the Kindle devices.

Onyx

In every eink thread that comes up, the Onyx is brought up as not following the GPL: they use a modified linux kernel and haven’t published the source for it.

Pine

The Pine Note is cool and open, but its software is still in development. Use only if you are willing to take on an early product aimed at early adopters and developers - In other words, maybe the Pine Note is too hacker friendly.

Appendix: Responses to HN Comments

Can you brick your RM2 by playing with this? I’m interested, but the device was a bit pricey for potentially destructive fooling around.

sort of - you can soft brick it and cause the screen to not display something, but you will still have SSH and can undo that. If you lose SSH, you can always recover but it’s more work. I understand this is scary, but I’ve never bricked myself because I have my SSH keys installed.

when you’re spending multiple hundreds of dollars for a new part, I don’t consider that the hacker realm.

you can find rM1 for under $200 on ebay, a kobo clara is under $100, but regardless: hacking is orthogonal to price. i understand the concern, though

Retro? Sure. Punk? Not when the patents are tightly held by a greedy patent troll who seems to do everything in their power to stop hobbyists and hackers

a lot of comments are talking about what retro and punk mean and whether they are applicable. i like the back and forth going on. the thought i had in mind when i called it retropunk is: what if there was an alternative path that was taken for computing from the 80s to today?

News update: October 2022

Sat, 15 Oct 2022 00:00:00 -0700

Community Happening

xochitl releases yet more updates, rm2fb is catching up
carta GUI library is released which is a wrapper around simple app script for python

rmkit happening

add a new binary eclear for clearing the screen
add a new widget to simple, the range widget

News update: May 2022

Fri, 06 May 2022 00:00:00 -0700

Community Happening

New xochitl update released, toltec support available in stable and testing

rmkit happening

harmony now supports layers! thanks for all the support, hirako! see this reddit post for examples. this update is available in toltec!
better memory usage for harmony
better memory usage for remux

News update: February 2022

Sun, 20 Feb 2022 00:00:00 -0800

Community Happening

New xochitl update released (2.12.5.257), toltec support now available in testing
New app spotted: rmgraph
Write up of harmony sketching spotted. Also see reddit post

rmkit happening

New app: dumbskull which has donsol and scoundrel games
New app: rpncalc added to toltec
remux: added compression to saved framebuffers, saving 5+MB of RAM for each app
minesweeper: fix sporadic crashes
genie: add palm recognition to prevent accidental palm taps

rmkit comes to kobo

Tue, 01 Feb 2022 00:00:00 -0800

My new year’s project for 2022 was to add Kobo support to rmkit. I’m now glad to announce that it all works! If you have a kobo, you are able to use the KoboRoot.tgz on the build server to easily install remux and other applications.

See remux and other apps in action on the Libra H20

A reddit post was made, as well.

Supported platforms

Currently, the Libra H20 and Clara are supported, but if you have any requests, please get in touch and I’ll look into enabling more devices. Individual devices have to be enabled so as to not cause issues, so seriously: please get in touch!

What it took to get working

In order to get Kobo support working, a few things had to happen:

support rotation in remux and other apps. remux automatically kills itself if the screen rotates and starts again
embed the font into the actual binaries since Kobo fonts seem to work a bit weirdly
support dynamic bpp for different applications, like KOReader
update all applications to work with kobo dimensions
add a KoboRoot.tgz step to the build system to make it easy to install packages

Installation

To install it, copy KoboRoot.tgz to KOBOReader/.kobo after mounting the device as USB storage, then eject the drive.

News update: January 2022

Sat, 08 Jan 2022 00:00:00 -0800

Community Happening

Oxide 2.3 released!
KOReader 2022.01 available in Toltec

rmkit happening

minesweeper bugfixes and new layout
wordle clone added to remarkable
rmkit applications now work on the kobo libra h2o and the kobo clara HD.
- See README.md for more details on how to install
- Refactored rmkit framebuffer interactions and touch handling to be more generic
- Modify apps to work at lower resolutions
- Remux supports per app BPP : each app can have its own BPP, including Nickel

howto: e-ink dev notes

Sat, 08 Jan 2022 00:00:00 -0800

How to draw to the screen?

e-ink devices tend to be low power and run without an X server. The way they draw to the screen is by using the framebuffer. The framebuffer is a piece of memory that directly represents what is on screen and can usually be found at /dev/fb0. Originally, the framebuffer represented the memory of what was being shown on the display, but these days the framebuffer is typically emulated: when you write to a framebuffer device, the kernel driver will copy that over to the display.

Either way, the framebuffer is a piece of memory that represents the pixels on screen. The pixels can be stored as 8 bit grayscale (Y8), 16 bit RGB (rgb565) or 32 bit RGBA.

The framebuffer details are usually obtained with a line like: ioctl(self.fd, FBIOGET_VSCREENINFO, &vinfo)), which will obtain the framebuffer’s width, height and stride, as well as the bit depth and rotation of the framebuffer.

The stride is the width of each line in pixels and may not line up with the actual width. For example, the remarkable width is 1404, but the stride is 1408. If you want to draw a straight line, you need to draw a pixel, then advance forward 1408 pixels before drawing the next one. If you advanced 1404 pixels the line will come out distorted.

On e-ink devices, writing to /dev/fb0 isn’t enough to update the display, though. After placing new data in the framebuffer, you need to signal the display to update using an ioctl that specifies the region to update and the waveform to use when updating that region. Each framebuffer driver will have a different call to use. A common driver is mxcfb and you need to include mxcfb.h which contains the relevant ioctls and structs associated with them.

A typical problem people run into when trying to update the screen is that their pixels don’t show up even after specifying the ioctl. This is likely because the wrong waveform was used.

What are waveforms?

Waveforms are how e-ink displays update what is displayed. They are typically proprietary (secret sauce) and contain the series of pulses to send to the screen in order to set a pixel to a specific value. They come in the form of LUTS (lookup tables), that tell you for a given temperature and a before and after value, what pulses you need to send. The fastest waveforms may contain 10 frames, while more detailed waveforms can have as many as 24 or more. There are 3 operations supported in the waveform: darken the pixel, lighten the pixel or do nothing.

The faster waveforms support less colors: DU (direct update) can only set pixels to black and white but updates extremely quickly. GC4 supports four colors and GC16 supports 16 colors. Waveforms also have algorithms for reducing “ghosting” - when a pixel stays dark even though it’s been changed to white.

See this link for more details on the framebuffer

How do I handle input?

If you are using QT (like many e-ink applications do), then you don’t have to worry too much because QT usually handles the input events for you. If you are not using QT, then you will likely use the linux input API. The API is standard across linux and consists of opening /dev/input/eventX (where X is a number) and reading events from it. The main inputs supported on e-ink devices tend to be touch (or multi-touch), buttons and a stylus. The input API generally sends back information describing the input as a series of events followed by a SYN event. Each datum consists of the event type, the event code and the event value.

As an example, the a touch display may send the following when you touch the display:

EV_KEY, ToolFinger, 1
EV_ABS, ABS_X, 300
EV_ABS, ABS_Y, 500
EV_SYN

When you lift your finger, the following may be sent:

EV_KEY, ToolFinger, 0
EV_SYN

Each input device will have different codes: you can find more info about them here. Luckily, you don’t have to handle them yourself, you can use a library like libinput to take care of the heavy lifting

How to compile for ARM processors

Typically, you want to compile your applications on a computer, but your machine is likely using an x86 compiler, like GCC. If you compile a program with it, it will not run on the e-ink device.

To compile for e-ink, you have to cross compiler - compile on one architecture for another one. Some tablets release their toolkits that include a compiler, like the remarkable, but you don’t need to use them: you can install a cross compiler on your own. The typical one to use is arm-linux-gnueabihf-gcc. The chances are that your application will be dynamically linked against glibc and other common libraries - but these libraries will likely not be available on the tablet. You can either install the libraries as .so files on the tablet after cross compiling them or you can compile your binary with the -static flag. You may also need to use the -static-libstd++ and -static-libgcc flags.

It’s a good idea to strip the binary after you’ve built it to reduce its size, otherwise you may end up with a binary that is several megabytes.

What about rotation?

The framebuffer typically supports rotations. You can rotate the framebuffer by 0, 90, 180 or 270 degrees. Once the framebuffer is rotated, you also need to rotate your input events to make sure they are consistent with the UI you are showing.

On the kobo, when the device is rotated, it will emit MSC_RAW input events on the button device. When those events are received, the running application will send an instruction to the framebuffer to rotate itself and then will make a note to translate the input events accordingly.