# CrossPoint Reader 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. **Now running on:** ESP32C3-based Xteink [X4](https://www.xteink.com/products/xteink-x4) and [X3](https://www.xteink.com/products/xteink-x3). ![CrossPoint Reader running on Xteink device](./docs/images/cover.jpg) ## What can CrossPoint do? - **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. - **Various formats**: native handling for `.epub`, `.xtc/.xtch`, `.txt`, and `.bmp`. - **Screenshots.** - **Custom fonts**: install your favorite fonts on the SD card. - **Tilt page turn (X3 only)**. - **Library workflow**: folder browser, hidden-file toggle, long-press delete, recent books, SD-cache management. - **Wireless workflows**: - 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) Some Xteink units purchased from third-party stores (e.g. AliExpress) ship with USB flashing locked from the factory. If your device is locked, you will need to use the **Xteink Unlocker** tool available at 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. **Not sure if your device is locked?** Power it on, connect the USB-C cable, and try flashing via the web flasher first (see [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. > ### ⚠️ WARNING: READ THIS BEFORE USING THE UNLOCKER ⚠️ > > **The only officially supported firmwares in the unlock tool are CrossPoint and CrossInk.** > > Flashing any other firmware on a USB-locked device may **permanently brick the device** or leave it **permanently > stuck on that firmware with no recovery path**. Once USB flashing is re-locked, your only way back is via OTA, and if > the firmware you flashed doesn't support OTA, **there is no way out**. > > **The Papyrix fork has removed OTA update support from its code.** If you flash Papyrix onto a > 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.** ## Install firmware ### Web installer (recommended) 1. Connect your device to your computer via USB-C and wake/unlock the device 2. Go to https://crosspointreader.com/#flash-tools, select device (X3 or X4), and choose an official CrossPoint release. ### Web installer (specific 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`. ### Revert to Official Firmware To revert to the official firmware, you can also flash the latest official firmware using https://crosspointreader.com/#flash-tools. ### Command line 1. Install [`esptool`](https://github.com/espressif/esptool): ```bash pip install esptool ``` 2. Download `firmware.bin` from the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases). 3. Connect your device via USB-C. 4. Find the device port. On Linux, run `dmesg` after connecting. On macOS: ```bash log stream --predicate 'subsystem == "com.apple.iokit"' --info ``` 5. Flash: ```bash esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin ``` Adjust `/dev/ttyACM0` to match your system. ### Manual See [Development quick start](#development-quick-start) below. --- ## 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 - [pioarduino](https://github.com/pioarduino/pioarduino) or VS Code + pioarduino plugin - Python 3.8+ - `clang-format` 21 - USB-C cable supporting data transfer ### Setup ```bash git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader cd crosspoint-reader # if cloned without --recursive: git submodule update --init --recursive ``` ### Build / flash / monitor ```bash pio run --target upload ``` ### Contributor pre-PR checks ```bash ./bin/clang-format-fix pio check -e default pio run -e default ``` ### Debugging After flashing the new features, it’s recommended to capture detailed logs from the serial port. First, make sure all required Python packages are installed: ```python python3 -m pip install pyserial colorama matplotlib ``` After that run the script: ```sh # 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.usbmodem2101 ``` Minor adjustments may be required for Windows. --- ## Internals 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. ### Data caching 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: ```text .crosspoint/ ├── epub_/ # one directory per book, named by content hash │ ├── progress.bin # reading position (chapter, page, etc.) │ ├── cover.bmp # generated cover image │ ├── book.bin # metadata: title, author, spine, TOC │ └── sections/ # per-chapter layout cache │ ├── 0.bin │ ├── 1.bin │ └── ... ``` 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. For more details on the internal file structures, see the [file formats document](./docs/file-formats.md). --- ## Contributing 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. Everyone here is a volunteer, so please be respectful and patient. For governance and community expectations, see [GOVERNANCE.md](./GOVERNANCE.md). --- ## Community forks 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: - [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.