eric/Crosspoint
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: update README.md to reflect the current state of crosspoint (#1812)

Browse Source 
## Summary

As noted in
[#1680](https://github.com/crosspoint-reader/crosspoint-reader/discussions/1680#discussioncomment-16661106),
the README hasn't been updated in a while and has fallen behind the
actual firmware. This PR brings it up to date.

Beyond the feature list, I added a section acknowledging community forks
worth knowing about. I also took some deliberate editorial choices
around how CrossPoint is framed — I think it has the potential to be
more than just "an alternative Xteink firmware", and the wording
reflects that.

A note on process: I wrote the bulk of the text myself, but used AI
tools to scan the codebase and catch features I might have missed, and
to clean up my English (I'm fluent but not a native speaker). If any
line reads as unnatural or AI-sounding, please flag it — I'd rather fix
it than leave it.

---

One thing outside the scope of this PR: I think the cover photo could
use a refresh, ideally replaced with a small gallery showing different
CrossPoint screens. If you have a professional camera and an Xteink
device and want to help with that, let me know.

---------

Co-authored-by: Zach Nelson <zach@zdnelson.com>
This commit is contained in:
Uri Tauber
2026-05-15 15:38:22 -05:00
committed by GitHub
co-authored by Zach Nelson
parent 43b20bd8be
commit 0fbe6ff469
1 changed files with 147 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+143 -109
View File
@@ -1,53 +1,54 @@
# CrossPoint Reader # CrossPoint Reader
Firmware for **Xteink** e-paper display readers (X3 and X4) (unaffiliated with Xteink). CrossPoint is open-source e-reader firmware - community-built, fully hackable, free forever. It's maintained by a growing community of developers and readers who believe your device should do what you want - not what a manufacturer decided for you.
Built using **PlatformIO** and targeting the **ESP32-C3** microcontroller.
CrossPoint Reader is a purpose-built firmware designed to be a drop-in, fully open-source replacement for the official **Now running on:** ESP32C3-based Xteink [X4](https://www.xteink.com/products/xteink-x4) and [X3](https://www.xteink.com/products/xteink-x3).
Xteink firmware. It aims to match or improve upon the standard EPUB reading experience.
![](./docs/images/cover.jpg) ![CrossPoint Reader running on Xteink device](./docs/images/cover.jpg)
## Motivation ## What can CrossPoint do?
E-paper devices are fantastic for reading, but most commercially available readers are closed systems with limited - **Reader engine**: EPUB 2/3 rendering with embedded-style option, image handling, hyphenation, kerning, chapter navigation, footnotes, go-to-percent, auto page turn, orientation control, focus reading, KOReader progress sync and more.
customisation. **Xteink** devices (such as the X3 and X4) are affordable e-paper readers, however the official firmware remains closed.
CrossPoint exists partly as a fun side-project and partly to open up the ecosystem and truly unlock the device's
potential.
CrossPoint Reader aims to: - **Various formats**: native handling for `.epub`, `.xtc/.xtch`, `.txt`, and `.bmp`.
* Provide a **fully open-source alternative** to the official firmware.
* Offer a **document reader** capable of handling EPUB content on constrained hardware.
* Support **customisable font, layout, and display** options.
* Run purely on **Xteink hardware**.
This project is **not affiliated with Xteink**; it's built as a community project. - **Screenshots.**
## Features & Usage - **Custom fonts**: install your favorite fonts on the SD card.
- [x] EPUB parsing and rendering (EPUB 2 and EPUB 3) - **Tilt page turn (X3 only)**.
- [x] Image support within EPUB
- [x] Saved reading position
- [x] File explorer with file picker
- [x] Basic EPUB picker from root directory
- [x] Support nested folders
- [ ] EPUB picker with cover art
- [x] Custom sleep screen
- [x] Cover sleep screen
- [x] Wifi book upload
- [x] Wifi OTA updates
- [x] KOReader Sync integration for cross-device reading progress
- [x] Configurable font, layout, and display options
- [ ] User provided fonts
- [ ] Full UTF support
- [x] Screen rotation
Multi-language support: Read EPUBs in various languages, including English, Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Polish, Swedish, Norwegian, [and more](./USER_GUIDE.md#supported-languages). - **Library workflow**: folder browser, hidden-file toggle, long-press delete, recent books, SD-cache management.
See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint, including the - **Wireless workflows**:
[KOReader Sync quick setup](./USER_GUIDE.md#367-koreader-sync-quick-setup).
For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document. - File transfer web UI
- EPUB Optimizer
- Web settings UI/API (edit many device settings from browser)
- WebSocket fast uploads
- WebDAV handler
- AP mode (hotspot) and STA mode (join existing WiFi), both with QR helpers
- Calibre wireless connect flow
- OPDS browser with saved servers (up to 8), search, pagination, and direct download
- OTA update checks and installs from GitHub releases
- **Customization**: multiple themes (Classic, Lyra, Lyra Extended, RoundedRaff), sleep screen modes, front/side button remapping, status bar controls, power-button behavior, refresh cadence, and more.
- **Localization**: 22 UI languages and counting.
### Coming soon:
- RTL support — Arabic, Hebrew, and Farsi.
- Bookmarks.
- Dictionary lookup — inline word lookup without leaving the reader.
- More themes.
- Much more! stay tuned.
---
## USB-locked devices (Xteink Unlocker) ## USB-locked devices (Xteink Unlocker)
@@ -57,8 +58,8 @@ https://crosspointreader.com/#unlock-tool before you can flash CrossPoint.
**You do not need this tool if you bought your device directly from xteink.com.** Those units are not locked. **You do not need this tool if you bought your device directly from xteink.com.** Those units are not locked.
**Not sure if your device is locked?** Power it on, connect the USB-C cable, and try flashing via the web flasher first **Not sure if your device is locked?** Power it on, connect the USB-C cable, and try flashing via the web flasher first (see
(see [Installing](#installing) below). If the browser's serial device picker does not show your device, try a different [Install firmware](#install-firmware) below). If the browser's serial device picker does not show your device, try a different
USB port or browser before assuming the device is locked. Only reach for the unlocker if the device still doesn't appear. USB port or browser before assuming the device is locked. Only reach for the unlocker if the device still doesn't appear.
> ### ⚠️ WARNING: READ THIS BEFORE USING THE UNLOCKER ⚠️ > ### ⚠️ WARNING: READ THIS BEFORE USING THE UNLOCKER ⚠️
@@ -73,74 +74,96 @@ USB port or browser before assuming the device is locked. Only reach for the unl
> USB-locked unit, you will have **zero update or recovery path** and will be stuck on it forever. **Do not flash > USB-locked unit, you will have **zero update or recovery path** and will be stuck on it forever. **Do not flash
> Papyrix (or any other unsupported firmware) on a locked device.** > Papyrix (or any other unsupported firmware) on a locked device.**
## Installing ## Install firmware
### Web (latest firmware) ### Web installer (recommended)
1. Connect your Xteink device to your computer via USB-C and wake/unlock the device 1. Connect your device to your computer via USB-C and wake/unlock the device
2. Go to https://xteink.dve.al/ and click "Flash CrossPoint firmware" 2. Go to https://crosspointreader.com/#flash-tools, select device (X3 or X4), and choose an official CrossPoint release.
To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap ### Web installer (specific version)
back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
### Web (specific firmware version) 1. Connect your device to your computer via USB-C and wake/unlock the device
2. Download a `firmware.bin` from [Releases](https://github.com/crosspoint-reader/crosspoint-reader/releases), local build, or continuous integration artifact.
3. Go to https://crosspointreader.com/#flash-tools, select device (X3 or X4), click "Custom .bin" and upload a `firmware.bin`.
1. Connect your Xteink device to your computer via USB-C ### Revert to Official Firmware
2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases)
3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section
To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap To revert to the official firmware, you can also flash the latest official firmware using https://crosspointreader.com/#flash-tools.
back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
### Command line (specific firmware version) ### Command line
1. Install [`esptool`](https://github.com/espressif/esptool): 1. Install [`esptool`](https://github.com/espressif/esptool):
```bash ```bash
pip install esptool pip install esptool
``` ```
2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases)
3. Connect your Xteink device to your computer via USB-C. 2. Download `firmware.bin` from the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases).
4. Note the device location. On Linux, run `dmesg` after connecting. On MacOS, run : 3. Connect your device via USB-C.
4. Find the device port. On Linux, run `dmesg` after connecting. On macOS:
```bash ```bash
log stream --predicate 'subsystem == "com.apple.iokit"' --info log stream --predicate 'subsystem == "com.apple.iokit"' --info
``` ```
5. Flash the firmware :
5. Flash:
```bash ```bash
esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin
``` ```
Change `/dev/ttyACM0` to the device for your system.
Adjust `/dev/ttyACM0` to match your system.
### Manual ### Manual
See [Development](#development) below. See [Development quick start](#development-quick-start) below.
## Development ---
## Documentation
- [User Guide](./USER_GUIDE.md)
- [Web server usage](./docs/webserver.md)
- [Web server endpoints](./docs/webserver-endpoints.md)
- [Project scope](./SCOPE.md)
- [Contributing docs](./docs/contributing/README.md)
---
## Development quick start
### Prerequisites ### Prerequisites
* **PlatformIO Core** (`pio`) or **VS Code + PlatformIO IDE** - [pioarduino](https://github.com/pioarduino/pioarduino) or VS Code + pioarduino plugin
* Python 3.8+ - Python 3.8+
* USB-C cable for flashing the ESP32-C3 - `clang-format` 21
* Xteink device (X3 or X4) - USB-C cable supporting data transfer
### Checking out the code ### Setup
CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository: ```bash
```
git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
cd crosspoint-reader
# Or, if you've already cloned without --recursive: # if cloned without --recursive:
git submodule update --init --recursive git submodule update --init --recursive
``` ```
### Flashing your device ### Build / flash / monitor
Connect your Xteink device to your computer via USB-C and run the following command. ```bash
```sh
pio run --target upload pio run --target upload
``` ```
### Contributor pre-PR checks
```bash
./bin/clang-format-fix
pio check -e default
pio run -e default
```
### Debugging ### Debugging
After flashing the new features, it’s recommended to capture detailed logs from the serial port. After flashing the new features, it’s recommended to capture detailed logs from the serial port.
@@ -150,7 +173,9 @@ First, make sure all required Python packages are installed:
```python ```python
python3 -m pip install pyserial colorama matplotlib python3 -m pip install pyserial colorama matplotlib
``` ```
after that run the script:
After that run the script:
```sh ```sh
# For Linux # For Linux
# This was tested on Debian and should work on most Linux systems. # This was tested on Debian and should work on most Linux systems.
@@ -159,63 +184,72 @@ python3 scripts/debugging_monitor.py
# For macOS # For macOS
python3 scripts/debugging_monitor.py /dev/cu.usbmodem2101 python3 scripts/debugging_monitor.py /dev/cu.usbmodem2101
``` ```
Minor adjustments may be required for Windows. Minor adjustments may be required for Windows.
---
## Internals ## Internals
CrossPoint Reader is pretty aggressive about caching data down to the SD card to minimise RAM usage. The ESP32-C3 only CrossPoint Reader is pretty aggressive about caching data down to the SD card to minimise RAM usage. The ESP32-C3 only has ~380KB of usable RAM, so we have to be careful. A lot of the decisions made in the design of the firmware were based on this constraint.
has ~380KB of usable RAM, so we have to be careful. A lot of the decisions made in the design of the firmware were based
on this constraint.
### Data caching ### Data caching
The first time chapters of a book are loaded, they are cached to the SD card. Subsequent loads are served from the The first time chapters of a book are loaded, they are cached to the SD card. Subsequent loads are served from the
cache. This cache directory exists at `.crosspoint` on the SD card. The structure is as follows: cache. This cache directory exists at `.crosspoint` on the SD card. The structure is as follows:
```text
```
.crosspoint/ .crosspoint/
├── epub_12471232/ # Each EPUB is cached to a subdirectory named `epub_<hash>` ├── epub_<hash>/ # one directory per book, named by content hash
│ ├── progress.bin # Stores reading progress (chapter, page, etc.) │ ├── progress.bin # reading position (chapter, page, etc.)
│ ├── cover.bmp # Book cover image (once generated) │ ├── cover.bmp # generated cover image
│ ├── book.bin # Book metadata (title, author, spine, table of contents, etc.) │ ├── book.bin # metadata: title, author, spine, TOC
│ └── sections/ # All chapter data is stored in the sections subdirectory │ └── sections/ # per-chapter layout cache
│ ├── 0.bin # Chapter data (screen count, all text layout info, etc.) │ ├── 0.bin
│ ├── 1.bin # files are named by their index in the spine │ ├── 1.bin
│ └── ... │ └── ...
│
└── epub_189013891/
``` ```
Deleting the `.crosspoint` directory will clear the entire cache. Removing `/.crosspoint` clears all cached metadata and forces a full regeneration on next open. Note: the cache isn't cleared automatically when you delete a book, and moving a file to a new path resets its reading progress.
Due the way it's currently implemented, the cache is not automatically cleared when a book is deleted and moving a book
file will use a new cache directory, resetting the reading progress.
For more details on the internal file structures, see the [file formats document](./docs/file-formats.md). For more details on the internal file structures, see the [file formats document](./docs/file-formats.md).
---
## Contributing ## Contributing
Contributions are very welcome! Contributions are welcome. If you're new to the codebase, start with the [contributing docs](./docs/contributing/README.md). For things to work on, check the [ideas discussion board](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas) — leave a comment before starting so we don't duplicate effort.
If you are new to the codebase, start with the [contributing docs](./docs/contributing/README.md). Everyone here is a volunteer, so please be respectful and patient. For governance and community expectations, see [GOVERNANCE.md](./GOVERNANCE.md).
If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas).
If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.
Everyone here is a volunteer, so please be respectful and patient. For more details on our governance and community
principles, please see [GOVERNANCE.md](GOVERNANCE.md).
### To submit a contribution:
1. Fork the repo
2. Create a branch (`feature/dithering-improvement`)
3. Make changes
4. Submit a PR
--- ---
CrossPoint Reader is **not affiliated with Xteink or any manufacturer of the hardware**. ## Community forks
Huge shoutout to [**diy-esp32-epub-reader** by atomic14](https://github.com/atomic14/diy-esp32-epub-reader), which was a project I took a lot of inspiration from as I One of the best things about open source is that anyone can take the code in a different direction. If you need something outside CrossPoint's [scope](./SCOPE.md), check out the community forks:
was making CrossPoint.
- [CrossInk](https://github.com/uxjulia/CrossInk) — Typography and reading tracking: Bionic Reading (bolds word stems to create fixation points), guide dots between words, improved paragraph indents, and replaces the default fonts with ChareInk/Lexend/Bitter.
- [papyrix-reader](https://github.com/bigbag/papyrix-reader) — Adds FB2 and MD format support. Actively maintained with Arabic script support. Custom themes via SD card.
- [crosspet](https://github.com/trilwu/crosspet) — A Vietnamese fork that adds a Tamagotchi-style virtual chicken that grows based on your reading milestones (pages read, streaks, care). Also: Flashcards, Weather, Pomodoro timer, and mini-games.
- [crosspoint-reader (jpirnay)](https://github.com/jpirnay/crosspoint-reader) — Faster integration of functionality. Tracks upstream PRs and integrates the good ones ahead of the official merge.
- [crosspoint-reader-cjk](https://github.com/aBER0724/crosspoint-reader-cjk) — Purpose-built for Chinese, Japanese, and Korean reading.
- [inx](https://github.com/obijuankenobiii/inx) — Completely reimagines the user interface with tabbed navigation.
- ~~[PlusPoint](https://github.com/ngxson/pluspoint-reader) — custom JS apps support.~~ (Unmaintained)
- [crosspoint-reader-papers3](https://github.com/juicecultus/crosspoint-reader-papers3) — Crosspoint port for M5Stack Paper S3.
**Note:** Many of these features will make their way into CrossPoint over time. We maintain a slower pace to ensure rock-solid stability and squash bugs before they reach your device.
Want to build your own device? Be sure to check out the [de-link](https://github.com/iandchasse/de-link) project.
---
CrossPoint Reader is **not affiliated with Xteink or any device manufacturer**.
Huge shoutout to [diy-esp32-epub-reader](https://github.com/atomic14/diy-esp32-epub-reader), which inspired this project.