README
¶
Inkshelf
An e-reader app for PocketBook e-ink readers (InkPad 3), written in pure Go, that reads EPUB books, comics and manga (CBZ) and recipes from your self-hosted Komga, Calibre-Web and Mealie servers.
This is a fun project: I wrote it to discover how EPUBs are handled (XHTML, CSS, line breaking, pagination, fonts…) and how a PocketBook works under the hood (framebuffer, e-ink refresh, firmware). I also plan to port it to Kobo and Kindle readers, just to understand how they work.
I also wanted to see whether a PocketBook app could do without the official SDK: no cgo, no libinkview, just Go drawing into the framebuffer and talking to the firmware itself. It can.
It was written with Claude Code, but I still tried to keep the code intelligible and easy to read: the goal is to learn, not to offer a production app. If you want a solid, mature reader, use KOReader.
Screenshots from the emulator, with fake servers; the book being read is Project Gutenberg's Alice's Adventures in Wonderland.
Using it
You're welcome to use it. Download the zip of the
latest release, connect the reader
over USB, unzip it at the root of the reader, then write applications/inkshelf/config.json
with your servers. How to configure it, or build it from source, is in
docs/reference/usage.md; how it works inside starts at
docs/reference/architecture.md.
To learn how it works from scratch, with animations of e-ink refreshes, dithering, EPUB
layout and the app's threads, read the documentation site
(or run make docs and open http://localhost:3000/inkshelf/): the
learning chapters go from the big picture down to the algorithms.
Working in a container
.devcontainer holds everything make verify, make icons and make docs need,
and Claude Code: open the folder in VS Code and choose Reopen in Container. Its firewall lets
through only Anthropic's API, GitHub, the Go proxy and npm. To run make emu against your own
servers, list their hosts, space-separated, in INKSHELF_ALLOWED_DOMAINS on the host before you
open it. make deploy needs the reader mounted over USB, so it runs on the host.
Maintenance
I don't maintain it on a regular basis, only when I feel like it. Pull requests are welcome, and so are forks.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
emulator
command
Command emulator runs the app on the host, on an emulated PocketBook: the real event loop and screens, with the e-ink panel kept in memory.
|
Command emulator runs the app on the host, on an emulated PocketBook: the real event loop and screens, with the e-ink panel kept in memory. |
|
inkshelf
command
Command inkshelf reads the books of Komga and Calibre-Web servers and the recipes of Mealie servers on PocketBook e-readers.
|
Command inkshelf reads the books of Komga and Calibre-Web servers and the recipes of Mealie servers on PocketBook e-readers. |
|
internal
|
|
|
app
Package app is Inkshelf's user interface: it shows one screen at a time, turns the reader's buttons and touches into what the screen shown does, and starts the work done in the background.
|
Package app is Inkshelf's user interface: it shows one screen at a time, turns the reader's buttons and touches into what the screen shown does, and starts the work done in the background. |
|
app/catalog
Package catalog keeps the lists of series and books that the app shows: what the server has, what the reader downloaded, and how far each one is read.
|
Package catalog keeps the lists of series and books that the app shows: what the server has, what the reader downloaded, and how far each one is read. |
|
app/covers
Package covers shows the covers of series and books: the small ones in the lists, and one on the whole screen.
|
Package covers shows the covers of series and books: the small ones in the lists, and one on the whole screen. |
|
app/downloadqueue
Package downloadqueue downloads books to the reader, one at a time, in the order they were asked for.
|
Package downloadqueue downloads books to the reader, one at a time, in the order they were asked for. |
|
app/openbook
Package openbook is the book open in the reader: opening it where it was left, turning its pages, preloading the pages around the one shown, and closing it.
|
Package openbook is the book open in the reader: opening it where it was left, turning its pages, preloading the pages around the one shown, and closing it. |
|
app/screens/booklist
Package booklist is the screen of the books of a series.
|
Package booklist is the screen of the books of a series. |
|
app/screens/contents
Package contents is the screen of a Reflowable book's navigation, opened from the reader's toolbar: its table of contents, and its printed pages and landmarks when the EPUB has them, each on a tab.
|
Package contents is the screen of a Reflowable book's navigation, opened from the reader's toolbar: its table of contents, and its printed pages and landmarks when the EPUB has them, each on a tab. |
|
app/screens/coverview
Package coverview is the screen that shows the cover of a series or a book on the whole screen, from a tap on its small cover in a list.
|
Package coverview is the screen that shows the cover of a series or a book on the whole screen, from a tap on its small cover in a list. |
|
app/screens/list
Package list draws what the screens of lists share: a header with the Back button, a title and the reader's status; a band under it for filters or tabs; a page of rows, each with a cover, a title, a subtitle and a progress bar; and a footer that turns the pages.
|
Package list draws what the screens of lists share: a header with the Back button, a title and the reader's status; a band under it for filters or tabs; a page of rows, each with a cover, a title, a subtitle and a progress bar; and a footer that turns the pages. |
|
app/screens/reader
Package reader holds the screens of the open book: the reader itself, and the question whether to delete a book just finished.
|
Package reader holds the screens of the open book: the reader itself, and the question whether to delete a book just finished. |
|
app/screens/serieslist
Package serieslist is the screen of the series list, the first screen once a server is chosen.
|
Package serieslist is the screen of the series list, the first screen once a server is chosen. |
|
app/screens/startup
Package startup holds the screens shown before the series list: the loading screen, which says what the session is doing or why it stopped, and the server screen, where the reader chooses a server when config.json lists several.
|
Package startup holds the screens shown before the series list: the loading screen, which says what the session is doing or why it stopped, and the server screen, where the reader chooses a server when config.json lists several. |
|
app/session
Package session starts the app's work with a server: it reads config.json, turns the Wi-Fi on, lets the reader choose a server when there are several, opens that server's folder on the reader, and loads the series list, or falls back to the downloaded books when the server cannot be reached.
|
Package session starts the app's work with a server: it reads config.json, turns the Wi-Fi on, lets the reader choose a server when there are several, opens that server's folder on the reader, and loads the series list, or falls back to the downloaded books when the server cannot be reached. |
|
app/state
Package state holds everything the app knows while it runs, and the one lock that guards it.
|
Package state holds everything the app knows while it runs, and the one lock that guards it. |
|
app/widgets
Package widgets holds what every screen of the app draws with: sizes that scale with the screen, the grays, the interface fonts, buttons and panels, text that fits, the logos of the servers, and the targets that make parts of the screen react to touches.
|
Package widgets holds what every screen of the app draws with: sizes that scale with the screen, the grays, the interface fonts, buttons and panels, text that fits, the logos of the servers, and the targets that make parts of the screen react to touches. |
|
device/pocketbook
Package pocketbook runs an app on a PocketBook e-reader (firmware 6.x, made for the InkPad 3) without PocketBook's SDK.
|
Package pocketbook runs an app on a PocketBook e-reader (firmware 6.x, made for the InkPad 3) without PocketBook's SDK. |
|
ebook/comicarchive
Package comicarchive reads the pages of a comic book archive.
|
Package comicarchive reads the pages of a comic book archive. |
|
ebook/epub
Package epub turns the chapters of an EPUB book (versions 2 and 3) into documents that the typesetting packages lay out on the reader's pages.
|
Package epub turns the chapters of an EPUB book (versions 2 and 3) into documents that the typesetting packages lay out on the reader's pages. |
|
ebook/epub/container
Package container opens an EPUB book (versions 2 and 3) and finds what is in it.
|
Package container opens an EPUB book (versions 2 and 3) and finds what is in it. |
|
ebook/epub/epubtest
Package epubtest makes EPUB books for the tests and benchmarks of the packages that read them: package epub and its container, the shelf that downloads them, the reading engine.
|
Package epubtest makes EPUB books for the tests and benchmarks of the packages that read them: package epub and its container, the shelf that downloads them, the reading engine. |
|
ebook/fixedlayout
Package fixedlayout draws the pages of fixed-layout EPUBs (rendition:layout pre-paginated): comics, children's books, magazines, where each spine item is one page designed at a fixed size and meant to be seen whole.
|
Package fixedlayout draws the pages of fixed-layout EPUBs (rendition:layout pre-paginated): comics, children's books, magazines, where each spine item is one page designed at a fixed size and meant to be seen whole. |
|
graphics/fonts
Package fonts measures and draws text in gray, for the app's screens and for book pages.
|
Package fonts measures and draws text in gray, for the app's screens and for book pages. |
|
graphics/pageimage
Package pageimage prepares page images for the e-ink panel, once, when a book is downloaded, so that turning a page on the reader only has to read a file.
|
Package pageimage prepares page images for the e-ink panel, once, when a book is downloaded, so that turning a page on the reader only has to read a file. |
|
naturalorder
Package naturalorder sorts titles as people do: "tome 2" before "tome 10".
|
Package naturalorder sorts titles as people do: "tome 2" before "tome 10". |
|
progress
Package progress keeps the reading progress of the books on the reader and on their server in agreement.
|
Package progress keeps the reading progress of the books on the reader and on their server in agreement. |
|
reading
Package reading is the engine behind the reading of a text book (an EPUB whose text flows to fit the screen): where the reader is in it, turning its pages across chapters, drawing them, following its links and notes, and its table of contents.
|
Package reading is the engine behind the reading of a text book (an EPUB whose text flows to fit the screen): where the reader is in it, turning its pages across chapters, drawing them, following its links and notes, and its table of contents. |
|
servers
Package servers is what the app needs from a server of books, said once for every kind of server.
|
Package servers is what the app needs from a server of books, said once for every kind of server. |
|
servers/calibreweb
Package calibreweb reads a Calibre-Web server, a server of ebooks, through its OPDS catalog.
|
Package calibreweb reads a Calibre-Web server, a server of ebooks, through its OPDS catalog. |
|
servers/calibreweb/fakecalibreweb
Package fakecalibreweb is a Calibre-Web server with a fixed library of generated EPUBs and CBZs, for running the app off the reader (the emulator) without a real server.
|
Package fakecalibreweb is a Calibre-Web server with a fixed library of generated EPUBs and CBZs, for running the app off the reader (the emulator) without a real server. |
|
servers/httpclient
Package httpclient holds what the clients of every kind of server share: the HTTP client the app sends its requests through, and the handling of their responses.
|
Package httpclient holds what the clients of every kind of server share: the HTTP client the app sends its requests through, and the handling of their responses. |
|
servers/komga
Package komga reads a Komga server, a server of comics and manga, through its REST API.
|
Package komga reads a Komga server, a server of comics and manga, through its REST API. |
|
servers/komga/fakekomga
Package fakekomga is a Komga server with generated series, books and pages, for running the app off the reader (the emulator) without a real server.
|
Package fakekomga is a Komga server with generated series, books and pages, for running the app off the reader (the emulator) without a real server. |
|
servers/mealie
Package mealie reads a Mealie server, a server of cooking recipes, through its REST API, and makes it look like a server of books: one series per category (and one for the recipes in none), one book per recipe.
|
Package mealie reads a Mealie server, a server of cooking recipes, through its REST API, and makes it look like a server of books: one series per category (and one for the recipes in none), one book per recipe. |
|
servers/mealie/fakemealie
Package fakemealie is a Mealie server with fixed recipes and generated photos, for running the app off the reader (the emulator) without a real server.
|
Package fakemealie is a Mealie server with fixed recipes and generated photos, for running the app off the reader (the emulator) without a real server. |
|
servers/mealie/recipepages
Package recipepages lays a recipe out into pages and draws them as images, for a server whose books are recipes (Mealie).
|
Package recipepages lays a recipe out into pages and draws them as images, for a server whose books are recipes (Mealie). |
|
servers/registry
Package registry opens the Server of each kind of server.
|
Package registry opens the Server of each kind of server. |
|
servers/servertest
Package servertest is a servers.Server in memory, for the tests of the packages that use one.
|
Package servertest is a servers.Server in memory, for the tests of the packages that use one. |
|
shelf
Package shelf keeps the books downloaded on the reader: it downloads them from a servers.Server, prepares them for the e-ink screen once and for all, and remembers how far each has been read.
|
Package shelf keeps the books downloaded on the reader: it downloads them from a servers.Server, prepares them for the e-ink screen once and for all, and remembers how far each has been read. |
|
timing
Package timing finds out where the time goes, in the log and in profiles.
|
Package timing finds out where the time goes, in the log and in profiles. |
|
typesetting/document
Package document is the model of a book's text: what package epub makes of a chapter's XHTML and CSS, and what package layout lays out into pages.
|
Package document is the model of a book's text: what package epub makes of a chapter's XHTML and CSS, and what package layout lays out into pages. |
|
typesetting/hyphen
Package hyphen finds where a word may be hyphenated, with Frank Liang's algorithm, the one TeX uses, and the hyph-utf8 patterns of a few languages, embedded in the program (patterns/, with their licences in patterns/LICENSES).
|
Package hyphen finds where a word may be hyphenated, with Frank Liang's algorithm, the one TeX uses, and the hyph-utf8 patterns of a few languages, embedded in the program (patterns/, with their licences in patterns/LICENSES). |
|
typesetting/layout
Package layout typesets a document (package document) into pages for the reader's screen, and draws them.
|
Package layout typesets a document (package document) into pages for the reader's screen, and draws them. |
|
web/css
Package css reads the stylesheets of EPUBs and works out which declarations apply to each element.
|
Package css reads the stylesheets of EPUBs and works out which declarations apply to each element. |
|
web/mathml
Package mathml lays out and draws the formulas that books write in presentation MathML.
|
Package mathml lays out and draws the formulas that books write in presentation MathML. |
|
web/svgimage
Package svgimage sizes and draws SVG images.
|
Package svgimage sizes and draws SVG images. |
|
web/uri
Package uri reads the URIs found in a book's markup.
|
Package uri reads the URIs found in a book's markup. |
|
web/webfont
Package webfont turns the fonts a book embeds into TrueType or OpenType data, the formats that golang.org/x/image/font/sfnt reads.
|
Package webfont turns the fonts a book embeds into TrueType or OpenType data, the formats that golang.org/x/image/font/sfnt reads. |
|
web/webimage
Package webimage prepares the images of a book's markup for the panel: raster images (JPEG, PNG, GIF, BMP, WebP, JPEG XL) and SVGs, read from the book's files or from data: URIs.
|
Package webimage prepares the images of a book's markup for the panel: raster images (JPEG, PNG, GIF, BMP, WebP, JPEG XL) and SVGs, read from the book's files or from data: URIs. |
Click to show internal directories.
Click to hide internal directories.