Skip to content

USER_GUIDE.md

Latest commit

 

History

History
795 lines (520 loc) · 49.7 KB

USER_GUIDE.md

File metadata and controls

795 lines (520 loc) · 49.7 KB
Raw

CrossVi User Guide

Welcome to the CrossVi firmware. This guide outlines the hardware controls, navigation, and reading features of the device.

1. Hardware Overview

The device utilises the standard buttons on the Xteink X4 (in the same layout as the manufacturer firmware, by default):

Button Layout

Location Buttons
Bottom Edge Back, Confirm, Left, Right
Right Side Power, Volume Up, Volume Down, Reset

Button layout can be customized in the Controls Settings.

Taking a Screenshot

When the Power Button and Volume Down button are pressed at the same time, it will take a screenshot and save it in the folder screenshots/.

Alternatively, while reading a book, press the Confirm button to open the reader menu and select Take screenshot.

2. Power & Startup

Power On / Off

To turn the device on or off, press and hold the Power button for approximately half a second. In the Controls Settings you can configure the power button to turn the device off with a short press instead of a long one.

To reboot the device (for example after a firmware update or if it's frozen), press and release the Reset button, and then quickly press and hold the Power button for a few seconds.

First Launch

Upon turning the device on for the first time, you will be placed on the Home screen.

Note

On subsequent restarts, the firmware will automatically reopen the last book you were reading.

Safe startup

If CrossVi crashes while loading a startup store, the next crash recovery skips that exact stage and opens a read-only safe-start notice instead of repeatedly overwriting or reloading the suspect data. Press Back or Confirm to continue to Home. CrossVi does not delete the skipped file.

To request the same protected startup manually, hold Volume Down + Power while powering on. This skips settings, resume state, recent books, network stores, and SD-card font discovery for that boot only. Volume Up + Power keeps its existing firmware-recovery priority.

3. Screens

3.1 Home Screen

The Home screen is the main entry point to the firmware. From here you can navigate to Reading Mode with the most recently read book, the Browse Files screen, the Recent Books screen, the File Transfer screen, or Settings.

3.2 Reading Mode

See Reading Mode below for more information.

3.3 Browse Files Screen

The Browse Files screen acts as a file and folder browser. The full path to the current directory is shown at the top of the screen. File extensions are displayed alongside each filename, and directories are shown with brackets (e.g. [folder-name]). Hidden directories (those beginning with .) are also visible.

  • Navigate List: Use Left (or Volume Up), or Right (or Volume Down) to move the selection cursor up and down through folders and books. You can also long-press these buttons to scroll a full page up or down.
  • Open Selection: Press Confirm to open a folder or start reading a selected book. Selecting a .bmp file will open the image viewer.
  • Delete Files or Folders: Hold and release Confirm to delete the selected file or folder. You will be given an option to either confirm or cancel. Multiple files can be selected for deletion in a single operation.
  • Rename or Move: Files can be renamed or moved to a different folder from within the browse screen.

3.4 Recent Books Screen

The Recent Books screen lists the most recently opened books in a chronological view, displaying title and author.

3.5 File Transfer Screen

The File Transfer screen allows you to upload and manage files on the device. When you enter the screen, choose Join a Network, Calibre Wireless, or Create Hotspot. The reader then starts the web server for the selected mode.

The same mode chooser also contains Nearby reading stats (Experimental). It exchanges a manually confirmed statistics snapshot directly with another nearby CrossVi reader. A received snapshot is stored separately and contributes to the Dashboard totals; it never overwrites the statistics recorded by this device.

See the web server docs for more information on how to connect to the web server and upload files.

The web interface also supports WebDAV, allowing you to mount the device as a network drive and manage files directly from your computer's file manager.

Download links for files already on the device are available in the web interface, so you can retrieve books or screenshots over Wi-Fi without connecting a cable.

A Wi-Fi signal strength indicator (dBm) is displayed on-screen during joined-network web server sessions.

Tip

Advanced users can also manage files programmatically or via the command line using curl. See the web server docs for details. [!TIP] If your EPUBs have compatibility issues, you can run the built-in EPUB Optimizer directly from the device to clean up and reprocess books for better rendering.

3.5.1 Calibre Wireless Transfers

CrossVi supports sending books from Calibre using the compatible upstream CrossPoint Reader device plugin.

Installing the Plugin in Calibre

If you don't already have the plugin installed:

  1. Head to https://github.com/crosspoint-reader/calibre-plugins/releases to download the latest version of the crosspoint_reader plugin.
  2. Download the zip file.
  3. Open Calibre → Preferences → Plugins → Load plugin from file → Select the zip file.
  4. Restart Calibre.

Configuring the CrossPoint Plugin in Calibre

  1. In Calibre select Preferences.
  2. In the Preferences dialog select Plugins.
  3. In Plugins search for "crosspoint".
  4. Click on "Customize plugin".
  5. Update the value for "Host" to match the IP for your device.
  6. Leave the other settings as they are.
  7. [optional] Modify the "Upload path" to point to a subfolder other than the root "/" folder. Enter this as a path relative to the root folder. Example: /mybooks
  8. Restart Calibre.
Image

Uploading Books

To upload a book using the CrossPoint plugin in Calibre:

  1. On the device: File Transfer -> Calibre Wireless, then join a network.
  2. Select one or more books.
  3. Right-click on that selection.
  4. Select "Send to Device" > "Send to main memory"

The CrossPoint plugin will connect to your device, create a folder for the book's author in the root folder (or the folder you configured for the plugin), then copy the book into that folder.

Image

Removing a Book

Books cannot be removed from your device through Calibre. Use the web interface instead.

3.6 Settings

The Settings screen allows you to configure the device's behavior. There are a few settings you can adjust:

3.6.1 Display

  • Sleep Screen: Which sleep screen to display when the device sleeps:

    • "Dark" (default) - The default dark CrossVi logo sleep screen
    • "Light" - The same default sleep screen, on a white background
    • "Custom" - Custom images from the SD card; see Sleep Screen below for more information
    • "Cover" - The book cover image (Note: this is experimental and may not work as expected)
    • "None" - A blank screen
    • "Cover + Custom" - The book cover image while actively reading, falls back to "Custom" behavior otherwise
    • "Quick resume" - The text of the last page read will be displayed on the sleep screen and a moon icon is shown on the edge of the screen. Waking up the device will return to the same page of the opened book. This is useful for quickly resuming reading without waiting for the device to fully wake up and load the book.

  • Sleep Screen Cover Mode: How to display the book cover when "Cover" sleep screen is selected:

    • "Fit" (default) - Scale the image down to fit centered on the screen, padding with white borders as necessary
    • "Crop" - Scale the image down and crop as necessary to try to fill the screen (Note: this is experimental and may not work as expected)

  • Sleep Screen Cover Filter: What filter will be applied to the book cover when "Cover" sleep screen is selected:

    • "None" (default) - The cover image will be converted to a grayscale image and displayed as it is
    • "Contrast" - The image will be displayed as a black & white image without grayscale conversion
    • "Inverted" - The image will be inverted as in white & black and will be displayed without grayscale conversion

  • Quick Resume on Timeout: Whether to enable the "Quick Resume" sleep screen when the device goes to sleep due to inactivity (System > Time to Sleep). This is useful for quickly resuming reading without waiting for the device to fully wake up and load the book. This overwrites the Sleep Screen Cover Mode when enabled.

  • Status Bar: Configure the status bar displayed while reading:

    • "None" - No status bar
    • "No Progress" - Show status bar without reading progress
    • "Full w/ Percentage" - Show status bar with book progress (as percentage)
    • "Full w/ Book Bar" - Show status bar with book progress (as bar)
    • "Book Bar Only" - Show book progress (as bar)
    • "Full w/ Chapter Bar" - Show status bar with chapter progress (as bar)

  • Hide Battery %: Configure where to suppress the battery percentage display in the status bar; the battery icon will still be shown:

    • "Never" (default) - Always show battery percentage
    • "In Reader" - Show battery percentage everywhere except in reading mode
    • "Always" - Always hide battery percentage

  • Refresh Frequency: Set how often the screen does a full refresh while reading to reduce ghosting; options are every 1, 5, 10, 15, or 30 pages.

  • Device Name: Set the short name shown at the top-left of the CrossVi Home screen. Long names are truncated to leave room for the battery; leave it empty to show the detected Xteink X3 or Xteink X4 model name. The device keyboard uses its existing basic Latin layout; use Web Settings when you want to enter Vietnamese diacritics or other Unicode characters.

  • Sunlight Fading Fix: Configure whether to enable a software-fix for the issue where white X4 models may fade when used in direct sunlight:

    • "OFF" (default) - Disable the fix
    • "ON" - Enable the fix

Note

A battery charging indicator is shown on the battery icon whenever the device is actively charging.

3.6.2 Reader

  • Reader Font Family: Choose the font used for reading:

    • "Noto Serif" (default) - Google's serif font
    • "Noto Sans" - Google's sans-serif font

  • Reader Font Size: Adjust the text size for reading; options are "Small", "Medium" (default), "Large", or "X Large".

  • Reader Line Spacing: Adjust the spacing between lines; options are "Tight", "Normal" (default), or "Wide".

  • Reader Screen Margin: Controls the screen margins in Reading Mode between 5 and 40 pixels in 5-pixel increments.

  • Reader Paragraph Alignment: Set the alignment of paragraphs; options are "Justified" (default), "Left", "Center", or "Right".

  • Daily Reading Goal: Set an optional daily target from 5 to 120 minutes, in five-minute steps. Choose "Off" to disable the target. The CrossVi Home theme compares today's verified reading time with this goal and opens full device statistics when its summary card is selected.

  • Embedded Style: Whether to use the EPUB file's embedded HTML and CSS stylisation and formatting; options are "ON" or "OFF".

  • Hyphenation: Whether to hyphenate text in Reading Mode; options are "ON" or "OFF".

  • Reading Orientation: Set the screen orientation for reading EPUB files:

    • "Portrait" (default) - Standard portrait orientation
    • "Landscape CW" - Landscape, rotated clockwise
    • "Inverted" - Portrait, upside down
    • "Landscape CCW" - Landscape, rotated counter-clockwise

  • Extra Paragraph Spacing: Set how to handle paragraph breaks:

    • "ON" - Vertical space will be added between paragraphs in Reading Mode
    • "OFF" - Paragraphs will not have vertical space added, but will have first-line indentation

  • Force Paragraph Indent: Give ordinary EPUB paragraphs a first-line indent even when extra paragraph spacing is enabled. An explicit publisher indent is preserved, and headings or centered/right-aligned blocks are not forced into paragraph indentation.

  • Dictionary: Select the StarDict dictionary used for word lookups while reading, or "None" to disable lookups. (Only shown when at least one dictionary folder exists under /dictionaries/ on the SD card — see docs/dictionary.md for setup and usage.)

  • Text Anti-Aliasing: Whether to show smooth grey edges (anti-aliasing) on text in reading mode. Note this slows down page turns slightly.

  • Images: Whether to display embedded images (JPG/PNG) found in EPUB files; options are "ON" (default) or "OFF".

  • Focus Reading: Bolds the first part of each word to create visual fixation points, similar to Bionic Reading. This can help improve reading speed and focus; options are "ON" or "OFF" (default).

3.6.3 Controls

  • Remap Front Buttons: A menu for customising the function of each bottom edge button.

  • Side Button Layout (reader): Swap the order of the up and down volume buttons from "Prev/Next" (default) to "Next/Prev". You can also disable them entirely. This change is only in effect when reading.

  • Long-press Chapter Skip: Set whether long-pressing page turn buttons skips to the next/previous chapter:

    • "Chapter Skip" (default) - Long-pressing skips to next/previous chapter
    • "Page Scroll" - Long-pressing scrolls a page up/down

  • Long-press Menu: Selects the function bound to holding the menu button (Confirm) while reading an EPUB. Cycles through the available functions each time the setting is selected — additional functions may be added in future releases, so this is not a binary on/off toggle. A short press of Confirm always opens the reader menu as normal:

    • "Bookmark" (default) - Hold Confirm (~0.4 second) to drop a bookmark at the current page.
    • "KOSync" - Hold Confirm (~1 second) to launch KOReader sync directly.
    • "Dictionary" - Hold Confirm (~0.4 second) to start dictionary word selection on the current page (see docs/dictionary.md).
    • "Disabled" - Long-press is ignored; only short-press opens the reader menu.

  • Short Power Button Click: Controls the effect of a short click of the power button:

    • "Ignore" (default) - Require a long press to turn off the device
    • "Sleep" - A short press puts the device into sleep mode
    • "Page Turn" - A short press in reading mode turns to the next page; a long press turns the device off
    • "Footnotes" - A short press in reading mode opens the footnotes submenu; if only one footnote is present on the page, the referenced page is opened directly. The short press on the power button can be used to select the footnote in the submenu, and to go back to the original page after finish reading the footnote (like the back button).
    • "Refresh" - A short press triggers a manual full-screen refresh, useful for clearing ghosting

  • Quick-return from footnotes: Toggles on and off the quick return functionality from the footnotes. When the functionality it's active, a short press of the power button will act as the back button from the footnotes page.

3.6.4 System

  • Time to Sleep: Set the duration of inactivity before the device automatically goes to sleep; options are 1, 3, 5, 10 (default), 15 or 30 minutes.

  • Wi-Fi Networks: Connect to Wi-Fi networks for file transfers and firmware updates.

  • KOReader Sync: Options for setting up KOReader for syncing book progress. Smart sync is the default for new configurations and auto-resolves simple push/pull decisions. Existing credential files retain Ask every time when migrated; you can switch Sync Behavior at any time if you prefer manual confirmation.

  • OPDS Servers: Manage one or more OPDS (Open Publication Distribution System) libraries for browsing and downloading books. See OPDS Servers (Multiple Libraries) below.

  • Clear Reading Cache: Clear the internal SD card cache.

  • Check for updates: Check for CrossVi firmware updates over Wi-Fi. Firmware can also be updated without a USB connection by placing a firmware.bin file on the SD card.

  • Language: Set the UI language. CrossVi supports 30 languages: English, Arabic, Belarusian, Bosnian, Catalan, Valencian, Czech, Danish, Dutch, Finnish, French, German, Hebrew, Hungarian, Italian, Kazakh, Lithuanian, Norwegian, Polish, Portuguese (Brazil), Portuguese (Portugal), Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Turkish, Ukrainian, and Vietnamese.

  • Manage Fonts: Browse, download, and manage custom font families installed from the SD card. See Custom Fonts (SD Card) for more information.

3.6.5 OPDS Servers (Multiple Libraries)

CrossVi supports saving multiple OPDS servers and switching between them when browsing catalogs.

  1. Open Settings -> System -> OPDS Servers.

  2. Select Add Server to create a new entry, or select an existing server to edit it.

  3. Configure these fields:

    • Server Name: Optional display name (for example, "Home Calibre" or "Public Catalog").

    • OPDS Server URL: Full catalog root URL (for Calibre Content Server, usually ends with /opds).

    • Username / Password: Optional credentials for authenticated servers.

  4. Use Delete Server inside a server entry to remove it.

Behavior notes:

  • You can store up to 8 OPDS servers.
  • OPDS authentication supports HTTP Basic auth. If you use Calibre Content Server with authentication enabled, set it to Basic (not Digest).

You can also manage OPDS servers from the web interface while in File Transfer mode:

  1. Connect to the device web UI.
  2. Open http://<device-ip>/settings.
  3. Use the OPDS Servers card to add, edit, or delete entries.

For web-based Wi-Fi network management, see Web Settings (Wi-Fi + OPDS).

3.6.6 Web Settings (Wi-Fi + OPDS)

While in File Transfer mode, the web settings page includes management cards for both Wi-Fi Networks and OPDS Servers.

  1. On device: open File Transfer and connect through Join a Network or Create Hotspot.
  2. In a browser, open http://<device-ip>/settings or http://crosspoint.local. CrossVi retains the legacy crosspoint.local mDNS hostname for compatibility with existing clients.
  3. In Wi-Fi Networks, add, edit, or delete saved network entries (SSID + optional password).
  4. In OPDS Servers, add, edit, or delete OPDS catalogs.

Behavior notes:

  • Passwords are never shown back in the web UI after saving.
  • Leaving Password blank while editing keeps the existing saved password unchanged.
  • The web UI can save hidden-network SSIDs, but connecting to hidden networks still depends on the device-side Wi-Fi connection flow.

3.6.7 KOReader Sync Quick Setup

CrossVi can sync reading progress with KOReader-compatible sync servers. It also interoperates with KOReader apps/devices when they use the same server and credentials.

Option A: CrossPoint Sync Server (sync.crosspointreader.com, default)

When Sync Server URL is left empty, CrossVi uses the free upstream CrossPoint Sync Server at https://sync.crosspointreader.com. It speaks the standard KOReader sync protocol (so KOReader apps can use it too) and additionally stores an exact spine/page position for lossless compatible-device sync.

  1. On each CrossVi device:

    • Go to Settings -> System -> KOReader Sync.

    • Set Username and Password (enter the plain password; CrossVi computes MD5 internally, and use the same values on all devices).

    • Leave Sync Server URL empty (or set it to https://sync.crosspointreader.com).

    • On the first device, run Sign Up once to create the account directly from the device. On every other device, just run Authenticate.

Accounts are per server. Existing sync.koreader.rocks credentials do not exist on the CrossPoint server; either sign up again with the same username/password or use Option B to keep using the legacy server.

Option B: Legacy Public KOReader Server (sync.koreader.rocks)

Use this if you already sync KOReader devices against the official public server.

  1. On each CrossVi device:

    • Go to Settings -> System -> KOReader Sync.

    • Set Sync Server URL to https://sync.koreader.rocks (required; an empty URL now points at the CrossPoint server instead).

    • Set Username and Password to your existing KOReader Sync credentials.

    • Run Authenticate.

  2. If you do not have an account yet, run Sign Up on the device, or register once with curl:

USERNAME="user"
PASSWORD="pass"
PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')"

curl -i "https://sync.koreader.rocks/users/create" \
  -H "Accept: application/vnd.koreader.v1+json" \
  -H "Content-Type: application/json" \
  --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"

When this returns HTTP 402 with {"code":2002,"message":"Username is already registered."}, pick a different username or use that existing account.

Option C: Self-Hosted Server (Docker Compose)
  1. Start a sync server:
mkdir -p kosync-quickstart
cd kosync-quickstart

cat > compose.yaml <<'YAML'
services:
  kosync:
    image: koreader/kosync:latest
    ports:
      - "7200:7200"
      - "17200:17200"
    volumes:
      - ./data/redis:/var/lib/redis
    environment:
      - ENABLE_USER_REGISTRATION=true
    restart: unless-stopped
YAML

# Docker
docker compose up -d

# Podman (alternative)
podman compose up -d

Note

ENABLE_USER_REGISTRATION=true is convenient for first setup. After creating your users, set it to false (or remove it) to avoid unexpected registrations.

  1. Verify the server:
curl -H "Accept: application/vnd.koreader.v1+json" "http://<server-ip>:17200/healthcheck"
# Expected: {"state":"OK"}
  1. Register a user once. CrossVi authenticates against KOReader Sync (koreader/kosync) using an MD5 key, so register using the MD5 of your password:

Warning

Sending a reusable MD5-derived password over plain HTTP is insecure. Create unique sync-only credentials and do not reuse main account passwords. Prefer https://<server-ip>:7200 whenever traffic leaves a fully trusted LAN or when using untrusted networks. Use curl -k only for self-signed certificate testing.

USERNAME="user"
PASSWORD="pass"
PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')"

curl -i "http://<server-ip>:17200/users/create" \
  -H "Accept: application/vnd.koreader.v1+json" \
  -H "Content-Type: application/json" \
  --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"

If this returns HTTP 402 with {"code":2002,"message":"Username is already registered."}, the account already exists.

  1. On each CrossVi device:

    • Go to Settings -> System -> KOReader Sync.

    • Set Username and Password (enter the plain password; CrossVi computes MD5 internally, and use the same values on all devices).

    • Set Sync Server URL to http://<server-ip>:17200.

    • Run Authenticate.

If you use the HTTPS listener, use https://<server-ip>:7200 (curl -k only for self-signed certificate testing).

Syncing While Reading

Once any of the options above is set up, press Confirm while reading to open the reader menu, then select Sync Progress. Alternatively, set Settings -> Controls -> Long-press Menu to KOSync and hold Confirm to launch sync directly.

  • With Sync Behavior set to Ask every time, choose Apply Remote to jump to remote progress or Upload Local to push current progress.
  • With Sync Behavior set to Smart sync, CrossVi auto-resolves simple cases: upload when no remote progress exists, confirm and leave both unchanged when local and remote progress are already synchronized, upload when local progress is further ahead, or apply remote when remote progress is further ahead.

3.7 Sleep Screen

The Sleep Screen setting controls what is displayed when the device goes to sleep:

Mode Behavior
Dark (default) The CrossVi logo on a dark background.
Light The CrossVi logo on a white background.
Custom A custom image from the SD card (see below). Falls back to Dark if no custom image is found.
Cover The cover of the currently open book. Falls back to Dark if no book is open.
Cover + Custom The cover of the currently open book, shown only while actively reading. Falls back to Custom behavior when not reading.
None A blank screen.

Cover settings

When using Cover or Cover + Custom, two additional settings apply:

  • Sleep Screen Cover Mode: Fit (scale to fit, white borders) or Crop (scale and crop to fill the screen).
  • Sleep Screen Cover Filter: None (grayscale), Contrast (black & white), or Inverted (inverted black & white).

Custom images

To use custom sleep images, set the sleep screen mode to Custom or Cover + Custom, then place images on the SD card:

  • Multiple Images (recommended): Create a .sleep directory in the root of the SD card and place any number of .bmp images inside. One will be randomly selected each time the device sleeps. (A directory named sleep is also accepted as a fallback.)
  • Single Image: Place a file named sleep.bmp in the root directory. This is used as a fallback if no valid images are found in the .sleep/sleep directory.

Tip

For best results:

  • Use uncompressed BMP files with 24-bit color depth
  • X4: Use a resolution of 480x800 pixels to match the device's screen resolution.
  • X3: Use a resolution of 528x792 pixels to match the device's screen resolution.

Tip

You can set an image as the sleep screen cover directly from the BMP image viewer in the Browse Files screen.

3.8 Custom Fonts (SD Card)

CrossVi supports loading additional fonts from the SD card, extending beyond the two built-in families (Noto Serif, Noto Sans). Custom fonts can include extended Unicode coverage, enabling CJK (Chinese, Japanese, Korean) and other scripts.

There are three ways to install fonts:

  1. Download from device (recommended): Go to Settings -> System -> Manage Fonts, browse the available font families, and select one to download over Wi-Fi.
  2. Upload via web interface: While in File Transfer mode, open the web UI in a browser and navigate to the Fonts tab to upload .cpfont files.
  3. Manual SD card copy: Download font files from the crosspoint-fonts repository and copy them to /.fonts/ (preferred) or /fonts/ on your SD card.

Once installed, custom fonts appear in Settings → Reader → Font Family alongside the built-in fonts.

See docs/sd-card-fonts.md for full installation details and SD card folder structure.

4. Reading Mode

Once you have opened a book, the button layout changes to facilitate reading.

Page Turning

Action Buttons
Previous Page Press Left or Volume Up
Next Page Press Right or Volume Down

The role of the volume (side) buttons can be swapped in the Controls Settings.

If the Short Power Button Click setting is set to "Page Turn", you can also turn to the next page by briefly pressing the Power button.

Chapter Navigation

  • Next Chapter: Press and hold the Right (or Volume Down) button briefly, then release.
  • Previous Chapter: Press and hold the Left (or Volume Up) button briefly, then release.

This feature can be disabled in the Controls Settings to help avoid changing chapters by mistake.

Auto Page Turn

Auto Page Turn automatically advances pages at a set interval, useful for hands-free reading. This feature can be enabled and configured from the Reader Menu while reading an EPUB.

Tilt Page Turn (X3 only)

On the Xteink X3, the gyroscope can be used to turn pages by tilting the device. This feature is available in the Controls settings.

Footnote Navigation

When reading an EPUB that contains footnotes, you can navigate to the footnote text by selecting the footnote reference in the book. From the footnote, you can return to your original reading position.

If the device goes to sleep or you close the book while viewing a footnote, the book reopens to your original reading position, not the footnote.

System Navigation

  • Return to Home: Press the Back button to close the book and return to the Home screen.
  • Return to Browse Files: Press and hold the Back button to close the book and return to the Browse Files screen.
  • Reader Menu: While reading an EPUB or TXT/Markdown book, press Confirm to open the Reader Menu. The plain-text menu shows only functions that have a reliable text equivalent; chapter navigation, footnotes and EPUB sync are intentionally omitted.
  • Long-press Confirm (EPUB, configurable): While reading an EPUB, holding Confirm runs the function chosen by the Long-press Menu setting in Controls Settings — "Bookmark" (default) drops a bookmark, "KOSync" launches KOReader Sync, "Dictionary" starts a word lookup, "Disabled" does nothing. In TXT/Markdown, use the corresponding explicit Reader Menu item so a long press cannot conflict with opening that menu.

Supported Languages

CrossVi renders text using the following Unicode character blocks, enabling support for a wide range of languages:

  • Latin Script (Basic, Supplement, Extended-A/B): Covers English, German, French, Spanish, Portuguese, Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Hungarian, Romanian, Slovak, Slovenian, Turkish, Catalan, and others.
  • Cyrillic Script (Standard and Extended): Covers Russian, Ukrainian, Belarusian, Bulgarian, Serbian, Macedonian, Kazakh, Kyrgyz, Mongolian, and others.
  • Vietnamese: Supported via extended Latin glyph coverage in the built-in reader fonts.

What is not supported with built-in reader fonts: Chinese, Japanese, Korean, Arabic, Greek, Hebrew, and Farsi. However, CJK, Hebrew, Greek, and other extended scripts can be enabled by installing custom SD card fonts — see Custom Fonts (SD Card).

XTC/XTCH fixed-layout books

XTC and XTCH store pages that have already been rendered as images. CrossVi supports uncompressed version 1.0 files whose portrait pages are exactly 480×800 pixels: .xtc uses one-bit XTG pages and .xtch uses four-level XTH grayscale pages. Metadata, chapters, progress, reading statistics, recent books, cover thumbnails and sleep covers are supported. Press Confirm while reading to open the chapter list when the file provides one; hold Confirm to open the current book statistics. When a file has no chapters, a short Confirm opens statistics directly.

X4 shows these pages at native 1:1 resolution. X3 fits the entire page into its 528×792 portrait screen, preserves the aspect ratio, centers it and leaves a small letterbox instead of cropping the last rows. A top or bottom reader status bar is an overlay; it does not change the source-page mapping.

Because the content is fixed, EPUB-only actions do not apply: changing font, font size or CSS, selecting words for a dictionary, clipping, per-book typography, and KOReader position sync are unavailable. An unsupported version, compressed page, wrong page size, mixed XTG/XTH payload or damaged/truncated file is rejected rather than opened approximately.

To create a compatible file, use the EPUB to XTC Converter and export uncompressed version 1.0 at the Xteink X4 / 480×800 portrait preset. Use that same output for X3; CrossVi performs the safe fit at display time. The repository does not bundle the converter.

5. Reader Menu

Press Confirm while reading an EPUB or TXT/Markdown file to open the Reader Menu. TXT/Markdown supports bookmarks, dictionary lookup, clipping creation and browsing, per-book font/size/line-spacing/margin/alignment/orientation/anti-aliasing settings, reading statistics, auto turn, go-to-percent, screenshots and safe cache clearing. Items that require EPUB structure—chapter selection, footnotes, QR chapter text, KOReader sync and Nearby position sync—are hidden instead of appearing as non-working controls.

Available options include:

  • Select Chapter – Open the table of contents to jump to a specific chapter (see Chapter Selection below).
  • Footnotes – Navigate to the footnotes for the current section (only shown in books that contain footnotes).
  • Look Up – Select a word on the current page and show its dictionary definition (see docs/dictionary.md). Requires a dictionary to be selected in Settings → Reader → Dictionary.
  • Book settings – Keep reader settings for this EPUB separate from the device-wide defaults.
  • Reading statistics – Show statistics for the current EPUB and the combined device totals.
  • Create clipping – Select and save a passage from the current page or continue through adjacent pages in the same chapter.
  • Clippings – Browse, open, jump to, or delete passages saved for this EPUB.
  • Reading Orientation – Cycle through screen orientations without leaving the reader.
  • Auto Turn (5–120 seconds) – Choose the delay between automatic page turns for hands-free reading.
  • Go to % – Jump to a specific position in the book by percentage.
  • Take screenshot – Save a screenshot of the current page to the screenshots/ folder.
  • Show page as QR – Display a QR code encoding the current reading position.
  • Go Home – Close the book and return to the Home screen.
  • Sync Progress – Push or pull reading progress with a KOReader sync server (see KOReader Sync Quick Setup).
  • Nearby position (Experimental) – Exchange the current position with another nearby CrossVi reader that has the exact same complete EPUB file.
  • Delete Book Cache – Rebuild generated layout/index data for the current book. Reading position, per-book settings, statistics, and clippings are preserved.

Press Back at any time to close the menu and return to your current page.

5.1 Chapter Selection

Accessible by selecting Chapters from the Reader Menu.

  1. Use Left (or Volume Up), or Right (or Volume Down) to highlight the desired chapter.
  2. Press Confirm to jump to that chapter.
  3. Alternatively, press Back to cancel and return to your current page.

5.2 Bookmarks

Bookmarks can be created to quickly save and restore your place in a book.

To create an EPUB bookmark, hold Confirm for about half a second, or use the explicit bookmark item in the Reader Menu. For TXT/Markdown, open the Reader Menu and choose Bookmark this page. The label changes to Remove bookmark from this page when the displayed text page is already bookmarked.

To open bookmarks, press Confirm while inside a book. Then navigate to the Bookmarks menu. Bookmarks can be opened by navigating to them and pressing Confirm, which will redirect you to that place in the book. You can delete bookmarks by holding Confirm for about 0.7 seconds, and then pressing Confirm again to confirm deletion, or Back to cancel.

Bookmarks are stored in the .crosspoint/bookmarks folder in the JSON format.

5.3 Per-book settings

Open Book settings from an EPUB's Reader Menu and enable Use settings for this book. Changes made on this screen apply only to that EPUB. Turning the option off restores the device-wide Reader defaults while keeping the custom profile available in case you enable it again. Reset removes the book-specific profile.

The profile includes typography, margins, paragraph layout, orientation, image/text rendering options, and the book's auto-page-turn rate. EPUB rendering is independent of the typography toggle and offers three bounded choices:

  • Balanced (default) applies the supported publisher styles without additional descendant-selector work.
  • Full also applies a bounded set of two-part descendant CSS selectors for books that depend on them.
  • Light keeps the text/content structure but drops publisher margins, padding, image dimensions, text indents and horizontal rules that commonly produce fragile layouts.

All three modes flatten complex tables into a readable sequence because the small fixed screen cannot reproduce arbitrary desktop table layout safely. Safe Mode is also per-book: it uses the Light policy with embedded CSS disabled. CrossVi offers it only after an explicit out-of-memory failure, asks before changing anything, and saves it only after a page renders successfully. You can disable it again in Book settings. CrossVi restores the global settings whenever you leave the EPUB, including sleep and sync paths, so a profile cannot leak into another book.

5.4 Reading statistics

Statistics are recorded for EPUB, TXT/Markdown, XTC and XTCH reading. Timing starts only after a page has rendered successfully and stops when you open a menu, leave the reader, or the visible interval becomes idle. Very short opens are filtered out: at least 10 active seconds are needed to save duration, and at least 60 active seconds are needed to count a session.

Open Reading statistics from the EPUB or TXT/Markdown Reader Menu. Press Confirm directly while reading an XTC/XTCH file without chapters; for XTC/XTCH files with chapters, hold Confirm so a short press can continue to open the chapter list. Home opens on This device; an in-reader shortcut opens on This book. A damaged or unsupported record is not displayed as plausible zero data.

For TXT/Markdown, page turns and progress are tracked, but the progress label is estimated from the current byte position. CrossVi marks average-page pace and estimated finish time as Not applicable because changing the font, margins, or orientation changes the number of rendered pages.

Time-of-day, day-of-week, and reading-streak views require a valid device date and time. Total active time and page-turn counts still work when the clock is unavailable. Nearby statistics are additive display snapshots; they do not modify local counters.

On This book, press Confirm to edit the stored start timestamp and, for a completed book, the finish timestamp. The editor validates calendar dates and refuses a finish earlier than the start. On This device, press Confirm and choose Reading calendar to browse the retained 730-day local history by month. A filled marker means reading was recorded, an outlined cell is today, and a dash means that older date falls outside retained history; synced peer snapshots are not mixed into this calendar. An invalid clock or legacy totals without dated history are shown as unavailable rather than as empty days.

When This device was opened from Home, the same Confirm menu also offers backup and restore for the local device aggregate. Restore requires confirmation and does not include per-book records, dictionary history, or Nearby snapshots. The verified backup is stored at /.crosspoint/stats_backups/device_stats_v1.bin; publication and restore use the same CRC/version checks and recoverable write rules as the live statistics store.

5.5 Clippings

Choose Create clipping, move the cursor to the first word, press Confirm, move to the last word, and press Confirm again. At the end of a page, you may continue through adjacent rendered pages in the same chapter. A draft is limited to 256 words and 512 bytes of UTF-8 text; nothing is saved until final confirmation. Up to 64 passages are stored for each book.

Before a draft continues onto another page, press Back once to remove its first selection point and start again; press Back again to leave without saving. After a draft has continued onto another page, Back leaves and discards the whole unfinished draft.

Open Clippings to read saved text. Press Confirm from a clipping's detail screen to return to its location. Hold Confirm and complete the two-step prompt to delete it. Clippings on Home groups passages from every book and can export them to a new My Clippings.txt-style text file without modifying the library.

Single-page clippings are underlined only when saved pagination still matches exactly. Multi-page clippings remain readable and return to their exact starting location, but are not yet drawn as inline underlines. After font, margin, orientation, or layout changes, saved text remains available and CrossVi does not guess where to draw a highlight.

5.6 Nearby position sync

On both readers, open the same complete EPUB and select Nearby position (Experimental). Choose Send on the reader whose position should win and Receive on the other reader; roles stay fixed for the session. Start the radio manually, compare the four-digit code shown on both devices, and continue only if it matches. The receiving reader previews and explicitly applies the incoming position; it never sends its old position back automatically.

The EPUB is hashed from the complete file, not matched by filename. A different edition or modified copy is rejected. The pairing code and peer/session binding prevent accidental cross-talk, but Nearby Sync traffic is not encrypted and is not designed to resist a malicious nearby device. Use it only with someone you trust.

CrossVi applies a received position only when it can resolve the sender's paragraph anchor against a finalized chapter cache built with the current per-book layout. If that exact source-based mapping is unavailable, it asks you to open/build the target chapter first instead of scaling or copying an approximate page number.

6. Current Limitations & Roadmap

Please note that this firmware is currently in active development. The following features are not yet supported but are planned for future updates:

  • Cover Images: Large cover images embedded into EPUB require several seconds (~10s for ~2000 pixel tall image) to convert for sleep screen and home screen thumbnail. Consider optimizing the EPUB with e.g. https://github.com/bigbag/epub-to-xtc-converter to speed this up.
  • Unsupported Image Formats: Most JPG and PNG images in EPUBs render correctly. GIFs and progressive JPEGs are not supported and will fall back to an [Image] placeholder.
  • Hardware validation: Core codecs, storage-recovery paths, layout mapping, and Nearby protocol state machines have automated host tests, and the complete firmware is build-checked. End-to-end UI, ESP-NOW radio, e-paper refresh, power-loss behavior, and real memory margins still require validation on physical X3 and X4 hardware before a stable release.

7. Troubleshooting Issues & Escaping Bootloop

If an issue or crash is encountered while using CrossVi, feel free to raise an issue ticket and attach the logs.

Crash reports on SD card: After a crash, CrossVi automatically saves a crash report to the SD card (no USB connection needed). Check the root of the SD card for a crash log file and include it with any bug report.

Serial monitor logs: For more detailed debugging, connect the device to a computer and run the custom debugging monitor script (requires Python 3 with pyserial, colorama, and matplotlib; install via pip3 install pyserial colorama matplotlib):

python3 scripts/debugging_monitor.py

The script auto-detects the serial port. You can also specify one explicitly:

python3 scripts/debugging_monitor.py /dev/ttyACM0        # Linux
python3 scripts/debugging_monitor.py /dev/tty.usbmodem1  # macOS
python3 scripts/debugging_monitor.py COM7                # Windows

Features:

  • Color-coded log output by category (errors, memory, display, EPUB parsing, etc.)
  • Live memory usage graph (free RAM, total RAM, max contiguous allocation) updated every second
  • Interactive command prompt — type a command and press Enter to send it to the device
  • Screenshot capture — saves the current display to screenshot.bmp when triggered by the device

Options:

Option Description
--baud RATE Baud rate (default: 115200)
--filter KEYWORD Show only lines containing the keyword (case-insensitive)
--suppress KEYWORD Hide lines containing the keyword (case-insensitive)

Examples:

# Show only memory-related log lines
python3 scripts/debugging_monitor.py --filter MEM

# Hide noisy SD card log lines
python3 scripts/debugging_monitor.py --suppress "[SD]"

Press Ctrl-C or close the graph window to exit.

If the device is stuck in a bootloop, press and release the Reset button. Then, press and hold on to the configured Back button and the Power Button to boot to the Home Screen.

For a broken book layout, first use Delete Book Cache for that book. This preserves its reading position, per-book profile, statistics, and clippings. If the UI is unavailable, back up the SD card and move only the matching /.crosspoint/epub_<path-hash>/sections/ directory aside before retrying.

Do not delete the whole .crosspoint directory as a normal troubleshooting step. It also contains device settings, resume state, bookmarks, clippings, and reading statistics. Removing it is a full reader-data reset; make a complete backup first if that is explicitly what you intend.