justin/xteink-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Justin Oros
2026-04-09 17:21:05 -07:00
parent 26f9b6b20c
commit 0ed88204df
1 changed files with 73 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+73 -60
View File
@@ -7,44 +7,63 @@
# xteink-plugins # xteink-plugins
A plugin system for customizing and extending [CrossPoint Reader](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. 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 ## Plugins
### Dark Mode ### 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). 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 | State | Effect
|-------|--------| ------|--------
| **Disabled** | Normal display (default) | Disabled | Normal display (default)
| **Enabled** | Screen inverted — white text on black background | Enabled | Screen inverted — white text on black background
---
### Smaller Fonts ### 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. 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 | Mode | Effect
|------|--------| -----|--------
| **Disabled** | No change (default) | Disabled | No change (default)
| **Smaller** | Drops the current font size down by one step (e.g. Bookerly 16 → 14) | Smaller | Drops the current font size down by one step (e.g. Bookerly 16 → 14)
| **Smallest** | Drops the current font size down by two steps (e.g. Bookerly 16 → 12) | Smallest | Drops the current font size down by two steps (e.g. Bookerly 16 → 12)
Supports Bookerly, Noto Sans, and OpenDyslexic. The plugin also generates and embeds Bookerly at 8pt and 10pt — sizes not included in the stock firmware. Supports Bookerly, Noto Sans, and OpenDyslexic. The plugin also generates and embeds Bookerly at 8pt and 10pt — sizes not included in the stock firmware.
---
### 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
---
### Hardcover Sync ### Hardcover Sync
Automatically syncs your reading progress between your xteink device and [Hardcover.app](https://hardcover.app). This plugin: Automatically syncs your reading progress between your xteink device and https://hardcover.app.
- Extracts ISBN metadata from EPUB files to identify books - Extracts ISBN metadata from EPUB files to identify books
- Tracks reading progress (page numbers) while you read - Tracks reading progress (page numbers) while you read
- Automatically syncs progress for books with > 0% completion - Automatically syncs progress for books with > 0% completion
- Marks books as "Read" (status_id: 3) when you reach 100%+ completion - Marks books as "Read" when you reach 100%+ completion
- Requires a Hardcover API token configured in Settings - 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. Books without ISBN metadata or at 0% completion are skipped. 100%+ completed books are automatically moved to your "Read" shelf on Hardcover.
**Requirements:** Requirements:
- Active internet connection via WiFi - Active internet connection via WiFi
- Hardcover account and API token - Hardcover account and API token
- Books with embedded ISBN metadata - Books with embedded ISBN metadata
@@ -52,48 +71,38 @@ Books without ISBN metadata or at 0% completion are skipped. 100%+ completed boo
## Requirements ## Requirements
- Python 3.10+ - Python 3.10+
- [PlatformIO](https://platformio.org/) (`pio` on your PATH) - PlatformIO (pio on your PATH)
- `git` - git
- Your xteink device connected via USB - Your xteink device connected via USB
Install Python dependencies with: Install Python dependencies with:
```bash
pip3 install -r requirements.txt pip3 install -r requirements.txt
```
## Usage ## Usage
From the root of this repository, run: From the root of this repository, run:
```bash
python3 install.py python3 install.py
```
To auto-accept all plugin prompts, pass `--yes` (or `-y`): To auto-accept all plugin prompts, pass --yes (or -y):
```bash
python3 install.py --yes python3 install.py --yes
```
By default this uses the `default` build environment. To use a different environment pass `--environment` (or `-e`): By default this uses the default build environment. To use a different environment pass --environment (or -e):
```bash
python3 install.py --environment slim python3 install.py --environment slim
python3 install.py --environment gh_release python3 install.py --environment gh_release
```
Flags can be combined: Flags can be combined:
```bash
python3 install.py -y -e gh_release python3 install.py -y -e gh_release
```
| Environment | Description | Environment | Description
|-------------|-------------| ------------|-------------
| `default` | Debug logging enabled, version from current git branch (recommended) | default | Debug logging enabled, version from current git branch (recommended)
| `gh_release` | Info logging only, version hardcoded to release tag | gh_release | Info logging only, version hardcoded to release tag
| `slim` | No serial logging, smallest binary size | slim | No serial logging, smallest binary size
The installer will: The installer will:
@@ -102,62 +111,66 @@ The installer will:
3. Build the firmware with PlatformIO 3. Build the firmware with PlatformIO
4. Auto-detect your device's serial port and flash the firmware 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. 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 ## Repository Structure
```
xteink-plugins/ xteink-plugins/
├── install.py # Interactive installer: clone → patch → build → flash ├── install.py # Interactive installer: clone → patch → build → flash
└── plugins/ └── plugins/
├── darkmode/ ├── darkmode/
│ ├── patch.py # Patch script applied to the CrossPoint source │ ├── patch.py
│ ├── DarkModePlugin.h/.cpp # Dark mode state and screen inversion logic │ ├── DarkModePlugin.h/.cpp
│ └── DarkModeSettingsPage.h/.cpp # Settings UI activity │ └── DarkModeSettingsPage.h/.cpp
├── smallerfonts/ ├── smallerfonts/
│ ├── patch.py # Patch script applied to the CrossPoint source │ ├── patch.py
│ ├── SmallerFontsPlugin.h/.cpp # Font resolution logic │ ├── SmallerFontsPlugin.h/.cpp
│ └── SmallerFontsSettingsPage.h/.cpp # Settings UI activity │ └── SmallerFontsSettingsPage.h/.cpp
├── lockscreen/
│ ├── patch.py
│ ├── LockscreenPlugin.h/.cpp
│ ├── LockscreenSettingsPage.h/.cpp
│ └── LockscreenActivity.h/.cpp
└── hardcover/ └── hardcover/
├── patch.py # Patch script applied to the CrossPoint source ├── patch.py
├── HardcoverPlugin.h/.cpp # Hardcover sync logic ├── HardcoverPlugin.h/.cpp
└── HardcoverSettingsPage.h/.cpp # Settings UI activity └── HardcoverSyncActivity.h/.cpp
```
## Troubleshooting ## Troubleshooting
### Linux: Permission denied when flashing ### 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`, your user needs to be added to the `dialout` group: If you see an error like:
Could not open /dev/ttyACM0, the port is busy or doesn't exist
or Permission denied
Run:
```bash
sudo usermod -aG dialout $USER sudo usermod -aG dialout $USER
```
Log out and log back in for the change to take effect, then re-run `install.py`. Log out and log back in for the change to take effect, then re-run install.py.
### Windows: 'pio' is not recognized ### Windows: 'pio' is not recognized
If you see `'pio' is not recognized as an internal or external command`, PlatformIO is not on your PATH. Run the following in PowerShell to add it: If you see:
'pio' is not recognized as an internal or external command
Run in PowerShell:
```powershell
$env:PATH += ";$env:USERPROFILE\.platformio\penv\Scripts" $env:PATH += ";$env:USERPROFILE\.platformio\penv\Scripts"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User") [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")
```
If you installed Python from the Microsoft Store, the scripts folder is in a different location. Run this instead to find and add it: If Python was installed from the Microsoft Store:
```powershell
$scripts = (Get-ChildItem "$env:USERPROFILE\AppData\Local\Packages" -Filter "Scripts" -Recurse -ErrorAction SilentlyContinue | Where-Object { $_.FullName -like "*Python*" } | Select-Object -First 1).FullName $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" $env:PATH += ";$scripts"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User") [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")
```
Restart your terminal and re-run `install.py`. Restart your terminal and re-run install.py.
## Adding a Plugin ## Adding a Plugin
1. Create a new directory under `plugins/` with your plugin's name. 1. Create a new directory under plugins/ with your plugin's name.
2. Add a `patch.py` file with a `patch(repo_dir: str)` function. This function receives the absolute path to the cloned CrossPoint repository and should make all necessary modifications. 2. Add a patch.py file with a patch(repo_dir: str) function.
The installer will automatically discover and offer to install any directory under `plugins/` that contains a `patch.py`. The installer will automatically discover and offer to install any directory under plugins/ that contains a patch.py.