CrossVi is an open-source, multilingual e-reader firmware for the ESP32-C3-based Xteink X3 and X4. It is independently developed from CrossPoint Reader, with an emphasis on reliable reading, Vietnamese typography, safe SD-card data, and features that fit the devices' limited resources.
Project status: CrossVi is a development preview. Automated host tests, firmware builds, static analysis, and X3/X4 simulator checks are available, but a stable release still requires validation on physical X3 and X4 devices.
- EPUB 2/3, plain-text TXT/Markdown, XTC/XTCH, and BMP support.
- Per-book typography, EPUB render modes, EPUB Safe Mode, bookmarks, clippings, StarDict lookup, reading statistics, focus reading, and automatic page turns.
- Built-in Vietnamese-capable Noto Serif and Noto Sans fonts, plus validated
.cpfontfamilies loaded from the SD card. - File browser, recent books, Web UI transfers, WebDAV, Calibre Wireless, OPDS, KOReader progress sync, and OTA updates.
- Themes designed for the 4-inch display, configurable controls, sleep screens, screenshots, and tilt page turns on X3.
- 30 interface languages, including a complete Vietnamese interface for CrossVi-specific features.
- Experimental Nearby Sync for confirmed position or statistics exchange between two nearby CrossVi readers. Nearby traffic is not encrypted.
CrossVi keeps the reader focused: it does not aim to add web browsing, media playback, games, or other background-heavy applications.
| Device | Status | Notes |
|---|---|---|
| Xteink X3 | Supported target | ESP32-C3; tilt page turn available |
| Xteink X4 | Supported target | ESP32-C3 |
| Format | Support |
|---|---|
.epub |
Reflowable EPUB 2/3 reader |
.txt, .md |
Plain-text reader; Markdown is currently treated as text |
.xtc, .xtch |
Tested uncompressed v1.0 fixed-layout subset using 480×800 pages |
.bmp |
Image viewer and sleep-screen images |
XTC/XTCH pages display 1:1 on X4 and are fitted and centred on X3. They do not provide EPUB typography, dictionary selection, clippings, or KOReader position sync. See the XTC/XTCH format contract.
The built-in Noto Serif and Noto Sans reader families provide Regular, Bold, Italic, and Bold Italic faces at 12, 14, 16, and 18 pt.
Compatible SD-card .cpfont families can additionally provide 20, 22, 24, 26,
and 28 pt. The size picker only shows sizes available for the selected family,
and the reader loads one physical .cpfont file at a time. Large font files are
not bundled into the firmware, so a fresh installation still exposes only the
built-in sizes until a compatible SD font family is installed.
To create or install a font family:
- Open the CrossPoint font builder, or use
lib/EpdFont/scripts/fontconvert_sdcard.pylocally. - Convert TTF/OTF sources to
.cpfont; TTF/OTF files are not parsed on-device. - Copy the generated family to
/fonts/FamilyName/or/.fonts/FamilyName/on the SD card. - Select it under Settings → Reader → Font Family.
Use the vietnamese-reading preset when preparing Vietnamese fonts. It checks
NFC letters, required NFD combining marks, punctuation, and every emitted style.
The source font's licence continues to apply to every generated .cpfont file.
Some devices sold by third parties have USB flashing locked. The public Xteink Unlocker currently supports CrossPoint and CrossInk as unlock payloads, not CrossVi. Do not use CrossVi as the unlock payload on a USB-locked device; doing so may leave the device without a supported recovery path.
CrossVi does not currently publish a hardware-validated stable release. If you
intentionally test a development build, back up the SD card first and use a
firmware.bin from a trusted build or build it locally.
- Wake the reader and connect it with a data-capable USB-C cable.
- Open the CrossPoint flash tools.
- Select X3 or X4, choose Custom .bin, and open CrossVi's
firmware.bin. - Continue only if the tool recognises the device and its Validate partition table step succeeds. Keep the reader connected until flashing completes.
Do not use a raw esptool write-flash 0x10000 firmware.bin command for a first
CrossVi installation. CrossVi uses two OTA application slots; writing only
ota_0 does not select that slot when otadata currently points at ota_1.
The browser tool validates the installed partition table, writes the inactive
application slot, and updates the boot selection. Command-line installation is
therefore intentionally not documented until the device partition table and
active slot have been inspected explicitly. Official CrossPoint firmware can
be restored through the same web flasher, subject to the same USB-access and
partition-validation requirements.
CrossVi retains CrossPoint-compatible working data under /.crosspoint where
supported. This directory contains both generated caches and important reader
data such as settings, positions, bookmarks, clippings, and statistics.
Do not delete the entire directory as routine troubleshooting. Use the firmware's cache-clear action first, and always back up the SD card before switching firmware or manually changing reader data. See file formats for the on-card layout.
- pioarduino, or VS Code with its extension
- Python 3.8 or newer
clang-format21 for formatting contributions- A data-capable USB-C cable for physical-device work
git clone --recursive https://github.com/tvhdc/crossvi.git
cd crossvi
pio runIf the repository was cloned without submodules:
git submodule update --init --recursiveRun the main contributor checks with:
./bin/clang-format-fix
pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
pio runThe simulator runs the real CrossVi interface and renderer without a physical reader:
python3 scripts/run_simulator.py x3
python3 scripts/run_simulator.py x4It validates desktop-visible behaviour, not e-paper ghosting, SD-card timing, radio behaviour, battery use, or peak memory on real hardware. See the simulator guide and hardware validation checklist.
Focused-reading contributions are welcome. Before starting a large change, open an Ideas discussion so work is not duplicated.
- Report reproducible bugs through GitHub Issues.
- Ask questions and propose features in GitHub Discussions.
- Read GOVERNANCE.md before contributing.
CrossVi is an independent fork of CrossPoint Reader. CrossPoint and its contributors remain the technical foundation of this project. Some reading-experience ideas were informed by CrossInk and independently adapted for CrossVi's resource and compatibility constraints.
The project is distributed under the MIT License while preserving upstream copyright and attribution. Font files retain their own licences. CrossVi is not affiliated with Xteink or any device manufacturer.