A fork of https://github.com/crosspoint-reader/crosspoint-reader
1# CrossPoint User Guide
2
3Welcome to the **CrossPoint** firmware. This guide outlines the hardware controls, navigation, and reading features of the device.
4
5- [CrossPoint User Guide](#crosspoint-user-guide)
6 - [1. Hardware Overview](#1-hardware-overview)
7 - [Button Layout](#button-layout)
8 - [2. Power \& Startup](#2-power--startup)
9 - [Power On / Off](#power-on--off)
10 - [First Launch](#first-launch)
11 - [3. Screens](#3-screens)
12 - [3.1 Home Screen](#31-home-screen)
13 - [3.2 Reading Mode](#32-reading-mode)
14 - [3.3 Browse Files Screen](#33-browse-files-screen)
15 - [3.4 Recent Books Screen](#34-recent-books-screen)
16 - [3.5 File Transfer Screen](#35-file-transfer-screen)
17 - [3.5.1 Calibre Wireless Transfers](#351-calibre-wireless-transfers)
18 - [3.6 Settings](#36-settings)
19 - [3.6.1 Display](#361-display)
20 - [3.6.2 Reader](#362-reader)
21 - [3.6.3 Controls](#363-controls)
22 - [3.6.4 System](#364-system)
23 - [3.6.5 OPDS Servers (Multiple Libraries)](#365-opds-servers-multiple-libraries)
24 - [3.6.6 KOReader Sync Quick Setup](#366-koreader-sync-quick-setup)
25 - [3.7 Sleep Screen](#37-sleep-screen)
26 - [4. Reading Mode](#4-reading-mode)
27 - [Page Turning](#page-turning)
28 - [Chapter Navigation](#chapter-navigation)
29 - [System Navigation](#system-navigation)
30 - [Supported Languages](#supported-languages)
31 - [5. Chapter Selection Screen](#5-chapter-selection-screen)
32 - [6. Current Limitations \& Roadmap](#6-current-limitations--roadmap)
33 - [7. Troubleshooting Issues \& Escaping Bootloop](#7-troubleshooting-issues--escaping-bootloop)
34
35
36## 1. Hardware Overview
37
38The device utilises the standard buttons on the Xteink X4 (in the same layout as the manufacturer firmware, by default):
39
40### Button Layout
41| Location | Buttons |
42| --------------- | ---------------------------------------------------- |
43| **Bottom Edge** | **Back**, **Confirm**, **Left**, **Right** |
44| **Right Side** | **Power**, **Volume Up**, **Volume Down**, **Reset** |
45
46Button layout can be customized in the **[Controls Settings](#363-controls)**.
47
48### Taking a Screenshot
49When 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/`.
50
51Alternatively, while reading a book, press the **Confirm** button to open the reader menu and select **Take screenshot**.
52
53---
54
55## 2. Power & Startup
56
57### Power On / Off
58
59To turn the device on or off, **press and hold the Power button for approximately half a second**.
60In the **[Controls Settings](#363-controls)** you can configure the power button to turn the device off with a short press instead of a long one.
61
62To 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.
63
64### First Launch
65
66Upon turning the device on for the first time, you will be placed on the **[Home](#31-home-screen)** screen.
67
68> [!NOTE]
69> On subsequent restarts, the firmware will automatically reopen the last book you were reading.
70
71---
72
73## 3. Screens
74
75### 3.1 Home Screen
76
77The Home screen is the main entry point to the firmware. From here you can navigate to **[Reading Mode](#4-reading-mode)** with the most recently read book, the **[Browse Files](#33-browse-files-screen)** screen, the **[Recent Books](#34-recent-books-screen)** screen, the **[File Transfer](#35-file-transfer-screen)** screen, or **[Settings](#36-settings)**.
78
79### 3.2 Reading Mode
80
81See [Reading Mode](#4-reading-mode) below for more information.
82
83### 3.3 Browse Files Screen
84
85The Browse Files screen acts as a file and folder browser.
86
87* **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.
88* **Open Selection:** Press **Confirm** to open a folder or read a selected book.
89* **Delete Files:** Hold and release **Confirm** to delete the selected file. You will be given an option to either confirm or cancel deletion. Folder deletion is not supported.
90
91### 3.4 Recent Books Screen
92
93The Recent Books screen lists the most recently opened books in a chronological view, displaying title and author.
94
95### 3.5 File Transfer Screen
96
97The File Transfer screen allows you to upload new e-books to the device. When you enter the screen, you'll be prompted with a WiFi selection dialog and then your X4 will start hosting a web server.
98
99See the [webserver docs](./docs/webserver.md) for more information on how to connect to the web server and upload files.
100
101> [!TIP]
102> Advanced users can also manage files programmatically or via the command line using `curl`. See the [webserver docs](./docs/webserver.md) for details.
103
104### 3.5.1 Calibre Wireless Transfers
105
106CrossPoint supports sending books from Calibre using the CrossPoint Reader device plugin.
107
1081. Install the plugin in Calibre:
109 - Head to https://github.com/crosspoint-reader/calibre-plugins/releases to download the latest version of the crosspoint_reader plugin.
110 - Download the zip file.
111 - Open Calibre → Preferences → Plugins → Load plugin from file → Select the zip file.
1122. On the device: File Transfer → Connect to Calibre → Join a network.
1133. Make sure your computer is on the same WiFi network.
1144. In Calibre, click "Send to device" to transfer books.
115
116### 3.6 Settings
117
118The Settings screen allows you to configure the device's behavior. There are a few settings you can adjust:
119
120#### 3.6.1 Display
121
122- **Sleep Screen**: Which sleep screen to display when the device sleeps:
123 - "Dark" (default) - The default dark Crosspoint logo sleep screen
124 - "Light" - The same default sleep screen, on a white background
125 - "Custom" - Custom images from the SD card; see [Sleep Screen](#37-sleep-screen) below for more information
126 - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
127 - "None" - A blank screen
128 - "Cover + Custom" - The book cover image, falls back to "Custom" behavior
129- **Sleep Screen Cover Mode**: How to display the book cover when "Cover" sleep screen is selected:
130 - "Fit" (default) - Scale the image down to fit centered on the screen, padding with white borders as necessary
131 - "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)
132- **Sleep Screen Cover Filter**: What filter will be applied to the book cover when "Cover" sleep screen is selected:
133 - "None" (default) - The cover image will be converted to a grayscale image and displayed as it is
134 - "Contrast" - The image will be displayed as a black & white image without grayscale conversion
135 - "Inverted" - The image will be inverted as in white & black and will be displayed without grayscale conversion
136- **Status Bar**: Configure the status bar displayed while reading:
137 - "None" - No status bar
138 - "No Progress" - Show status bar without reading progress
139 - "Full w/ Percentage" - Show status bar with book progress (as percentage)
140 - "Full w/ Book Bar" - Show status bar with book progress (as bar)
141 - "Book Bar Only" - Show book progress (as bar)
142 - "Full w/ Chapter Bar" - Show status bar with chapter progress (as bar)
143- **Hide Battery %**: Configure where to suppress the battery percentage display in the status bar; the battery icon will still be shown:
144 - "Never" (default) - Always show battery percentage
145 - "In Reader" - Show battery percentage everywhere except in reading mode
146 - "Always" - Always hide battery percentage
147- **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.
148
149- **UI Theme**: Set which UI theme to use:
150 - "Classic" - The original Crosspoint theme
151 - "Lyra" - The new theme for Crosspoint featuring rounded elements and menu icons
152 - "Lyra Extended" - Lyra, but displays 3 books instead of 1 on the **[Home Screen](#31-home-screen)**
153- **Sunlight Fading Fix**: Configure whether to enable a software-fix for the issue where white X4 models may fade when used in direct sunlight:
154 - "OFF" (default) - Disable the fix
155 - "ON" - Enable the fix
156
157#### 3.6.2 Reader
158- **Reader Font Family**: Choose the font used for reading:
159 - "Noto Serif" (default) - Google's serif font
160 - "Noto Sans" - Google's sans-serif font
161 - "Open Dyslexic" - Font designed for readers with dyslexia
162- **Reader Font Size**: Adjust the text size for reading; options are "Small", "Medium" (default), "Large", or "X Large".
163
164- **Reader Line Spacing**: Adjust the spacing between lines; options are "Tight", "Normal" (default), or "Wide".
165- **Reader Screen Margin**: Controls the screen margins in Reading Mode between 5 and 40 pixels in 5-pixel increments.
166- **Reader Paragraph Alignment**: Set the alignment of paragraphs; options are "Justified" (default), "Left", "Center", or "Right".
167- **Embedded Style**: Whether to use the EPUB file's embedded HTML and CSS stylisation and formatting; options are "ON" or "OFF".
168- **Hyphenation**: Whether to hyphenate text in Reading Mode; options are "ON" or "OFF".
169- **Reading Orientation**: Set the screen orientation for reading EPUB files:
170 - "Portrait" (default) - Standard portrait orientation
171 - "Landscape CW" - Landscape, rotated clockwise
172 - "Inverted" - Portrait, upside down
173 - "Landscape CCW" - Landscape, rotated counter-clockwise
174- **Extra Paragraph Spacing**: Set how to handle paragraph breaks:
175 - "ON" - Vertical space will be added between paragraphs in Reading Mode
176 - "OFF" - Paragraphs will not have vertical space added, but will have first-line indentation
177- **Text Anti-Aliasing**: Whether to show smooth grey edges (anti-aliasing) on text in reading mode. Note this slows down page turns slightly.
178
179#### 3.6.3 Controls
180
181- **Remap Front Buttons**: A menu for customising the function of each bottom edge button.
182- **Side Button Layout (reader)**: Swap the order of the up and down volume buttons from "Prev/Next" (default) to "Next/Prev". This change is only in effect when reading.
183
184- **Long-press Chapter Skip**: Set whether long-pressing page turn buttons skips to the next/previous chapter:
185 - "Chapter Skip" (default) - Long-pressing skips to next/previous chapter
186 - "Page Scroll" - Long-pressing scrolls a page up/down
187- **Short Power Button Click**: Controls the effect of a short click of the power button:
188 - "Ignore" (default) - Require a long press to turn off the device
189 - "Sleep" - A short press puts the device into sleep mode
190 - "Page Turn" - A short press in reading mode turns to the next page; a long press turns the device off
191
192#### 3.6.4 System
193
194- **Time to Sleep**: Set the duration of inactivity before the device automatically goes to sleep; options are 1, 5, 10 (default), 15 or 30 minutes.
195
196- **WiFi Networks**: Connect to WiFi networks for file transfers and firmware updates.
197- **KOReader Sync**: Options for setting up KOReader for syncing book progress.
198- **OPDS Servers**: Manage one or more OPDS libraries for browsing and downloading books. See [OPDS Servers (Multiple Libraries)](#365-opds-servers-multiple-libraries) below.
199- **Clear Reading Cache**: Clear the internal SD card cache.
200- **Check for updates**: Check for Crosspoint firmware updates over WiFi.
201- **Language**: Set the system language (see **[Supported Languages](#supported-languages)** for more information).
202
203#### 3.6.5 OPDS Servers (Multiple Libraries)
204
205CrossPoint supports saving multiple OPDS servers and switching between them when browsing catalogs.
206
2071. Open **Settings -> System -> OPDS Servers**.
2082. Select **Add Server** to create a new entry, or select an existing server to edit it.
2093. Configure these fields:
210 - **Server Name**: Optional display name (for example, "Home Calibre" or "Public Catalog").
211 - **OPDS Server URL**: Full catalog root URL (for Calibre Content Server, usually ends with `/opds`).
212 - **Username / Password**: Optional credentials for authenticated servers.
2134. Use **Delete Server** inside a server entry to remove it.
214
215Behavior notes:
216
217- You can store up to 8 OPDS servers.
218- OPDS authentication supports HTTP Basic auth. If you use Calibre Content Server with authentication enabled, set it to Basic (not Digest).
219
220You can also manage OPDS servers from the web interface while in File Transfer mode:
221
2221. Connect to the device web UI.
2232. Open `http://<device-ip>/settings`.
2243. Use the **OPDS Servers** card to add, edit, or delete entries.
225
226#### 3.6.6 KOReader Sync Quick Setup
227
228CrossPoint can sync reading progress with KOReader-compatible sync servers.
229It also interoperates with KOReader apps/devices when they use the same server and credentials.
230
231##### Option A: Free Public Server (`sync.koreader.rocks`)
232
2331. Register a user once (only if needed):
234
235```bash
236USERNAME="user"
237PASSWORD="pass"
238PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')"
239
240curl -i "https://sync.koreader.rocks/users/create" \
241 -H "Accept: application/vnd.koreader.v1+json" \
242 -H "Content-Type: application/json" \
243 --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"
244```
245
246Already have KOReader Sync credentials? Skip registration; basic sync only requires using the same existing username/password on all devices.
247
248When this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, pick a different username or use that existing account.
249
2502. On each CrossPoint device:
251 - Go to **Settings -> System -> KOReader Sync**.
252 - Set **Username** and **Password** (enter the plain password; CrossPoint computes MD5 internally, and use the same values on all devices).
253 - Set **Sync Server URL** to `https://sync.koreader.rocks`, or leave it empty (both use the same default KOReader sync server).
254 - Run **Authenticate**.
255
2563. While reading, press **Confirm** to open the reader menu, then select **Sync Progress**.
257 - Choose **Apply Remote** to jump to remote progress.
258 - Choose **Upload Local** to push current progress.
259
260##### Option B: Self-Hosted Server (Docker Compose)
261
2621. Start a sync server:
263
264```bash
265mkdir -p kosync-quickstart
266cd kosync-quickstart
267
268cat > compose.yaml <<'YAML'
269services:
270 kosync:
271 image: koreader/kosync:latest
272 ports:
273 - "7200:7200"
274 - "17200:17200"
275 volumes:
276 - ./data/redis:/var/lib/redis
277 environment:
278 - ENABLE_USER_REGISTRATION=true
279 restart: unless-stopped
280YAML
281
282# Docker
283docker compose up -d
284
285# Podman (alternative)
286podman compose up -d
287```
288
289> [!NOTE]
290> `ENABLE_USER_REGISTRATION=true` is convenient for first setup. After creating your users, set it to `false` (or remove it) to avoid unexpected registrations.
291
2922. Verify the server:
293
294```bash
295curl -H "Accept: application/vnd.koreader.v1+json" "http://<server-ip>:17200/healthcheck"
296# Expected: {"state":"OK"}
297```
298
2993. Register a user once.
300CrossPoint authenticates against KOReader Sync (`koreader/kosync`) using an MD5 key, so register using the MD5 of your password:
301
302> [!WARNING]
303> Sending a reusable MD5-derived password over plain HTTP is insecure.
304> Create unique sync-only credentials and do not reuse main account passwords.
305> Prefer `https://<server-ip>:7200` whenever traffic leaves a fully trusted LAN or when using untrusted networks.
306> Use `curl -k` only for self-signed certificate testing.
307
308```bash
309USERNAME="user"
310PASSWORD="pass"
311PASSWORD_MD5="$(printf '%s' "$PASSWORD" | openssl md5 | awk '{print $2}')"
312
313curl -i "http://<server-ip>:17200/users/create" \
314 -H "Accept: application/vnd.koreader.v1+json" \
315 -H "Content-Type: application/json" \
316 --data "{\"username\":\"$USERNAME\",\"password\":\"$PASSWORD_MD5\"}"
317```
318
319If this returns `HTTP 402` with `{"code":2002,"message":"Username is already registered."}`, the account already exists.
320
3214. On each CrossPoint device:
322 - Go to **Settings -> System -> KOReader Sync**.
323 - Set **Username** and **Password** (enter the plain password; CrossPoint computes MD5 internally, and use the same values on all devices).
324 - Set **Sync Server URL** to `http://<server-ip>:17200`.
325 - Run **Authenticate**.
326
327If you use the HTTPS listener, use `https://<server-ip>:7200` (`curl -k` only for self-signed certificate testing).
328
3295. While reading, press **Confirm** to open the reader menu, then select **Sync Progress**.
330 - Choose **Apply Remote** to jump to remote progress.
331 - Choose **Upload Local** to push current progress.
332
333### 3.7 Sleep Screen
334
335The **Sleep Screen** setting controls what is displayed when the device goes to sleep:
336
337| Mode | Behavior |
338|------|----------|
339| **Dark** (default) | The CrossPoint logo on a dark background. |
340| **Light** | The CrossPoint logo on a white background. |
341| **Custom** | A custom image from the SD card (see below). Falls back to **Dark** if no custom image is found. |
342| **Cover** | The cover of the currently open book. Falls back to **Dark** if no book is open. |
343| **Cover + Custom** | The cover of the currently open book. Falls back to **Custom** behavior if no book is open. |
344| **None** | A blank screen. |
345
346#### Cover settings
347
348When using **Cover** or **Cover + Custom**, two additional settings apply:
349
350- **Sleep Screen Cover Mode**: **Fit** (scale to fit, white borders) or **Crop** (scale and crop to fill the screen).
351- **Sleep Screen Cover Filter**: **None** (grayscale), **Contrast** (black & white), or **Inverted** (inverted black & white).
352
353#### Custom images
354
355To use custom sleep images, set the sleep screen mode to **Custom** or **Cover + Custom**, then place images on the SD card:
356
357- **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.)
358- **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.
359
360> [!TIP]
361> For best results:
362> - Use uncompressed BMP files with 24-bit color depth
363> - X4: Use a resolution of 480x800 pixels to match the device's screen resolution.
364> - X3: Use a resolution of 528x792 pixels to match the device's screen resolution.
365
366---
367
368## 4. Reading Mode
369
370Once you have opened a book, the button layout changes to facilitate reading.
371
372### Page Turning
373| Action | Buttons |
374| ----------------- | ------------------------------------ |
375| **Previous Page** | Press **Left** _or_ **Volume Up** |
376| **Next Page** | Press **Right** _or_ **Volume Down** |
377
378The role of the volume (side) buttons can be swapped in the **[Controls Settings](#363-controls)**.
379
380If 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.
381
382### Chapter Navigation
383* **Next Chapter:** Press and **hold** the **Right** (or **Volume Down**) button briefly, then release.
384* **Previous Chapter:** Press and **hold** the **Left** (or **Volume Up**) button briefly, then release.
385
386This feature can be disabled in the **[Controls Settings](#363-controls)** to help avoid changing chapters by mistake.
387
388
389### System Navigation
390* **Return to Home:** Press the **Back** button to close the book and return to the **[Home](#31-home-screen)** screen.
391* **Return to Browse Files:** Press and hold the **Back** button to close the book and return to the **[Browse Files](#33-browse-files-screen)** screen.
392* **Chapter Menu:** Press **Confirm** to open the **[Table of Contents/Chapter Selection](#5-chapter-selection-screen)** screen.
393
394### Supported Languages
395
396CrossPoint renders text using the following Unicode character blocks, enabling support for a wide range of languages:
397
398* **Latin Script (Basic, Supplement, Extended-A):** Covers English, German, French, Spanish, Portuguese, Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Hungarian, Romanian, Slovak, Slovenian, Turkish, and others.
399* **Cyrillic Script (Standard and Extended):** Covers Russian, Ukrainian, Belarusian, Bulgarian, Serbian, Macedonian, Kazakh, Kyrgyz, Mongolian, and others.
400
401What is not supported: Chinese, Japanese, Korean, Vietnamese, Hebrew, Arabic, Greek and Farsi.
402
403---
404
405## 5. Chapter Selection Screen
406
407Accessible by pressing **Confirm** while inside a book.
408
4091. Use **Left** (or **Volume Up**), or **Right** (or **Volume Down**) to highlight the desired chapter.
4102. Press **Confirm** to jump to that chapter.
4113. *Alternatively, press **Back** to cancel and return to your current page.*
412
413---
414
415## 6. Current Limitations & Roadmap
416
417Please note that this firmware is currently in active development. The following features are **not yet supported** but are planned for future updates:
418
419* **Images:** Embedded images in e-books will not render.
420* **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.
421
422---
423
424## 7. Troubleshooting Issues & Escaping Bootloop
425
426If an issue or crash is encountered while using Crosspoint, feel free to raise an issue ticket and attach the serial monitor logs. The logs can be obtained by connecting the device to a computer and starting a serial monitor. Either [Serial Monitor](https://www.serialmonitor.org/) or the following command can be used:
427
428```
429pio device monitor
430```
431
432If 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.
433
434There can be issues with broken cache or config. In this case, delete the `.crosspoint` directory on your SD card (or consider deleting only `settings.bin`, `state.bin`, or `epub_*` cache directories in the `.crosspoint/` folder).