xteink-plugins

A plugin system for customizing and extending https://github.com/crosspoint-reader/crosspoint-reader firmware on your xteink device. Plugins are applied as source-level patches before the firmware is compiled and flashed.

Plugins

Dark Mode

Adds a Dark Mode option to the Plugins settings tab and the web interface Settings page. When enabled, the screen is inverted after each page render, producing white-on-black text across all reader formats (EPUB, TXT, and XTC).

State	Effect
Disabled	Normal display (default)
Enabled	Screen inverted — white text on black background

---

Smaller Fonts

Adds a Smaller Fonts option to the Plugins settings tab and the web interface Settings page. When enabled, your chosen reader font is transparently substituted with a smaller variant — no need to change your font preference.

Mode	Effect
Disabled	No change (default)
Enabled	Drops the current font size down by one step (e.g. Bookerly 16 → 14)

Supports Noto Serif, Noto Sans, and Bookerly.

---

Lockscreen

Adds a customizable Lockscreen experience to your xteink device.

This plugin introduces a dedicated lockscreen activity that is shown when the device wakes or powers on.

Features:

• Custom lockscreen activity integrated into firmware
• Four-digit PIN configurable on plugin enable
• Displays on device wake or power-on
• Replaces default wake screen behavior
• Clean UI consistent with CrossPoint Reader

---

Bookerly Font

Adds the Bookerly font to your xteink device, available as a reader font option alongside the built-in Noto Serif, Noto Sans, and OpenDyslexic fonts.

• Generates Bookerly at 12pt, 14pt, 16pt, and 18pt during install
• Selectable via Settings → Reader → Font
• Works with the Smaller Fonts plugin to drop one size step down (e.g. 16 → 14)

---

Hardcover Sync

Automatically syncs your reading progress between your xteink device and https://hardcover.app.

• Extracts ISBN metadata from EPUB files to identify books
• Tracks reading progress (page numbers) while you read
• Automatically syncs progress for books with > 0% completion
• Marks books as "Read" when you reach 100%+ completion
• Requires a Hardcover API token configured in Settings

Books without ISBN metadata or at 0% completion are skipped. 100%+ completed books are automatically moved to your "Read" shelf on Hardcover.

Requirements:

• Active internet connection via WiFi
• Hardcover account and API token
• Books with embedded ISBN metadata

---

GitHub Sync

Syncs .epub files from a private GitHub repository to your device on boot.

• Downloads new or updated books from your configured repo automatically on startup
• Skips files already on the device that haven't changed
• Configurable via Settings → Plugins → GitHub Sync (username, personal access token, repo, branch), after flashing

Requirements:

• Active internet connection via WiFi
• GitHub account with a repository containing your .epub files
• Personal access token with read-only Contents access to the repo

---

Requirements

• Python 3.10+
• PlatformIO (pio on your PATH)
• git
• Your xteink device connected via USB

Install Python dependencies with:

pip3 install -r requirements.txt

Usage

From the root of this repository, run:

python3 install.py

To auto-accept all plugin prompts, pass --yes (or -y):

python3 install.py --yes

By default this uses the default build environment. To use a different environment pass --environment (or -e):

python3 install.py --environment slim python3 install.py --environment gh_release

Flags can be combined:

python3 install.py -y -e gh_release

Environment	Description
default	Debug logging enabled, version from current git branch (recommended)
gh_release	Info logging only, version hardcoded to release tag
slim	No serial logging, smallest binary size

The installer will:

1. Clone the CrossPoint Reader source repository
2. Prompt you to select which plugins to install and apply them as patches
3. Build the firmware with PlatformIO
4. Auto-detect your device's serial port and flash the firmware

Note: This script modifies and flashes custom firmware to your device. The author accepts no responsibility for any damage that may occur to your device as a result of using this installer.

Repository Structure

xteink-plugins/
├── install.py              # Interactive installer: clone → select → apply → build → flash
├── framework/               # Shared plugin engine (see "Adding a Plugin" below)
│   ├── manifest.py          # Declarative contribution types plugins are built from
│   ├── engine.py             # Applies every selected plugin's contributions in one pass
│   └── discovery.py          # Finds plugin.py files under plugins/
├── test_harness.py          # Applies every plugin, alone and in combination, against a
│                             # fresh clone and reports pass/fail - run this after adding
│                             # or editing a plugin
└── plugins/
    ├── darkmode/
    │   ├── plugin.py
    │   └── DarkModePlugin.h/.cpp
    ├── smallerfonts/
    │   ├── plugin.py
    │   └── SmallerFontsPlugin.h/.cpp
    ├── lockscreen/
    │   ├── plugin.py
    │   ├── LockscreenPlugin.h/.cpp
    │   └── LockscreenActivity.h/.cpp
    ├── bookerly/
    │   ├── plugin.py
    │   └── BookerlyPlugin.h/.cpp
    ├── hardcover/
    │   ├── plugin.py
    │   ├── HardcoverPlugin.h/.cpp
    │   └── HardcoverSyncActivity.h/.cpp
    ├── githubsync/
    │   ├── plugin.py
    │   ├── GitHubSync.h/.cpp
    │   └── GitHubSyncSettingsActivity.h/.cpp
    └── pong/
        ├── plugin.py
        └── PongActivity.h/.cpp

Why plugin.py instead of patch.py

Previously every plugin's patch.py directly rewrote CrossPoint's shared source files with hand-written string edits, and each one had to hardcode knowledge of every other plugin's edits to land in the right place (e.g. darkmode's patch literally contained smallerfonts' settings entry). That's fine as long as you always install every plugin together in the same order, but install any subset, or add a new plugin later, and those hardcoded assumptions stop holding - settings referenced fields that were never declared, and the build failed.

plugin.py instead returns a declarative PluginManifest (see framework/manifest.py) describing what the plugin needs - a settings field, a row in the on-device "Plugins" tab, a new SettingAction, a boot-time hook, and so on. A single engine (framework/engine.py) collects the manifests of only the plugins you actually selected and writes each shared file exactly once, built fresh from that selection. Installing 1 plugin or all 7, in any combination, produces internally consistent output every time.

Troubleshooting

Linux: Permission denied when flashing

If you see an error like: Could not open /dev/ttyACM0, the port is busy or doesn't exist or Permission denied

Run:

sudo usermod -aG dialout $USER

Log out and log back in for the change to take effect, then re-run install.py.

Windows: 'pio' is not recognized

If you see: 'pio' is not recognized as an internal or external command

Run in PowerShell:

$env:PATH += ";$env:USERPROFILE.platformio\penv\Scripts" [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

If Python was installed from the Microsoft Store:

$scripts = (Get-ChildItem "$env:USERPROFILE\AppData\Local\Packages" -Filter "Scripts" -Recurse -ErrorAction SilentlyContinue | Where-Object { $_.FullName -like "Python" } | Select-Object -First 1).FullName $env:PATH += ";$scripts" [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

Restart your terminal and re-run install.py.

Adding a Plugin

1. Create a new directory under plugins/ with your plugin's name.
2. Add a plugin.py with a get_manifest(ctx) -> PluginManifest function. Use an existing plugin (e.g. plugins/pong/plugin.py for a simple action-row example, or plugins/darkmode/plugin.py for a settings-backed one) as a template. framework/manifest.py documents every contribution type: SettingsField, PluginsTabEntry, SettingActionEnumValue, MainHook, ToggleHook, TranslationEntry, and so on.
3. List any plugin-owned .h/.cpp files under source_files so the installer copies them into the firmware tree - you don't touch any shared CrossPoint file directly.
4. Run python3 test_harness.py <path-to-a-crosspoint-reader-clone> /tmp/scratch <your-plugin-name> (or all to check every plugin and combination) to confirm it applies cleanly alone and alongside everything else, before shipping it.

The installer automatically discovers and offers to install any directory under plugins/ that contains a plugin.py exposing get_manifest.