kindle-utils

README

kindle-utils

A bunch of helper functions to build dash apps like Scopae for jailbroken Kindle and some reusable go building blocks: reading device state over LIPC, drawing text with the stock eips tool, formatting localized dates, and rendering dashboard-style graphics with fogleman/gg for e-ink output.

Requirements

• Go 1.25 or newer.

• A jailbroken Kindle. The kindlesystem and eips packages call into the device's own lipc-get-prop / lipc-set-prop / eips binaries and read /dev/fb0 directly. Both only build and run for GOOS=linux:

  GOOS=linux GOARCH=arm go build ./...
  

  The locale, render, and render/assethelper packages have no Kindle-specific dependencies and build on any platform.

Installation

go get github.com/lennardollesch/kindle-utils

Packages

eips

Writes aligned, word-wrapped text to the e-ink screen through the stock eips tool. The character grid is auto-detected once per process (via eips' own range diagnostic) and cached, so it adapts to different Kindle models without hardcoded dimensions.

import "github.com/lennardollesch/kindle-utils/eips"

eips.Clear()
eips.DrawText("Hello, Kindle!", eips.AlignCenter, 0.5)
eips.DrawBoxedText("Boxed and bottom-aligned", eips.AlignLeft, 1.0, 1)

kindlesystem

Reads and writes Kindle system state via LIPC (Wi-Fi, battery), reads the framebuffer's display dimensions, and reads the active locale.

import "github.com/lennardollesch/kindle-utils/kindlesystem"

if kindlesystem.PrepareWiFiConnection(30) {
    defer kindlesystem.RevertWiFiConnection()
    // ... do networked work ...
}

level, ok := kindlesystem.BatteryLevel()
dims, err := kindlesystem.GetDisplayDimensions()

locale

Formats dates, weekdays, and month names for a Kindle-style locale string (e.g. "de_DE.UTF-8"), backed by goodsign/monday.

import "github.com/lennardollesch/kindle-utils/locale"

locale.FormatWeekday(time.Now(), "de_DE.UTF-8")  // "Donnerstag"
locale.FormatDayMonth(time.Now(), "de_DE.UTF-8") // "09.07"

render, render/assethelper

render embeds the library's own SVG icons (battery levels, Wi-Fi state) as an fs.FS. assethelper rasterises any SVG - from disk or from an fs.FS - to a cached PNG at a given size:

import "github.com/lennardollesch/kindle-utils/render/assethelper"

pngPath := assethelper.EnsureAssetPNG("battery_44.svg", 64, 64)

render/gghelper, render/gghelper/widgets

Font loading/measurement and image helpers built on fogleman/gg, centred on gghelper.Canvas: a gg.Context that also remembers the font face installed through SetFont. Because gg exposes no getter for the active face, ink-anchored text would otherwise force callers to carry the face around. Canvas embeds *gg.Context, so every gg method stays available.

canvas := gghelper.NewCanvas(gg.NewContext(screenWidth, screenHeight))

canvas.SetFont(primaryFont, 48)                          // face is remembered
canvas.DrawStringInkAnchored("13.02", 100, 200, 0.5, 0.5) // no face argument
canvas.RenderToJPEG("/mnt/us/dashboard.jpg")

Unlike gg.DrawStringAnchored, which offsets by the font's metric height, DrawStringInkAnchored anchors on the glyphs' real ink bounds: anchorY=0.5 centres the ink on posY, anchorY=1 puts its top edge there.

The Widget interface composes a dashboard out of self-contained, independently laid-out elements. widgets.TopBar is a ready-made Widget that renders an info string, battery icon/level, and Wi-Fi icon:

import (
    "github.com/lennardollesch/kindle-utils/render/gghelper"
    "github.com/lennardollesch/kindle-utils/render/gghelper/widgets"
)

bar := &widgets.TopBar{
    Info:            "Thursday, 9 July",
    FontPrimary:     primaryFont,
    FontSecondary:   secondaryFont,
    ConnectionState: kindlesystem.ConnectionDefault,
    BatteryLevel:    "84%",
    BatteryStatus:   kindlesystem.BatteryFourQuarters,
}
var widget gghelper.Widget = bar
barHeight := widget.PreferredHeight(canvasWidth, canvasHeight)
widget.Render(canvas, 0, 0, canvasWidth, barHeight)

Laying a widget out is a two-step exchange: ask how tall it wants to be inside the canvas, then draw it into the rectangle you give it. The height is a suggestion - pass Render whatever height you want. TopBar sizes itself off the canvas' shorter edge, so the bar stays the same thin strip whether the dashboard is laid out portrait or landscape.

Because every widget measures against the same canvas, a dashboard is a loop:

posY := 0.0
for _, widget := range []gghelper.Widget{topBar, calendar, footer} {
    height := widget.PreferredHeight(canvasWidth, canvasHeight)
    if err := widget.Render(canvas, 0, posY, canvasWidth, height); err != nil {
        return err
    }
    posY += height
}

License

This library is licensed under the GNU Affero General Public License v3.0; see LICENSE. Programs that link it and are made available to users over a network must offer those users the corresponding source.

The bundled SVG icons under render/assets/ and the Go modules linked into any resulting binary carry their own licenses; see NOTICE.md. Note in particular that github.com/golang/freetype, pulled in through fogleman/gg, is used under the FreeType License, which obliges anyone distributing a binary to credit The FreeType Project in its documentation.