Skip to content
SomniusPublic

About

Books and Obsidian vaults on the Xteink X4 Pro. Firmware based on CrossPoint Reader.

Topics

Resources

Stars

5 stars

Watchers

1 watching

Forks

Latest commit

 

History

501 Commits

Folders and files

Repository files navigation

VaultInk logo

VaultInk

Books and Obsidian vaults on the Xteink X4 Pro.

Version MIT licence Xteink X4 Pro ESP32-S3 C++20 PlatformIO Arduino and FreeRTOS Obsidian English and Greek

Install from your browser · Project page and donations · Releases

Download the Android companion app (APK) · Companion guide

VaultInk is firmware for the Xteink X4 Pro e-reader. It keeps everything CrossPoint Reader does for books, and adds a way to carry your Obsidian notes with you. You can read them, search them and follow their links. Later on you'll be able to edit and sync them too.

It's free and open source (my code is MIT; the firmware binaries are GPL-3.0-or-later, see License). It is not affiliated with Obsidian, Xteink or CrossPoint.

Warning

Still early. VaultInk is at 0.77.2. Releases from 0.8.2 on have been tested on a real X4 Pro by one tester (kos25k, UC8279 screen); the bugs he found are fixed and listed in the release notes. Much of the newest work has been checked on his device up to 0.66.0 (the status bar page number, Hide Status Bar, search, the Library and the battery page among them). Some of it has only run in the simulator so far: MOBI and AZW books, Dice, VaultEUC and the Bluetooth keyboard. Back up your SD card. Most screenshots below come from the simulator; each section says which. From 0.75.0 I can also check things on my own X4 Pro over USB; each release note says what was checked there.

At a glance

Home screen: Books, Vaults, Favourites, Search, Browse Files, Gallery, Transfer & Remotes and Settings (a simulator screenshot) Library with the Recent, up-percent and down-percent bar and the percent read next to each author An Obsidian note with links, a callout, tasks and a table Search in Book results that fill the row, with the gear at the right of the header

Home, the Library sorted by how far you have read, an Obsidian note, and Search in Book.

Home, Plugins: Sudoku, Dice and VaultEUC Dice: Vampire V5 with Hunger dice in black and the Willpower reroll button VaultEUC: the live dash of a demo wheel Sudoku

Home → Plugins holds the built-in tools: Sudoku, a dice roller, and VaultEUC for electric unicycles.

Paper contrast: a tile of every page background and a slider Random page: a book opened on a random page with a bar to go back to your place The Library header with the format filter gear The PIN lock screen with the owner's name and phone Search files in Browse Files: hits with their folders Flashlight: S.O.S., brightness, warmth and flash speed Paper contrast with a tile of all fourteen page backgrounds

Page background contrast with a preview, Random page!, the Library's format filter, the lock screen, search in Browse Files, the flashlight and all fourteen page backgrounds.

A MOBI book with Huffman compression open in the reader A MOBI book page with italics, quotes and hyphenation Customise Status Bar with Hide Status Bar, the book page number and the page number when the bar is hidden Advanced Typography: switches for ligatures, kerning, widow and orphan control, keeping headings with text and hanging punctuation

MOBI and AZW books, the status bar options with the book page number, and Advanced Typography.

More screenshots are in the sections below and in docs/.

New in 0.77.1: word gaps and the top swipe

kos25k found two things in 0.77.0. With Space condensing and Optical spacing on, words could glue together (#30): a word gap now never goes under 60% of a space. Letter spacing has five steps now, and on a loose line the letters take the spare room first. And a swipe from the top edge now opens quick settings over an open book menu, with no tap first (#15). I checked both on my X4 Pro with Fira Sans 16 pt; the classic list menu and line balancing are computer tests only.

Word gaps with condensing, optical and minimal on

New in 0.77.0: more than one vault, and LiveSync that finishes

LiveSync now keeps up to four vaults. Each one is a database synced into its own folder under /Vaults, with a name you choose, and Settings > Vaults > LiveSync has Sync all. On my X4 Pro (2026-11-16) a Sync all of two vaults, about 340 and 75 files with pictures, finished in about 2 minutes with nothing skipped, and the free internal memory never went under 90 KB. The first runs did not get that far: one stopped at the third file on a picture, one ran the internal memory down to 104 bytes, one waited minutes on requests with no answer. Those are fixed. A file that still can't be fetched is skipped with a reason and tried again next time. Guide: docs/livesync.md.

Vaults are not books any more. Only the folders in /Vaults are vaults, and nothing under /Vaults shows in the Library, Recent, Favourites or Random page (computer tests only). The Library index is rebuilt once after the update.

kos25k asked (#30) for two more Typography Engine settings: Space after punctuation (Normal, Minimal or None) and Optical spacing. Both are off by default. I tried every mode on my X4 Pro with Fira Sans 16 pt.

Space after punctuation: Minimal What they do: docs/reading-and-files.md.

Also, on a computer only: the profile setup beyond the two-vault sync, and a reader that no longer sleeps right after a long sync, PDF conversion or download.

Known: in the earlier runs some requests got no answer and I did not find out why. The GitHub certificate check is still off in release builds.

New in 0.76.1: PDFs that open, and a menu for the format

Two big PDFs of mine crashed the reader on open ("System Crash"). The crash dump pointed at the PDF text extractor: it ran out of stack on forms inside forms. It now uses about 14 KB of its 24 KB (measured on one run), and far less memory. I converted three PDFs of 24, 58 and 74 MB (the 58 MB one has 2472 pages) from scratch on my X4 Pro and all three opened; the first conversion takes 1.5 to 6 minutes. If memory ever runs low the extractor now stops with a message and removes the half-written text (tested on a computer only).

The book menu of a one-chapter book: only Text and More, no Contents

kos25k also asked (#30) that the reader show only the options a book's format supports. A book with one chapter (every PDF, TXT, note, MOBI, FB2, HTML, RTF, DOC and CHM, and an EPUB with one entry) has no Contents tile now: the menu is Text and More. I saw that on the reader with a PDF and a one-chapter EPUB. Embedded Style is hidden for TXT, notes and DOC, and "Book's style" is not offered for TXT, notes, DOC and PDF text (computer tests only). Settings > Reader and Book menu options still list everything. Which format shows what: docs/reading-and-files.md.

Also: the update check, the firmware download and the font list say why they failed (no date, certificate not accepted, no Wi-Fi, server unreachable), computer tests only. The 34 other languages have the newer texts, machine-written and not yet checked by a native speaker (corrections welcome).

Known: the GitHub certificate check is still off in release builds, and the backup and restore page is not published yet.

New in 0.76.0: the Typography Engine, and two fixes

kos25k asked for typography like KOReader's (#30). I wrote it from the published ideas, with no KOReader code, as one group of settings: Settings > Reader > Typography Engine (Greek: Μηχανή τυπογραφίας) and the last row of a book's Text menu. All of it is off by default, so a book looks the same until you turn something on. I tried every setting on my own X4 Pro, on an English page, a Greek page and a dialogue page; these screenshots are from the reader, except the Gallery and Home ones (simulator).

The Typography Engine screen with its seven settings A book's Text menu with Typography Engine as its last row An English test page, justified, engine off The same page with space condensing at 60% and Small letter spacing

The same page with Hyphenation mode Off: long gaps on loose lines A Greek test page, engine off The same Greek page with space condensing at 60% and Small letter spacing Dialogue lines with Locked space off: the gap after the leading dash stretches The same lines with Locked space on: the gap after the dash keeps its width

The settings: Space condensing (word gaps shrink to 90 down to 50% of a space to fit one more word), Letter spacing on loose lines, Locked space after a quote or dash, Hyphenation mode (patterns, soft hyphens only, off), Letters before and after a hyphen, and Hyphenation language (13 sets, by name). What each does, with the numbers: docs/reading-and-files.md. On my test pages 60% condensing fit one more word on a line, 70 and 80% changed nothing, and 50% is too strong (some gaps nearly vanish).

Two fixes, both checked on my X4 Pro:

Settings with the System row fully drawn at the bottom The Gallery grid with dark pictures that stay visible (a simulator screenshot with my own test pictures)

  • The bottom row of Settings (System) reacts to a tap without scrolling first (it was drawn clipped, with no touch area).
  • Dark pictures in the Gallery are no longer solid black boxes, and the [GFX] Outside range line when the Gallery opens is gone. The thumbnails are made again once; the old ones stay on the card, unused.

Also (computer tests only): the Hyphenation switch agrees in Settings, on the web settings page and in the book. Every book is laid out again the first time you open it.

Known limits: it only works on left-to-right text (right-to-left, mixed-direction, CJK and ruby paragraphs are laid out as before); the new names in the 34 languages other than English and Greek are machine-written (after 0.76.0), see docs/translating.md; the GitHub certificate check is still off in release builds; the backup and restore page is not published yet.

New in 0.75.1: a terminal font, and Transfer & Remotes

A patch on 0.75.0. The screenshots are from the simulator, which has no USB Drive and no SSH, so those two rows are missing in the second picture and there is no picture of the terminal itself.

The home screen with the Transfer & Remotes row where File Transfer was Transfer & Remotes: Join a Network, Calibre Wireless, Create Hotspot and Remote servers

Checked on a real X4 Pro:

  • The SSH terminal connected to a real server from the reader, and it has its own font: fixed-width, 1-bit, made from Terminus and drawn pixel for pixel, so it is crisp. Four sizes (8x16 is the default, 60 columns), with box-drawing and block characters, bold and Greek. Settings → Connectivity → SSH servers → Terminal text size. SFTP has still not been tried from a device. docs/ssh.md
  • File Transfer on Home is now Transfer & Remotes (Greek: Μεταφορά & Διακομιστές). Its screen holds Join a Network, Calibre Wireless, Create Hotspot, USB Drive, Remote servers (WebDAV, FTP, SFTP) and SSH terminal. Settings → Connectivity keeps both server lists as shortcuts.

Not checked on a device: whether the Greek name fits its row. The licences screen now lists the terminal font (Terminus Font 4.49.1, SIL OFL 1.1).

For developers: scripts/devlink.py push-update sends your own developer build to the reader over Wi-Fi (developer builds only, never in a release image; tried on a real X4 Pro). docs/devlink.md

Known bugs and limits: the bottom row of Settings (System) ignores a tap until you scroll the list (fixed in 0.76.0); the Books list still takes about 1.75 s to show; I haven't judged how readable the smallest terminal size (6x12) is on the panel; the other 34 languages have the new Home name and rows after 0.76.0, machine-written (see docs/translating.md).

New in 0.75.0: scroll mode, SSH, and the first checks on a real X4 Pro

This is the first release where I could check part of the work on a real X4 Pro myself, over a USB developer link. Below, every item says which it is: checked on the device, or tried on a computer only. The screenshots are from the simulator.

The home screen with all ten rows on, none cut off under the Continue card Settings, Reader: Continuous scrolling, Scroll step and Clean screen every N scrolls Settings, Connectivity, Translation: MyMemory by default, or a LibreTranslate server address, its API key and a Check Certificate switch Settings, System, About: the Open-source licences screen

Home with all ten rows, the scroll mode settings, the Translation settings, and the licences screen. There is no picture of the SSH screens: the simulator is built without SSH.

Checked on a real X4 Pro (a developer build of this code):

  • Search no longer freezes. Opening Search blocked the reader for about 12 seconds on a vault of a few hundred notes. Now the keyboard appears in 0.8 s instead of 12.7 s, and a search of unchanged vaults is ready in about 2 s: an unchanged vault costs one walk of its folders instead of a new index.
  • Gallery shows interlaced and 16-bit PNGs, which used to be an empty frame, and a page appears first with the thumbnails it already has.
  • Library shows the list first: the list shows in about 1.8 s instead of 3.5 s, and the read percents follow.
  • Home rows fit the screen with all 10 rows on (not yet in landscape).
  • Scroll mode (kos25k #30): Settings → Reader → Continuous scrolling, off by default. It works on the device, but the whole screen refreshes on every step: about 1.4 seconds a step against 0.6 for a page turn. docs/reading-and-files.md
  • The certificate check for GitHub works in a developer build: the update check, the font list and a firmware download all passed with it on, after SHA-384 was added to the TLS library (GitHub's chain is signed with it). The release build still doesn't check GitHub's certificate; that switch stays off for one more release.
  • Open-source licences: a screen under Settings → System → About with the GPL-3.0-or-later statement and the list, and docs/licenses.md with every library, font and icon.

Tried on a computer only, not on a device:

  • Translate lookups when the dictionary has no entry: MyMemory (free, no key) or a LibreTranslate server of your own. Only the selected text and the two language codes are sent, and it asks before the first use. docs/dictionary.md
  • SSH terminal and SFTP client (X4 Pro builds only): a shell on your own server on a line terminal, and SFTP in the same file browser as WebDAV and FTP. Tried against a real OpenSSH server from the computer, never from a device. docs/ssh.md
  • DOC and CHM books: Word 97-2003 .doc files and .chm help files open as text. docs/book-formats.md
  • Gamepad buttons (a scaffold): one Bluetooth gamepad's buttons can be learned for the reader's actions. It has never seen a real gamepad. docs/gamepad.md
  • Auto warmth by the sun: the night window can run from sunset to sunrise for the latitude and longitude you type.
  • Gestures inside Reading presets: Save preset asks "Include gestures".
  • Developer link, debug page and a developer build you can install: a read-only build answers status and log requests over USB, and the debug page makes a report file from it. It can't read or write your files or settings, press keys or flash anything. It can reboot the reader, change the log level, take a screenshot and write a small bench log to the card. I used the full developer build for my own tests; the read-only build and the page haven't been tried on a reader yet. docs/debug-page.md

The X4 Pro firmware now also holds wolfSSH (GPL-3.0-or-later), so the firmware binaries are distributed under the GPL-3.0-or-later; VaultInk's own code stays MIT (docs/licenses.md, NOTICE).

Known bug (fixed in 0.76.0): the bottom row of Settings (System) ignores a tap until you scroll the list.

New in 0.74.0: the KOReader milestone

A batch of reading tools and transfer features, picked from what KOReader has and VaultInk didn't. Everything below was tried on a computer and in the simulator, not on a device yet. The screenshots are from the simulator.

Book map: a strip with a segment per chapter, a marker at the current position, and a 'you were here' mark The More menu in a book, with Book map next to Go to % and Toggle Bookmark Settings, Reader, Gestures: a row for each corner tap, the centre tap and the four swipes, and the Quick Menu entries Settings, Display: Auto Warmth by Clock, Night From and Night Until hours, Night Warmth and Night Mode at Night

Book map, the More menu that opens it, the Gestures screen, and Auto Warmth in Display.

  • Book map and hidden flows (EPUB): one strip with a segment per chapter and ticks for bookmarks and highlights, drag to jump; long press a chapter to leave it out of the page count and percent. docs/reading-and-files.md
  • Gestures and a Quick Menu: set what the corner taps, the centre tap and the four swipes do in the reader. Every row starts on Default, which is how it worked before; the buttons and the edge gestures can't be changed, so you can't lock yourself out.
  • FB2, HTML and RTF books, Greek included, open like text books.
  • Auto warmth by the clock: warmer light, and night mode if you want, between two hours or from sunset to sunrise.
  • Wikipedia lookup when the dictionary has no entry, with the connection certificate-checked.
  • Highlights to Readwise or Memos from the Clippings screen. docs/exports.md
  • WebDAV and FTP clients to browse a server and copy files to or from the card. FTP is not encrypted and asks before every connect. docs/webdav-ftp.md
  • USB Drive (File Transfer over the USB-C cable) and the Power + Down screenshot now have guides. docs/webserver.md

What isn't in 0.74.0 (all of it came in 0.75.0): scroll mode, the SSH terminal and SFTP, the gamepad scaffold, and gestures as profiles. The update check and GitHub downloads are not certificate-checked yet; that code is written; it passed on a real X4 Pro in a 0.75.0 developer build and is still off in the release. wolfSSL (TLS 1.3) is GPL-2.0-or-later, so the firmware binaries are under the GPL terms; VaultInk's own code stays MIT (NOTICE).

New since 0.62 (up to 0.70.0)

Eleven releases in four days, most of it from kos25k's issues. The screenshots are from the simulator, except the companion ones, which come from a phone.

MOBI, AZW and AZW3 (0.67.0, 0.67.1)

A Huffman-compressed MOBI open on VaultInk An AZW3 book open on VaultInk

.mobi and .prc books open and show in the Library and in Browse Files, with a MOBI / AZW row in Book formats. Bold, italic, headings, lists, tables and pictures show. There are no chapters yet: the whole book is one chapter, like a .txt. Many MOBI files, most Kindle-store downloads without DRM among them, use Huffman compression, and 0.67.0 refused those; 0.67.1 reads them, and opens .azw and .azw3 too. For the newer AZW3 files the text reads in order, but pictures, links and chapters don't work yet, and a heading can sit apart from its paragraph. Books with DRM are refused with a message. docs/book-formats.md

Advanced Typography (0.66.0)

The five Advanced Typography switches, still called Experimental in 0.66.0

Settings → Reader → Advanced Typography, and in a book Text → Advanced Typography. Five switches: ligatures (fi, fl), kerning, widow and orphan control, keeping headings with their text, and hanging punctuation. The first four were always on and still are by default; now you can turn them off. Hanging punctuation is new and off by default: an opening quote or bracket at the start of a line hangs into the left margin, and a closing mark at the end of a justified line into the right one, Greek « » and ano teleia included, up to 12 px. It needs a little page margin. docs/reading-and-files.md

Reading presets and the More menu (0.70.0)

Reading presets in Settings Reading presets from the book menu The end of the More menu

Ten slots, in Settings → Reader → Reading presets and as the last row of the book menu → More. Save preset keeps your current Text settings in a slot with a name you give it: font, size, line spacing, alignment, hyphenation, Focus Reading, Even Word Gaps, word and character spacing, margin, paragraph indent and the five Advanced Typography switches and (0.76.0) the seven Typography Engine settings. Inside a book one press on a slot applies it and the page is laid out again. In the More menu, Search, Go to % and Go to page come first; the favourite toggle, Take screenshot, Show page as QR, Delete Book Cache, Go Home and Reading presets come last. Frontlight and Night Mode left More, and are still in the quick settings. docs/reading-and-files.md

Page numbers and the status bar (0.65.0 to 0.68.0)

Customise Status Bar Go to page

A book page number in brackets, like (37), next to the battery, counted from the first chapter, with a second switch to keep it when the bar is hidden. It's an estimate and changes with the font. Hide Status Bar sits in Customise Status Bar and in the book menu under More. Go to page (More, under Go to %) is a slider that counts pages the same way, so it's an estimate too; the side buttons jump by a twentieth of the book. It isn't for notes.

The home screen, the home button and the stars (0.68.0 to 0.70.0)

The home screen with even tiles The home screen with the favourites star

Every home tile is the same height with the same gap, the Books icon is bigger, and the Books count counts only books in the formats ticked in Book formats, not notes, text files or canvases. A ★ marks a favourite on the Continue Reading card, in Browse Files before the file type, and on the quick settings book card. A long press on the house at the top puts the reader to sleep, a tap still goes home, and the house has a small crescent moon on its roof. A Wi-Fi mark and a Bluetooth mark appear next to the battery as soon as the radio is on, with a ! until it's connected, and are gone when it's off.

Browse Files (0.64.0, 0.69.0, 0.70.0)

Browse Files with the sort gear, file-type icons and stars Search in Browse Files

Search finds files and folders by name across the whole card, up to 200 hits and 12 folders deep. The sort gear next to it (name, newest, oldest, largest, smallest, folders first) stays the same in every folder until you change it. Icons are bigger with the file type written inside a book's icon, and in a folder's the type it holds most. Info and the date sort use the time the file was last added or changed on the card. docs/reading-and-files.md

Papyrus, Battery and a Flashlight (0.65.0)

A page on the cracked papyrus Flashlight

Four more papyrus looks (aged, cracked, stained, crumpled), drawn in code. The Battery page splits awake drain into light off and light on (it needs a few days of new data and is approximate). Flashlight (Home → Plugins) is the front light as S.O.S., blinking or steady, with brightness, warmth and speed, and it puts the light back as it was when you stop.

Focus timer, Habits and Excalidraw (0.63.0)

The Focus timer Habits An Excalidraw drawing

A Pomodoro Focus timer that follows the clock even while the reader sleeps, and Habits, up to 16 daily habits with the last seven days, a streak and a total. .excalidraw files and the Obsidian plugin's .excalidraw.md open in a viewer with fit, pan and zoom, compressed drawings included. docs/tools.md

Typing, the phone and LiveSync (0.63.0 to 0.68.1)

The Greek on-screen keyboard Companion Help: the VaultInk documentation on the phone Companion About

A paired Bluetooth keyboard types into the on-screen keyboard's line (US and Greek, off by default). The keyboard has a From phone button for text the companion app left on the card, and the companion app can ask for a LiveSync sync that runs at the reader's next wake. LiveSync Setup URI (0.68.1): the reader said "Turn on end-to-end encryption (V2)" for a vault that already used V2, because the plugin leaves its default settings out of the Setup URI. A missing algorithm now counts as V2, and the message says what's really wrong. Companion 0.5.0 adds an intro, About, the whole VaultInk documentation as Help, each file's type in the list, and Bring notes in (a Google Keep Takeout as Markdown notes). docs/companion.md

What's tested on a real device, and what isn't

kos25k confirmed on his X4 Pro: the four papyrus looks, the Battery split, the Flashlight, the book page number, Hide Status Bar in the book menu, Advanced Typography, and MOBI, AZW and AZW3 (all three of his files opened). A cheap Bluetooth camera shutter turns pages with the Bluetooth Page Turner that was already there.

Everything else hasn't been on a device yet. Go to page, the home screen and the Books count, the stars, the Continue Reading fix, the Wi-Fi and Bluetooth marks, the sort gear and icons, reading presets, the More order and the sleep long press have only run in the simulator. Search in Browse Files, From phone, sync from the phone, the Focus timer, Habits, Excalidraw and the dice seed ran in the simulator and in tests on a computer. The LiveSync fix was checked against the plugin's source and with tests, not with a real vault. The Bluetooth keyboard hasn't met a real keyboard, and the companion app hasn't been tried against a real reader. VaultEUC has never talked to a real wheel: don't use it while riding, and rely on the wheel's own alarms. Back up your SD card before updating.

What it does

Each line links to its guide where there is one; all the guides are listed in docs/. The full list is in SPECS.md, what changed in each version is in CHANGELOG.md.

Books (what opens, and what doesn't: docs/book-formats.md)

  • Everything CrossPoint Reader offers: EPUB, TXT and XTC/XTCH books, SD-card fonts, hyphenation, bookmarks, highlights, dictionaries, KOReader sync, OPDS catalogs, Calibre wireless transfer and SD-card plugins. docs/reading-and-files.md
  • MOBI, PRC, AZW and AZW3 (0.67.0, 0.67.1): they open like a text book, read a record at a time, with bold, italic, headings, lists, tables and pictures; Huffman-compressed files too. No chapters yet, and AZW3 shows text only. DRM books are refused. Opened on a real X4 Pro (a MOBI, an AZW3 and an AZW). docs/reading-and-files.md
  • FB2, HTML and RTF (0.74.0, tested on a computer only): .fb2, .html / .htm / .xhtml and .rtf files open like a text book, read a piece at a time. FB2 keeps its sections, titles, poems and quotes; HTML its headings, lists and quotes; RTF its paragraphs, bold and italic. Greek works in all three (UTF-8, Windows-1253, ISO-8859-7, RTF \u and \'hh). No pictures and no chapters. docs/book-formats.md
  • DOC and CHM (0.75.0; tested on a computer only, not on a device): Word 97-2003 .doc files open as text (paragraphs, the result of fields, tables as text, footnotes at the end; no formatting, no pictures; password-protected files and .docx are refused: convert .docx to EPUB). .chm help files open as one book, the pages in the order of the contents list (no pictures, no links). VaultInk's own code, no library added. DjVu and scanned PDFs stay outside the reader: convert them first. docs/book-formats.md
  • Book map (0.74.0, computer tests only): More → Book map shows an EPUB as one strip, a segment per chapter, with marks for bookmarks and clippings and the place you were at. Drag along it to see the chapter, percent and estimated page, let go to jump; tap a bookmark's mark to open it. The chapter lists now show the page each chapter starts on. docs/reading-and-files.md
  • Hidden chapters (0.74.0, computer tests only): long-press a chapter in an EPUB's chapter list to leave it out of the book percent, the book page number, Go to page and Go to %. It can still be read. docs/reading-and-files.md
  • Auto warmth by the clock (0.74.0, computer tests only): Settings → Display turns the light warmer, and optionally night mode on, between two hours you pick. Or from sunset to sunrise where you are (0.75.0, computer tests only): type your latitude and longitude and the times are worked out on the device. docs/reading-and-files.md
  • Wikipedia lookup (0.74.0, computer tests only): when the dictionary has no entry, the Not found message offers Wikipedia. Wi-Fi comes on only on your tap, the article's summary shows as plain text in the book's language, and Wi-Fi goes off again. docs/dictionary.md
  • Translation lookup (0.75.0, computer tests only: the reader has never connected to the service): the same Not found message also offers Translate. Only the word or phrase you selected and the two language codes are sent, and a question says so before the first use. It asks MyMemory (free, no key, 5000 characters a day, results credited "MyMemory"), or a LibreTranslate server of your own set in Settings → Connectivity → Translation. docs/dictionary.md
  • Gamepad buttons (0.75.0, computer tests only, never tried with a real gamepad): the buttons of one Bluetooth gamepad can be learned for the reader's actions (pages, chapters, menus, night mode, light, bookmark, refresh, Home, screenshot) under Bluetooth Page Turner → Gamepad Buttons. Buttons only: no sticks, no triggers, no games. docs/gamepad.md
  • Highlights to Readwise and Memos (0.74.0, computer tests only, never tried against the real services): send a book's clippings to Readwise or to your own Memos server from the book menu or the Clippings screen. Wi-Fi comes on only for that job, what was sent is remembered so sending again sends only the new ones, and the access tokens are kept on the SD card (anyone with the card and the reader can get them). docs/exports.md
  • WebDAV and FTP servers (0.74.0, computer tests only, not tried on a device or against a real server): Home → Transfer & Remotes → Remote servers (Settings → Connectivity → WebDAV and FTP servers is a shortcut to the same list). Browse a server's folders, tap a file to download it to the card, upload a file from the card, make a folder. WebDAV over https can check the server's certificate; FTP and http:// are not encrypted, and the device says so and asks before every connection. Passwords are kept on the SD card only lightly scrambled, like the OPDS ones. docs/webdav-ftp.md
  • SSH terminal and SFTP (0.75.0, X4 Pro builds only; in 0.75.1 the terminal connected to a real server from a real X4 Pro, SFTP has run on a computer only): Home → Transfer & Remotes → SSH terminal (Settings → Connectivity → SSH servers is a shortcut to the same list). A shell on your own server on a line terminal (no vim or htop), typed with a Bluetooth keyboard or the key row on the screen, in a fixed-width font in four sizes (80, 60 or 48 columns; 0.75.1, seen on a real X4 Pro, the smallest size not judged), and SFTP in the same file browser as WebDAV and FTP. The password is typed at every connection and never saved, or the device signs in with its own Ed25519 key, made on the device and shown as a QR code for authorized_keys. The server's key is pinned at the first connection and a changed key is refused. The SSH library (wolfSSH) is GPL-3.0-or-later, which makes the firmware binaries GPL-3.0-or-later from 0.75.0. docs/ssh.md
  • Certificate checks (0.74.0, computer tests only): Wikipedia is always checked against root certificates built into the firmware. The update check and downloads from GitHub are not checked yet in the release build. In 0.75.0 the check was tried on a real X4 Pro in a developer build (update check, font list, firmware download) and works, after SHA-384 was added to the TLS library; it stays off in the release for one more version. KOReader sync has a new Check certificate switch, off by default so existing setups keep working. docs/reading-and-files.md
  • PDF as text: a PDF opens as reflowing text, Greek and filled-in form fields included, up to four columns, with its headings, bold and italic (the Style setting turns them off) and its filled boxes marked by dash lines (0.73.0); no pictures, tables or scans. PDFs are listed in the Library. docs/reading-and-files.md
  • Comics: CBZ files open straight from the card (JPEG and PNG pages, chapters from folders, covers, landscape spreads as two pages, manga right to left, a page cache for faster turns). XTC/XTCH files from the Banana Comic Converter open with their chapters; a QR code in Settings opens the converter on your phone. docs/comics.md
  • Highlights to a vault note: a book's clippings written to Highlights/<title>.md in your vault, and sent on by LiveSync. docs/reading-and-files.md

Library and finding your place

  • Library: tabs for Recent, Title, Author, Favourites and Folders, in an order you choose and with a tab it opens on. Sort Recent by how far you have read (↑% and ↓%), with the percent on every book. A gear filters the formats; All | Books only hides notes and text files (what is in /Vaults is never listed: vaults are not books); Authors can be folders; a long press on any book gives Open, Delete, Favourites and Info. docs/reading-and-files.md
  • Favourites and Book info on a long press (title, author, size, percent read), in the Library, Browse Files and the home card. docs/reading-and-files.md
  • Random page! (a Home item, off by default): a random page of a random book, saving nothing, with a way back to where you were. docs/reading-and-files.md
  • Reading stats on a sleep screen: today, this week, this month and total, your last three books, a month calendar, streaks and finished books. docs/reading-and-files.md

Obsidian vaults (docs/editing.md, docs/livesync.md, docs/flashcards.md)

  • Every vault on the card (a folder in /Vaults) opens like a folder of notes, and remembers the note you read last. The Vaults screen lists your recent notes.
  • Notes read like book pages: headings, lists, tasks as real boxes, quotes, callouts in a frame, tables, code, footnotes, highlights (three styles), pictures with their sizes, note embeds (whole note, a heading or a block), frontmatter and tags, with Greek throughout. Links resolve the way Obsidian does, with aliases and partial paths; a note's menu has Backlinks and a « Back row.
  • Search across every vault by title, alias, tag, heading, text and block id; a hit in a heading or block opens the note right there. Accents and capitals never matter.
  • Edit on the device: tick tasks, edit a note line by line with undo, join lines, make, rename and delete notes (to .trash). Renaming a note updates the links to it. Untouched lines keep their exact bytes, and every save goes through a temp file.
  • LiveSync both ways with Obsidian Self-hosted LiveSync over Wi-Fi: end-to-end encryption, certificate checks, a Sync tile in quick settings, sync on wake every 6 or 24 hours, and conflicts kept as a copy, never overwritten. Not tried against a real Obsidian install yet.
  • Flashcards written in your notes (Front::Back, ? cards, {{gaps}}), reviewed with spaced repetition, per deck or per note. Nothing is written into your notes.
  • Canvas files open in a viewer: pan, zoom, pictures in cards, tap a card to open its note. Excalidraw drawings (.excalidraw, the plugin's .excalidraw.md, compressed too) open the same way, read only.
  • Import a vault from a ZIP on the device's web page. Pictures in your vaults show in the Gallery.

Reading comfort, search and typography

  • Search in Book: a word or phrase, partial or whole words (accents and capitals never matter), starting at your chapter and wrapping, with the words shaded on the page and a bar to step through the hits or go back to your place. A gear sets the type and the range; an opt-in index makes repeat searches faster. docs/reading-and-files.md
  • Text panel in the book with every layout setting: font, size, line spacing 0 to 10, alignment, hyphenation (on by default, Greek and polytonic too), Even Word Gaps, word and character spacing, screen margin down to 0, paragraph indent. Changes show at once. docs/reading-and-files.md
  • Advanced Typography (0.66.0): switches for ligatures, kerning, widow and orphan control, headings kept with their text, and hanging punctuation. docs/reading-and-files.md
  • Typography Engine (0.76.0, every setting checked on a real X4 Pro): seven settings, all off by default, in Settings → Reader and in the book's Text panel. Space condensing (word gaps may shrink to 90% down to 50% of a space so one more word or syllable fits a justified line), letter spacing on loose lines, a locked space after an opening quote or a dash, and for hyphenation a mode (patterns, soft hyphens only, off), the fewest letters before and after a hyphen, and a language to use instead of the book's. docs/reading-and-files.md
  • Reading presets (0.70.0): ten named sets of your Text settings, saved and applied from Settings → Reader or the last row of the book menu's More, so one press applies one while you read. A preset can also carry your gestures and Quick Menu (0.75.0, computer tests only): Save preset asks "Include gestures". docs/reading-and-files.md
  • Page backgrounds: fourteen of them, from plain to papyrus and bath towel, a set you choose for the quick-settings paper tile, and a 0 to 100 contrast slider with a preview. Mostly for fun.
  • Status bar: choose what it shows, hide it from Settings or the book menu, and show the page number counted from the start of the book in brackets, even with the bar hidden (the number is an estimate for books). Go to page in the book menu under More (0.68.0) jumps by that number. docs/reading-and-files.md
  • Tap Zones: turn pages from the whole page or the corners only, so a stray finger does nothing. docs/reading-and-files.md
  • Gestures and a Quick Menu (0.74.0, computer tests only): Settings → Reader → Gestures gives the corner taps, the centre tap and the four swipes an action each (next chapter, bookmark, night mode, light panel, a Quick Menu of up to six actions, and more). The buttons and edge swipes stay fixed. docs/reading-and-files.md
  • Quick settings on a swipe down: light and warmth, night mode, refresh, sleep, Wi-Fi, Sync, Library, the paper tile, and a book card that opens the Library or goes Home. One menu at a time, so menus never stack.

Tools (Home → Plugins, built into the firmware: docs/tools.md)

  • Sudoku: three levels, pencil notes, undo, hints, a timer, and it saves where you left off.
  • Dice: polyhedral dice with advantage, keep-highest and exploding dice; old World of Darkness; Vampire V5 with Hunger dice, Willpower reroll and Rouse checks; Chronicles of Darkness; Fate; Powered by the Apocalypse; Blades in the Dark; Call of Cthulhu; Shadowrun; Savage Worlds; Year Zero; Cyberpunk Red. The seed mixes the chip's generator with the time and the battery. Not tried on a device yet. docs/reading-and-files.md
  • Focus timer: a Pomodoro timer that follows the clock, so a sleeping reader still knows when a phase ended; finished phases are logged. Habits: up to 16 daily habits with the last seven days, a streak and a total.
  • Flashlight (0.65.0): the front light as an S.O.S., blinking or steady, with brightness, warmth and flash speed.
  • VaultEUC: an electric unicycle companion over Bluetooth (Begode, Veteran/Leaperkim, KingSong, InMotion, Ninebot, VESC): live numbers every 5 to 30 seconds, alarm limits, ride logs as CSV on the card, your wheels remembered, km/h or mph, a demo wheel to try it. Not for use while riding, and not tried on a real wheel yet. docs/vaulteuc.md
  • Plugins from the SD card and the Plugin Hub: docs/sd-plugins.md.

The device

  • Home screen with the book or note you were reading on top, counts on the Books and Vaults rows, rows in any order and any of them hidden, a home button in the top bar, and a Favourites row. CrossPoint's home styles stay as a choice. docs/reading-and-files.md
  • Settings grouped by task, with a search that finds a setting by name, and rows that show their current value.
  • Browse Files with Open, Delete, Rename, Move, Copy, New folder, Extract here for zips, Open as gallery and Info on every file. Books keep their place when they or their folder move. A magnifier searches the whole card by name (0.64.0). docs/reading-and-files.md A sort gear (name, date, size) is kept in every folder, list icons are bigger with the file type written inside (a folder shows its most common type), and favourite books have a ★ (guide).
  • Gallery for the pictures on the card, nine to a page, with filters, chosen folders, phone photos up to 50 MP, and Set as sleep picture. docs/reading-and-files.md
  • Sleep screens: your own picture (JPEG, PNG or BMP, cropped or fitted), the battery percent, the owner's name and phone, or the reading stats.
  • Lock screen with a 4-digit PIN or a corner long-press, how long after sleeping it locks, and the owner's name and phone on it. docs/reading-and-files.md
  • Battery page: charge, voltage, charging, temperature, and the drain per hour asleep and awake (light off and on). docs/reading-and-files.md
  • Updates over Wi-Fi from the reader, with the release notes shown first, What's New after an update, and a five-page welcome guide on the first start. Debug logs to the card on request. docs/debug-logs.md
  • No telemetry, accounts or payments; the update check is the only network call you don't start yourself.

Phone, Bluetooth and languages

  • Transfer & Remotes on the Home screen (it was called File Transfer): file transfer over Wi-Fi (as vaultink.local), USB Drive (the SD card as a drive over the USB-C cable, no Wi-Fi: Transfer & Remotes → USB Drive) and Calibre, plus the lists of your WebDAV, FTP and SFTP servers and the SSH terminal; a web page for files, notes, settings, LiveSync setup and vault import. docs/webserver.md
  • Android companion app (docs/companion.md): quick notes into a vault, share text, pictures, books and comics from other apps, the SD card with uploads and downloads, the reader's settings, a comic converter inside the app, an outbox for when the reader is away, a Google Keep importer, LiveSync status with a sync request, typing into the reader from the phone, and the documentation offline. English and Greek. Tested against the simulator, not a real X4 Pro yet. Companion 0.6.0 (not released yet) adds a Home tab with the reader's status, Reader setup from the phone (Wi-Fi networks, LiveSync, OPDS catalogues, remote servers, fonts), a settings backup and a new look; run on a OnePlus phone against a real X4 Pro (Home, the Note tab's vault list, Settings and the Fonts list seen working); backup and restore, uploads, saving in Reader setup and rotation are unit tests only.
  • Bluetooth: a page-turner remote, and a Bluetooth keyboard can type into the on-screen keyboard's line (off by default, not tried with a real keyboard). docs/reading-and-files.md
  • Full Greek interface, a Greek and English on-screen keyboard, Greek (monotonic and polytonic) in the built-in fonts and hyphenation. Menus in many more languages from CrossPoint. docs/translating.md

Page backgrounds

Swiping down quick settings and tapping the paper tile to change the page background Settings, Paper Button Cycle, with the contrast row on top

Swipe down from the top for quick settings, then tap the paper tile to change the page background under the text. It's also under Settings → Reader → Page Background. The choices are plain, paper, sandpaper, papyrus (soft, medium, hard, cloudy, aged, cracked, stained and crumpled), toilet paper, kitchen paper and bath towel. Settings → Reader → Paper Button Cycle sets which of them the tile steps through, and its first row, Paper contrast, opens a 0 to 100 slider with a tile of every background that changes as you move it (0.60.0).

While a background is on, text anti-aliasing is switched off, so the letters stay sharp on the real screen. This one is mostly for fun 😄. Plain is the default and the easiest to read, but the papyrus ones are actually nice for a long read. The idea came from kos25k.

Getting started

The first time VaultInk starts, it shows a short welcome guide. The five pages are below.

Welcome page Reading page Quick settings page Adding books page Last page

  1. Welcome. VaultInk is for your books and your Obsidian vaults. The menus are in English, Greek and many other languages, listed on this page.
  2. Reading. Swipe left for the next page and right for the previous one, or use the side buttons. Tap the middle of the page to open the reading menu.
  3. Quick settings. Swipe down from the top of the screen, or tap the battery. You get the light, night mode, sleep, and a full refresh (to clear ghost images).
  4. Adding books. Copy books into the books folder on the SD card, or send them from your computer with Transfer & Remotes on the Home screen (Wi-Fi, USB Drive over the USB-C cable, or Calibre).
  5. That's it. Open the guide again from Settings → System → Welcome Guide. It also comes back once after an update that changes it. To stop that, turn off Show Welcome Guide After Updates in the same place.

Screenshots. Hold Power and press Down at the same time, on any screen, and the reader saves what is on the screen as a BMP in /screenshots/ on the SD card (in a book it goes in a folder with the book's title). The Down button is the right-hand side button on the X4 Pro. Inside a book it is also in the book menu, under More, as Take screenshot. docs/reading-and-files.md

Menus in Greek: Settings → System → Language, then Ελληνικά (second in the list, right after English). Back in Greek the same place is Ρυθμίσεις → Σύστημα → Γλώσσα.

In the guide, Next (or OK, or the right and down keys) moves on. Back goes back a page. On the first page, Back asks whether you want to skip.

Comics and manga, with Banana Comic Converter

Banana Comic Converter on a phone

Comics on the X4 Pro go through Banana Comic Converter, made by u/curseofthebanana (Reddit, GitHub: seethroughme). It's a free tool in your browser, on a phone or a computer, with no AI: it cuts every page into its panels and repacks them to fill the small screen, instead of shrinking the whole page. It has an X4 / X4 Pro preset, manga (right-to-left) or western order, a full panel editor for the pages it gets wrong, batch conversion and file splitting, and it writes XTC, XTCH, EPUB and CBZ.

We're working on this together: its author is happy for VaultInk to send comic readers their way, and VaultInk is built to open what it makes. Convert to XTCH (or XTC for the fastest page turns), upload the file with the companion app or the web page, and read it like a book. The companion app converts comics too, XTCH pages turn faster since 0.36.1, and since 0.39.0 plain CBZ files open as well (JPEG and PNG pages). The guide: docs/comics.md.

On the X4 Pro, Settings → Library → Convert comics shows a QR code that opens the converter on your phone.

If it saves you time, the converter's page has a "Buy me a coffee" link for its author.


What's coming

The roadmap has the details and the order. Open items right now:

  • The backup and restore page for the web loader is written but not published: it failed to connect to my X4 Pro in Chromium on Linux (the port was lost a few milliseconds after it opened, and a third-party flasher failed the same way, while Espressif's own esptool works). It needs a working test on a real reader first. docs/backup-restore.md
  • Switching on the certificate check for GitHub in the release build. On 2026-11-15 my developer build passed the update check and the font list with it on; the firmware download and a run with the clock not yet set still need a test.
  • Real-device testing of what 0.75.0 has only run on a computer: SFTP (the SSH terminal connected from a real X4 Pro in 0.75.1), DOC and CHM books, the translation lookup (the reader has never connected to the service), the gamepad buttons (never tried with a real gamepad), and Highlights to Readwise and Memos.
  • Real-device testing of most of 0.74.0 (book map, hidden flows, gestures, FB2/HTML/RTF, auto warmth, Wikipedia, WebDAV and FTP).
  • Scroll mode works on the device but refreshes the whole screen on every step (about 1.4 seconds); a partial refresh would make it usable for long reading. See Continuous scrolling.
  • Typography Engine: right-to-left, mixed-direction, CJK and ruby text are laid out as before; the language of a single passage inside a book is not read; more hyphenation languages would have to load from the SD card, as the firmware has no room for them.
  • The 34 languages other than English and Greek have the texts added after 0.75.0 (Transfer & Remotes and its rows, the terminal text size, the Typography Engine settings), but those are machine-written and not yet reviewed by a native speaker; corrections are welcome (docs/translating.md). The older VaultInk texts and the three longer help texts that name Transfer & Remotes still show in English there.
  • Real-device testing of older features: MOBI and AZW books, Advanced Typography, Dice, VaultEUC with a real wheel and the Bluetooth client and keyboard.
  • Chapters and the cover for MOBI books, and pictures and links for AZW3.
  • The XTCH refresh choice and a few share-to-reader edge cases wait for device tests.

The companion app lives in companion/ in this repo and is released separately (guide: docs/companion.md).

Companion 0.6.0 (not released yet): run on a OnePlus phone against a real X4 Pro (Home, the Note tab's vault list, Settings and the Fonts list seen working); backup and restore, uploads, saving in Reader setup and rotation are unit tests only.

Companion 0.6.0: the Home tab with the reader's status Companion 0.6.0: the Note tab with the vault list Companion 0.6.0: Settings with Reader setup Companion 0.6.0: the fonts on the reader's card

Until 0.5.0:

Companion: a quick note into a vault Companion: the reader's SD card Companion: the reader's settings Companion: no reader found, with the app update check

What is in and out of scope is in SCOPE.md.

Installing

The easiest way is the web installer at https://somnius.github.io/VaultInk/. Pick your device there and follow its steps. For the X4 Pro, in short:

  1. Back up your SD card.
  2. Copy vaultink-<version>-x4pro.bin from the latest release (not the factory file) to the SD card, so you can reinstall from the reader under Settings → System → SD Card Firmware Update.
  3. Put the reader in boot mode: switched off, hold Power, then also hold both page-turn buttons.
  4. Connect it over USB-C to a computer with Chrome or Edge and press Install. Erasing the device wipes the reader's own memory (settings, Wi-Fi networks), not the SD card.

After that, updates come over Wi-Fi: Settings → System → Check for Updates shows what's new in the newest release (scroll it), with Cancel and Update at the bottom, and Update installs it.

You can also build it yourself (see below) and flash it over USB with esptool:

esptool.py --chip esp32s3 --port /dev/ttyACM0 --baud 921600 write_flash 0x0 .pio/build/x4pro/firmware.factory.bin

Tech stack

Device Xteink X4 Pro: ESP32-S3, 480×800 e-ink touch screen, SD card
Firmware C++20 on Arduino and FreeRTOS (ESP-IDF underneath), built with PlatformIO
Base CrossPoint Reader and the FreeInk SDK (drivers, UI, keyboard)
Notes A streaming Markdown to XHTML converter, so notes render through the book reader
Search A per-vault index file on the SD card, updated incrementally, with Greek and accent folding
Desktop An SDL2 simulator that runs the same code, and host tests with CMake and GoogleTest
Installer ESP Web Tools on GitHub Pages; the firmware is built locally, not on CI

Building

You need PlatformIO and a copy of this repository with its submodules:

git clone --recursive https://github.com/Somnius/VaultInk.git
cd VaultInk
pio run -e x4pro            # firmware for the X4 Pro
pio run -e simulator_x4_pro # desktop simulator (Linux needs SDL2 and OpenSSL headers)

The simulator runs the same code in a window on your computer. It reads its "SD card" from a folder called fs_ in the directory you start it from:

mkdir -p fs_/books && cp some-book.epub fs_/books/
.pio/build/simulator_x4_pro/program

Arrow keys are the buttons, Enter is OK, Escape is Back, and the mouse works as touch.

For work on the firmware there is a developer build, pio run -e x4pro-dev, that answers status, reboot and flashing-mode commands over the USB cable (scripts/devlink.py), can log the battery to the SD card for drain tests with the cable out, and lets a script press keys, tap the screen, fetch the debug logs and screenshots, and flash a firmware file from the SD card. scripts/devtest.py plays a whole scripted test from a JSON file (keys, taps, waits, checks, screenshots) and keeps a log of it. The build's version ends in -dev. It is never a release build and has not been tried on a device yet: docs/devlink.md.

Help us debug

If you hit a bug and want to help find it, there is a developer build you can install from the install page ("Developer build (read-only debugging)"). It is the same firmware plus a read-only serial link: over the USB cable it answers a status request and prints its log. It can't read or write your files or settings, press keys or flash anything. It can reboot the reader, change the log level, take a screenshot and write a small bench log to the card. Installing it replaces your current firmware; the normal Install button puts the release back.

With it on the reader, open the debug page in Chrome or Edge on a computer, press Connect, and create a report: the status by default, log lines and screenshots only if you tick them. The page replaces Wi-Fi names, addresses, server names and file paths before you save the file, as well as it can, and shows you the text so you can check it. Nothing is uploaded by the page. Attach the report to a debug report issue (issues are public) or e-mail it to me@lefteros.com.

The page and the read-only developer build are new and have not been tried on a reader yet (my own tests used the full developer build); Windows is untested and phones are not supported yet. docs/debug-page.md has the steps and the Linux notes, docs/devlink.md what the link can and cannot do.

Translating

The menus are in English and Greek, and many other languages from CrossPoint Reader are partly there. To ask for your language or help translate it, see docs/translating.md, or open a translation request.

Author and donations

VaultInk is made by Lefteris Iliadis (lefteros.com). The app page, lefteros.com/en/apps/vaultink, has more about it, and you can donate there to support the project.

Credits

VaultInk stands on other people's work:

Libraries and licences

Every library, font and icon VaultInk uses is listed with its licence in docs/licenses.md: the firmware, the device's web pages, the companion app and the loader page. Each licence there was read from the library's own licence file; where there was no file to read, it says not verified. The same list is in NOTICE, on the device (Settings > System > About > Open-source licences) and in the companion app's About screen. The data is docs/third-party.json; python3 scripts/gen_licenses.py writes the rest from it.

License

MIT for VaultInk's own source. See LICENSE.

The firmware binaries also contain wolfSSL (TLS 1.3, GPL-2.0-or-later), wolfSSH (the SSH terminal and SFTP client, GPL-3.0-or-later) and Apache-2.0 libraries (NimBLE-Arduino, JPEGDEC and others). wolfSSL's "or later" lets the first two be combined under version 3, and Apache-2.0 is compatible with version 3 of the GPL but not version 2, so the binaries are distributed under the GPL-3.0-or-later, with the source in this repository. See NOTICE and docs/licenses.md.

About

Books and Obsidian vaults on the Xteink X4 Pro. Firmware based on CrossPoint Reader.

Topics

Resources

Stars

5 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages