FBInk: printing text and images to an e-ink framebuffer

The gap that a Kobo developer hits on day one

FBInk is a small tool and library for printing text and images to an e-ink Linux framebuffer, and the README explains the problem it solves in the voice of somebody who has hit it.

It is intended to fill the void felt by Kobo developers and tinkerers when they realize they do not have a built-in way to print stuff on the device's screen. And it is especially cruel when moving to a Kobo, after being used to the ubiquity of eips on Kindle.

That last sentence is the context for everything else. On a Kindle, eips was a familiar command you could call from a script to push a message onto the screen. On a Kobo there is nothing equivalent, so a person writing a script that wants to display a result, a status line or a notification has to deal with the framebuffer and the display controller directly.

FBInk takes that work on. It prints messages or images on the screen, handling the low-level tinkering with both the Linux framebuffer interface and the i.MX EPDC, as well as the MTK one on Kindle and the sunxi one on Kobo.

The tested devices are Kobo, Kindle, BQ Cervantes, reMarkable and PocketBook, and the README says that porting it to other Linux i.MX eInk devices should be trivial, with the aside that even Sipix support should not be too hard. The supporting evidence for that claim is the linked pull request 64, which the README describes as proving that we can even bend sunxi APIs to our will, if you don't care too much about losing your sanity in the process.

The licence is GPLv3+, the language is C, and the repository topics cover c, eink, framebuffer, kindle, kobo, linux, remarkable and cervantes. The homepage is a MobileRead forum thread, which says something about where this project's users are.

Software you already use is already using it

The most convincing evidence for a tool like this is not the feature list, it is the list of things that already depend on it.

KFMon uses FBInk to provide visual feedback. kobo-rclone uses it for screen scraping, which is the mirror image of the same capability: reading what is on the screen rather than writing to it. And KOReader uses it to make the OTA update process more user-friendly, which means that during a firmware update on a Kobo, a message appears on the e-ink screen telling the user what is happening.

That last one is the clearest statement of the value. Without a way to draw on the screen, a device update is silent, and the user cannot tell whether it is progressing or hung.

There are also the bindings in other languages, which often include a few examples, and the README points at a GitHub search for code mentioning fbink as the way to find them. Three are named: a DAMAGE-handling shim for X11, a Qt5 QPA plugin, and InkVT, a terminal emulator.

The X11 shim and the Qt platform plugin are worth thinking about, because they show the shape of the integration from the other side. A Qt platform plugin for Kobo means a Qt application can treat the device's e-ink screen as a normal QPA surface, and the X11 shim suggests the same trick applied to a desktop X server with an e-ink display attached. Neither of those would be possible without a library that already knows how to talk to the controller.

So the practical position is that FBInk is infrastructure that other projects have built on, and the README's invitation to the author for help with the library API is an offer of help rather than an admission of gaps.

A CLI and a library, and the licence point to read first

FBInk is both a command line tool and a library, and they are built on the same public API.

A CLI utility is available, built around the same public API that can be used via a shared or static library for C projects, or via FFI in other languages. The README then adds the warning in brackets: beware, though, it is licensed under the GPLv3+, not the LGPL.

That parenthetical matters more than it looks. The GPL is the kind of licence that reaches a linked binary, so if you ship an application that links FBInk, the terms of the GPL apply to your application too. The LGPL would not do that. For a hobby project on your own device this is irrelevant, and for a commercial product it is the first thing to check, which is why the README puts it right next to the library description rather than in a licence section at the bottom.

For the command line utility the documentation is in CLI.md, or you can run fbink --help for details:

fbink --help

For the library, the entry point is the public header, fbink.h, and the README invites you to contact the author if things appear unclear. That last sentence tells you the size of the project: it is one maintainer, and the library API is something you are expected to read rather than to be guided through.

The source layout reflects how a small library with a large platform surface is organised. There is a file per concern rather than a directory per concern: fbink.c is the core, fbink_block.c handles block rendering, fbink_cmd.c the command handling, fbink_device_id.c the device identification, fbink_input_scan.c and fbink_button_scan.c the input side, fbink_rota_quirks.c the rotation special cases, fbink_string_utils.h and fbink_types.h the shared helpers, and fbink_rgb565.h a pixel format definition. Then there is the font family, with a module per device model: cozette, fatty, leggie, microknight, orp, scientifica, spleen, terminus, tewi, topaz, unifont, unscii and vga.

Rotation is left alone on purpose

One behaviour of the tool is documented as a deliberate decision rather than a limitation, and it is worth understanding before you spend an afternoon on it.

FBInk generally makes no attempt at handling software rotation, because that currently appears to be the right thing to do with both current Kobo firmware versions and on Kindle. Your mileage may vary on older firmware, or if something else is fudging with the fb rotation, or if your application is implementing rotation in software, for instance a rotated viewport.

The reasoning is worth reconstructing. On these devices the operating system owns the panel orientation and the firmware applies the rotation when it presents its own interface, and Nickel on a Kobo rotates the screen to match the device orientation. If FBInk also rotated its drawing, its output would be turned twice relative to what the user sees. So the library draws in the natural orientation and lets the firmware do the rotating.

Hardware rotation has a small number of specific exceptions, and they are listed. On Kobo devices running in 16bpp mode and appearing to be in landscape mode, since that seems to be their native state, the tool attempts to compensate, as it can legitimately be used before Nickel itself corrects this. And on devices with an accelerometer, like the Forma and Libra, Nickel itself will handle the hardware rotation.

The Forma and Libra case is the interesting one, because it means the correct behaviour of the library depends on the model of the device, and the detection is in fbink_rota_quirks.c. A device with an accelerometer tells the firmware what orientation it is in, so the firmware rotates the panel; a device without one has a fixed panel, and the library has to compensate for the way that device presents itself.

So if you are porting to a new device, the rotation behaviour is one of the two things, along with the controller, that you will have to get right yourself.

Fonts and images, and the framebuffer fallback

The rendering side has two axes: what font you draw with and what you draw.

By default, text rendering relies on bundled fixed cell bitmap fonts, with a small sampling linked in the README. But thanks to contributions from @shermp, pull request 20, you can also rely on full-fledged TrueType and OpenType font rendering. The screenshots in the README show both: the fixed cell text on a Kobo H2O, then a later version with the TrueType fonts, and a progress bar example along the way.

The bitmap fonts are per device, which is the point of having thirteen modules for them. A Kobo with a particular screen and panel expects a particular cell size and baseline, and shipping one universal font would either look wrong or cost more memory than a device has. The module names correspond to the models: cozette, leggie, microknight, orp, scientifica, terminus, tewi and topaz are Kobo families, unifont and unscii are general purpose, and vga is a plain PC font.

Images are supported in most common formats, JPEG, PNG, TGA, BMP, GIF and PNM, as well as raw packed pixels in the most relevant pixel formats, Gray8 and RGB32, both with and without alpha. The README's screenshots show the transparency working on old hardware, which is the harder case.

Then there is the fallback that widens the tool's reach: it also happens to work perfectly fine on any kind of Linux framebuffer device, and supports a wide range of bitdepths, 4bpp, 8bpp, 16bpp, 24bpp and 32bpp, so you could use this to draw on your EFI framebuffer, for instance.

That is a genuinely useful property. The same code that draws on a Kobo's e-ink panel will draw on a framebuffer on a normal Linux system, which is exactly what makes the visualizer and the test tooling possible, and it is why make linux is a build target.

Building: cross toolchains, LTO and the make targets

The build section is written for people who know what a cross-compiler is, which fits the stated audience.

Unless you are just trying to take it for a spin on a native pure Linux system, with make linux, you will need a cross-compiler targeting your target device. The Makefile is tailored to automatically detect the author's own cross-compilation toolchain setups, and the README says the author heartily recommends using that instead of relying on generic cross-compilation toolchains which may not exactly target the right kernel and libc duo. Using the koxtoolchain frontend should make building one of these a fairly painless process.

The reasoning about generic toolchains is the interesting part. A device's userspace is not glibc, and building against the wrong libc produces a binary that fails in ways that look like bugs in the code rather than a mismatch in the environment. The author's own toolchain is configured for the exact kernel and libc pair of the devices, and the recommended alternative, koxtoolchain, is the one KOReader uses.

If you are using your own toolchain, the requirements are C11 support, GCC 4.9 or newer or Clang 3.0 or newer, and the README strongly recommends building with LTO enabled provided the compiler is not too old.

The make targets are then a matter of choosing a shape. The default target, plain make, yields a static Kobo build, while make kobo yields a stripped shared build and additionally packages everything the Kobo way, which is the package found in the Kobo thread. There are convenience targets for the usual build types, among them make static for a static build. The Makefile picks up CROSS_TC or CROSS_COMPILE from the environment and derives the compiler, strip, ar and ranlib names from it, including the gcc-ar and gcc-ranlib variants, and it separates the Release and Debug output directories with the usual -O2 versus -Og flags.

The C sources are formatted with a .clang-format configuration and the project uses CREDITS and a .gitmodules file, so the bundled dependencies are pinned as submodules.

Editorial conclusion

FBInk suits a developer who needs to show something on an e-ink device's own screen, whether that is a status message from a background task, a progress bar, or a rendered image, and who is prepared to cross-compile for the device or to take a prebuilt binary from the forum thread. It does not suit you if you need a general purpose graphics library, since it targets e-ink controllers and a Linux framebuffer rather than a display in general, and it does not suit a commercial product without reading the licence, because the GPLv3+ terms reach the binaries and any library you link it into. Check three things before you rely on it: which controller your device uses, since the i.MX EPDC, the MTK one on Kindle and the sunxi one on Kobo each need their own path, whether you need software rotation, because the project makes no attempt to handle it, and which of the many font modules matches the device, since the fixed cell fonts are per device model. The last push to the repository was on 2026-08-06 and the newest tagged release is v1.25.0 from 2022-12-05.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. NiLuJe/FBInk on GitHub
3. Project website
4. README
5. Releases