This repository is CrossPoint Reader with a small set of changes so you can push EPUBs from your phone to the reader and have the book open immediately—a great match for Send to X4 (Android / iOS / browser) by Chapiware: install the app, join the same Wi‑Fi as the X4 running this firmware, send an article or EPUB, and the device can grab the file and jump straight into the reader without digging through the file browser.
Disclaimer — use at your own risk
The changes in this fork were developed with help from Cursor (AI-assisted editing in Cursor IDE). This is unofficial firmware: you use it entirely at your own risk. There is no warranty; neither the maintainer(s) nor Cursor are responsible for bricked devices, data loss, security issues, or any other harm. Keep a recovery path (e.g. official CrossPoint or stock firmware flashing) before you experiment.
Why we changed the firmware
- Send to X4 talks to the reader over local Wi‑Fi (no cloud). CrossPoint already exposes a web file transfer UI; we wanted that flow to be one gesture on the device and one less step after upload (open the book automatically).
- We use station (STA) mode: the reader joins your remembered Wi‑Fi (same network as the phone), not a device hotspot, which matches how Send to X4 expects to reach the X4 on your LAN.
What we added (summary)
| Area | Change |
|---|---|
| Gesture | Long-press Back (~2s) from most screens starts Quick File Transfer (won’t double-fire while you’re in the Wi‑Fi picker or keyboard). |
| Network | Opens WifiSelectionActivity with auto-connect to the last saved network when possible; otherwise the normal network list. |
| After upload | CrossPointWebServer accepts an optional upload callback; the first completed upload triggers goToReader(path) so the EPUB (or other supported file) opens immediately. |
| UI | Full white clear before drawing the transfer screen so the previous UI doesn’t ghost on e‑ink. |
| Plumbing | ActivityManager::goToQuickFileTransfer(), Activity::blocksQuickFileTransferHotkey() so sub-flows aren’t interrupted by the global long-press. |
Upstream & license
- All original CrossPoint code and docs remain MIT and belong to the CrossPoint project and its contributors.
- This fork is for personal/convenience use; send kudos to Chapiware for Send to X4.
Repository mirror note
This GitHub repo may ship without the upstream .github/ folder (issue templates, Actions workflows) so it can be pushed from tools that lack GitHub’s workflow OAuth scope. For CI and release automation, copy .github from crosspoint-reader/crosspoint-reader or push with a token that includes workflow scope.
Firmware for the Xteink X4 e-paper display reader (unaffiliated with Xteink). 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 Xteink firmware. It aims to match or improve upon the standard EPUB reading experience.
E-paper devices are fantastic for reading, but most commercially available readers are closed systems with limited customisation. The Xteink X4 is an affordable, e-paper device, 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:
- 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 the Xteink X4 hardware.
This project is not affiliated with Xteink; it's built as a community project.
- EPUB parsing and rendering (EPUB 2 and EPUB 3)
- Image support within EPUB
- Saved reading position
- File explorer with file picker
- Basic EPUB picker from root directory
- Support nested folders
- EPUB picker with cover art
- Custom sleep screen
- Cover sleep screen
- Wifi book upload
- Wifi OTA updates
- KOReader Sync integration for cross-device reading progress
- Configurable font, layout, and display options
- User provided fonts
- Full UTF support
- Screen rotation
Multi-language support: Read EPUBs in various languages, including English, Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Polish, Swedish, Norwegian, and more.
See the user guide for instructions on operating CrossPoint, including the KOReader Sync quick setup.
For more details about the scope of the project, see the SCOPE.md document.
- Connect your Xteink X4 to your computer via USB-C and wake/unlock the device
- Go to https://xteink.dve.al/ and click "Flash CrossPoint firmware"
To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
- Connect your Xteink X4 to your computer via USB-C
- Download the
firmware.binfile from the release of your choice via the releases page - 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 back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
- Install
esptool:
pip install esptool- Download the
firmware.binfile from the release of your choice via the releases page - Connect your Xteink X4 to your computer via USB-C.
- Note the device location. On Linux, run
dmesgafter connecting. On MacOS, run :
log stream --predicate 'subsystem == "com.apple.iokit"' --info- Flash the firmware :
esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.binChange /dev/ttyACM0 to the device for your system.
See Development below.
- PlatformIO Core (
pio) or VS Code + PlatformIO IDE - Python 3.8+
- USB-C cable for flashing the ESP32-C3
- Xteink X4
CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:
git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader
# Or, if you've already cloned without --recursive:
git submodule update --init --recursive
Connect your Xteink X4 to your computer via USB-C and run the following command.
pio run --target uploadAfter flashing the new features, it’s recommended to capture detailed logs from the serial port.
First, make sure all required Python packages are installed:
python3 -m pip install pyserial colorama matplotlibafter that run the script:
# For Linux
# This was tested on Debian and should work on most Linux systems.
python3 scripts/debugging_monitor.py
# For macOS
python3 scripts/debugging_monitor.py /dev/cu.usbmodem2101Minor adjustments may be required for Windows.
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.
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:
.crosspoint/
├── epub_12471232/ # Each EPUB is cached to a subdirectory named `epub_<hash>`
│ ├── progress.bin # Stores reading progress (chapter, page, etc.)
│ ├── cover.bmp # Book cover image (once generated)
│ ├── book.bin # Book metadata (title, author, spine, table of contents, etc.)
│ └── sections/ # All chapter data is stored in the sections subdirectory
│ ├── 0.bin # Chapter data (screen count, all text layout info, etc.)
│ ├── 1.bin # files are named by their index in the spine
│ └── ...
│
└── epub_189013891/
Deleting the .crosspoint directory will clear the entire cache.
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.
Contributions are very welcome!
If you are new to the codebase, start with the contributing docs.
If you're looking for a way to help out, take a look at the ideas discussion board. 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.
- Fork the repo
- Create a branch (
feature/dithering-improvement) - Make changes
- Submit a PR
CrossPoint Reader is not affiliated with Xteink or any manufacturer of the X4 hardware.
Huge shoutout to diy-esp32-epub-reader by atomic14, which was a project I took a lot of inspiration from as I was making CrossPoint.