Lector · Firmware guide Back to the tools

Lector User Guide

Lector is e-reader firmware for the Xteink X3 and X4. This guide covers the buttons, the screens, the in-book menu, and every setting the firmware ships with.

A few names on the device and on the SD card still read "CrossPoint", the project Lector forked from: the /.crosspoint folder on the card, the crosspoint.local web address, and the CrossPoint Reader plugin for Calibre. Those are written exactly as they appear.

Contents:

1. Buttons

Lector uses the buttons the device already has, in the manufacturer's layout by default.

LocationButtons
Bottom edgeBack, Confirm, Left, Right
Right sidePower, Volume Up, Volume Down, Reset

Throughout this guide the side buttons are called Volume Up and Volume Down, and the bottom-edge buttons Back, Confirm, Left and Right.

The four bottom-edge buttons can be reassigned in Settings > Controls > Remap Front Buttons, and the side buttons can be swapped or disabled with Side Button Layout (reader).

Tapping, on a device with a touch screen

A tap takes two steps. The first tap on a row, a button or any other control highlights it with a thin outline and does nothing else. A second tap on that same control runs it. A tap on a different control moves the outline there instead of running anything, so only one control is ever highlighted and a mis-aimed tap costs nothing.

In Settings and Text Settings, the outlined row is waiting for confirmation; it is never filled black. The first tap leaves the button selection where it was. The second tap selects and runs the outlined row.

The highlight goes away when you scroll the list, leave the screen, or tap an empty part of the screen. Moving the selection with the side keys clears it too, and the on-screen Back and Select buttons along the bottom edge act on the first tap, as the physical buttons do.

Three things are deliberately left on a single tap, because a confirming tap would get in the way: the on-screen keyboard, sliders (brightness, text size and the rest, which are dragged or stepped), and the Yes/No pop-ups, which are already a question being answered. Page turns by tap while reading are unchanged. Holding a word on the page for half a second looks it up in the dictionary.

Touch Sleep (Settings > System, X4 Pro) is Off by default. Set to 15 s, 30 s or 1 min, it saves a little battery by putting the touch screen to sleep after that long without input. While it sleeps, touches and the touch Home key below the screen do nothing; press any side button, or lock and unlock, to wake it.

Taking a screenshot

Hold Power and Volume Down together. The image is written to /screenshots/ on the SD card as a BMP file.

Screenshots can also be taken from inside a book: open the in-book menu, go to the Device tab, and pick Take screenshot. A screenshot taken this way is filed under a folder named after the book, and its filename records the chapter, page and percentage.

2. Power, sleep and wake

Power on and off

Press and hold Power for about half a second.

With Settings > Controls > Short Power Button Click set to Sleep, the hold that puts the device to sleep is much shorter (about a tenth of a second); every other value keeps the longer hold, so a stray press cannot switch the device off.

Waking is a separate setting: Settings > Controls > Wake Hold. Normal needs the usual half-second hold, so a press in a bag cannot wake the reader; Fast wakes on any press. Readers that already had Sleep selected keep the fast wake they had.

Binding an action to Double-click power turns that shortcut off again: the first of the two presses would otherwise sleep the device before the second one arrived. Sleep then needs the normal half-second hold, and the double-click action works as bound.

To reboot, press and release Reset, then press and hold Power for a few seconds.

Boot shows the name "Lector" between the two banners. Waking never redraws the sleep screen: the unlock goes straight to the screen you asked for.

Battery

The battery percentage sits in the status bar and in the home header. When the charge drops to 10 percent Lector shows a Battery low notice over whatever you are reading; press any button to dismiss it and carry on. It appears once per discharge, not once per wake, and it arms itself again after the battery climbs back above 15 percent. It stays quiet while the device is plugged in, and it never interrupts a firmware update, a file transfer or the sleep screen.

Sleep

The device sleeps after the inactivity set in Settings > System > Time to Sleep, anywhere from 1 to 30 minutes, or Never. The default is 10 minutes. What it shows while asleep is the sleep screen, covered in section 8.

A wake from sleep goes straight back into the book, without stopping at any other screen.

Fast Unlock (Display settings, on by default) shortens the wait for the recovery button chord at wake and paints the page straight over the sleep screen in one pass instead of clearing the screen first; the first page turn after a wake then runs the clean pass. Turn it off if a wake ever lands in the recovery firmware picker by itself, or if a faint wallpaper stays visible in the first page after a wake.

First launch

The first boot lands on the Home screen. After that, an unlock always opens a book. Open Book on Boot chooses which: Last Book (the default) opens the last-read book every time, and Random Book opens one of the books in progress at random. Holding Back during boot skips both and lands on Home.

On a fresh card, Lector creates the folders it uses: /read, /recents, /sleep and /sleep pause (that last name contains a space).

3. Home screen

The Home screen is the entry point. It lists the books you have been reading, and below them:

menu, and only once something has been read.

section 9.

Settings > Controls > Home Back Button decides what Back does here: nothing, resume the current book, or open Sortes. Resume remains the default. Sortes opens a randomly chosen finished EPUB at a random page: a book counts as finished when its saved library badge is 100% (Read), wherever it is filed. The footer says No read books and does nothing when none qualify.

Back or sleep ends the visit. Sortes leaves the saved reading position, Read status, filing and recents untouched. Quotes and bookmarks can still be saved deliberately, and the reader menu works. Book look edits last for this visit; sync, sending the book, deleting its cache/book and removing it from recents require opening it normally. Selection covers the whole library; an unreadable or over-deep directory tree shows Unavailable instead of choosing from an incomplete scan.

Settings > Display > Author On Home switches the author line between initials and the full name.

Reading stats

Every time you close a book (Back, Home, or sleep), Lector adds one line to /stats/journal.txt on the card: when, how long, how many pages you turned forward, whether you reached the end, and the title. Sittings under a minute are not kept. A page left open for more than five minutes stops the clock for that page, so a book left on the table does not count as reading.

Stats on Home leads with this month as a calendar: each day fills from the bottom by how long you read that day, the longest day full, and today has a thick outline. Under it are the last 7 days, this year, all time and the books finished. The sleep screen shows the last 7 days in a thin black band along its foot, on wallpapers and covers alike, when Settings > Display > Show Reading Stats is on (off by default). Reading Stats Position puts its text in the Center (default), or on the Left or Right.

Days need the clock. The X3 and X4 Pro keep one; the X4 has no clock chip, so a Wi-Fi connection sets its clock until it next powers off. With the clock set, a sitting is dated. Without it the sitting still counts toward the totals, but not toward any day, week or year.

The journal is plain text, one tab-separated line per sitting, so you can open it in a spreadsheet, edit it, or delete it to start over. With File Transfer running, the Stats page in the browser shows the same totals, the last 12 months day by day, and recent sessions.

4. Browsing files

The file browser shows the current folder path at the top, files with their extensions, and folders in brackets, for example [folder-name].

either one to move a whole page at a time.

small menu offering Send to Nearby Reader and Delete; anything else goes straight to the delete confirmation. Nothing is deleted without confirming.

match.

Renaming and moving files is done from the web interface rather than on the device, see section 9.

Each row shows its file type on the right, and a book you have opened before also shows how far in you are on the left, in front of the title: a percentage while you are reading it, or Read once you reach its last page, in the same style the home screen uses. The badge stays even after the book leaves the Recents list or is filed into /read. Books you have never opened show no badge, and comics (XTC) never carry one.

Upgrading from an older release, the books still in your Recents list get their badge on the first boot; any other book read long ago gets one the next time you close it.

Settings > System > Show Hidden Files decides whether entries beginning with . appear. File Browser Order lists a folder alphabetically, in random order, by the date each file was added, or by when you last read it. Both date orders put the newest first and leave the folders at the top; books you have never opened sit at the bottom of Last Read, in name order. Last Read reads one small file per book, so a folder of hundreds takes a moment longer to open.

Recently Added uses the date on the file itself, which is written by whatever put it there: books copied from a computer carry a real date, while books the device downloaded itself (Wi-Fi transfer, Calibre, OPDS) all share one, so they keep name order among themselves.

What Lector can open

TypeOpens as
.epubThe full reader: chapters, footnotes, bookmarks, quotes
.txtPlain-text reader
.xtcXTC reader, the Xteink book format
.bmpImage viewer
.pxcImage viewer for the packed wallpaper format
.binOffered as a firmware file, see section 13

Text files are read as UTF-8. A file that is not valid UTF-8 is read as Windows-1252, the usual encoding of older Western text files (Latin-1 accents, curly quotes, the euro sign). UTF-16 files are not supported and show a message instead.

From the image viewers you can set the picture as your sleep wallpaper.

Opening a wallpaper from /sleep gives you the triage buttons: Favorite, Pause and Delete. Favoriting closes the viewer straight away and takes you back to the folder, so you can work through a folder at button speed. The rename itself happens later, when you open a book, reach the home screen, or lock the device, because renaming a file in a folder of thousands is slow enough to be worth keeping off the press. The list shows the new name immediately either way.

Filing books automatically

Three System settings move books for you as you read:

5. Reading

Turning pages

ActionButtons
Previous pageLeft or Volume Up
Next pageRight or Volume Down

Settings > Controls > Side Button Layout (reader) swaps the two side buttons or disables them while reading. Orient front buttons turns the bottom-edge buttons along with the page when you read in landscape.

With Short Power Button Click set to Page Turn, a short press of Power also turns the page.

EPUB, TXT and XTC batch position saves every ten page turns, or on the next page redraw after five minutes. Leaving the book or putting the reader to sleep saves any pending position; explicit progress sync saves immediately.

Chapters

Chapter jumps live in the in-book menu, under Navigate > Select Chapter. Holding a page turn button does nothing: page turning fires on the press, so the page never waits to find out whether a hold was coming.

Footnotes

In an EPUB with footnotes, open a footnote from its reference and return afterwards to where you were. Falling asleep or closing the book after following a link reopens the book on the page you were viewing, and Back still returns you to where you tapped the link.

Short Power Button Click > Footnotes opens the footnotes for the page with a short press; when the page holds a single footnote, it opens that one directly. Quick-return from footnotes makes a short power press act as Back while a footnote is on screen.

Leaving the book

Browser** swaps the two, so a short press goes to the browser instead.

to. A short press always opens the menu.

Holds and double clicks

Three Controls settings bind an action to a gesture. They share one list of actions, so any of them can be pointed at any action.

Pop-up Items decides which rows the quick pop-up those bindings can open actually contains.

Text Settings is no longer one of the actions on offer, and is no longer a pop-up row. It is reached from Settings, or from the in-book menu. A binding that pointed at it reads as Disabled after the update; pick another action for that gesture.

Reading in landscape

Settings > Reader > Reading Orientation offers Portrait, Landscape CW, Portrait 180° and Landscape CCW. The in-book menu can rotate the screen without leaving the book.

6. The in-book menu

Press Confirm while reading. The menu is one list of five tabs: Look, Navigate, Book, Sleep Screen and Device. Each tab is a heading with a plus at its right edge and the number of rows it holds. Moving onto a heading opens it (the plus turns to a minus) and closes the one that was open. Back closes the open tab; a second Back leaves the menu. Rows that do not apply to the open book are not shown at all.

The menu opens on Sleep Screen. Settings > Reader > Book Menu Opens On changes that to Navigate, Book, Look or Device instead, and that choice always wins. The Sleep Screen tab appears alongside the others while the lock screen has a wallpaper to act on; on nights it has none, a menu set to open there opens on Navigate.

open are left out, so every row here goes somewhere.

from the card; hits appear as they are found, each with a line of context and its chapter. Case, curly quotes and line breaks do not matter. Up to 100 hits. Pick one to land on its page (Return takes you back); Back stops the search. The last search is offered again.

or opening a bookmark. Keeps the last eight jump origins during this reading session; ordinary page turns do not add entries. Shown only while there is somewhere to return to. Changing text size still returns to the same passage. Leaving the book (including sleep) clears this history; the Back button and footnote returns keep their usual behavior.

Return. A new jump (chapter, percentage, bookmark) clears it.

This Book

section 11.

definition again.

Look

place.

default bar, so every book opens with it.

Sleep Screen

This tab appears only when the last sleep screen was a wallpaper that is still on the card.

rotating again.

Device

Press Back to close the menu.

7. Bookmarks and quotes

Bookmarks

Bind Long press while reading to Bookmark and hold Confirm to drop one, or use Toggle Bookmark in the menu. Open the list from Navigate > Bookmarks, press Confirm on an entry to jump there. To delete one, hold Confirm on it, then confirm.

Bookmarks are stored as JSON under /.crosspoint/bookmarks.

Quotes

Grab Quote saves a passage from the current page. Quotes for a book live beside it on the card as a plain-text sidecar named after the book, for example Book_QUOTES.txt, with the chapter and anchor recorded next to each quote. View Quotes reads them back on the device.

8. Sleep screen and wallpapers

Settings > Display > Sleep Screen decides what the panel shows while the device sleeps:

ModeBehaviour
CustomA wallpaper from the SD card. When none is found, the open book's cover; with no book open, a white screen with the lector crow and the name "Lector".
CoverThe open book's cover. With no book open, the white crow and "Lector" screen.

Custom is the default. Retired sleep-screen choices now use Custom. Inactivity uses your selected sleep screen.

Wallpaper files

Wallpapers are .bmp or .pxc files. The .pxc format is the packed 2-bit format the Lector converter writes.

the device sleeps. A hidden /.sleep folder is also read.

takes priority over the folders.

Size the image to the panel: 480x800 on the X4, 528x792 on the X3.

Wallpaper rows in the in-book menu's Sleep Screen tab favourite, pause, hold and delete the wallpaper the device just showed. Paused wallpapers move to /sleep pause and stop appearing in the rotation. Settings > Display > Shuffle Wallpapers reshuffles the order.

Five Display settings decide what is drawn over a wallpaper: Show Wallpaper Name, Show Favorite Badge, Show Wallpaper Position, Show Reading Stats (the last 7 days in a band along the foot) and Sleep Footer Text (your own line of text). Sleep Image Quality trades rendering time against how the image looks: Fast or Pretty.

Cover settings

For Cover, and for the cover Custom falls back to:

cropped to fill).

Inverted.

9. Getting books onto the device

The simplest route is a card reader: copy files onto the SD card. On the X4 Pro the device can be that card reader itself, over its USB cable (USB Drive, below). Everything else here is wireless.

File Transfer

Home > File Transfer offers four modes, and a fifth on the X4 Pro:

the network list; it never offers to forget the network, since a connection drops for reasons that have nothing to do with the password. To forget one deliberately, press Left on a saved network in that list.

In the first two modes the device runs a web server. Open http://<device-ip>/ in a browser, or http://crosspoint.local. The web interface uploads and downloads files, manages fonts, and edits Wi-Fi networks and OPDS servers at http://<device-ip>/settings. It also speaks WebDAV, so the card can be mounted as a network drive.

The home page shows battery charge, free card space, and the books you have in progress. The file manager can zip several selected files into one download, and Fetch from URL hands the reader a link so it downloads the file itself instead of you uploading it.

An upload that is cut off part way through does not have to start again. What arrived is kept beside the finished books under a .part name, which the library ignores, and uploading the same file again carries on from that point. The browser checks that the part already on the card really is the start of the file being sent, so a different file that happens to share the name is uploaded from the beginning instead of being appended to. A file only takes its real name, and only appears in the library, once every byte is there. Starting an upload into a folder clears any other .part file left in it, so the leftovers cannot build up; you can also delete them yourself from the file manager.

While joined to a network, the screen shows the Wi-Fi signal strength in dBm.

See docs/webserver.md for the full web server documentation, including managing files from the command line with curl.

USB Drive

On the X4 Pro the SD card can appear on a computer as a removable disk, with no card reader and no network. The X3 and X4 do not have this mode.

  1. Open File Transfer > USB Drive.
  2. Connect the reader to the computer with a USB data cable. The screen says **USB Drive

Connected**; the disk can take up to 30 seconds to appear on the computer.

  1. Copy books, fonts or wallpapers onto the disk as you would with any USB stick.
  2. Eject the disk on the computer (Eject in Finder, Explorer or the Linux file manager,

or eject /dev/sdX in a terminal; a plain umount is not enough) and wait for it to disappear. The reader then restarts to Home with the new files in place.

Unplugging the cable also ends the mode, but eject first: a cable pulled while the computer is still writing can leave a half-copied file or a damaged card, exactly as with any USB stick.

While the computer holds the card the reader does nothing else with it: no sleep, no screenshots, no other screens, and the buttons are inactive. Before a computer connects, Back, Power or the Home gesture leaves the mode, and it gives up by itself after five minutes. Leaving always restarts the reader, which is how it takes the card back.

Calibre wireless transfers

Lector works with the CrossPoint Reader device plugin for Calibre.

Installing the plugin:

  1. Download the latest crosspoint_reader plugin from

the plugin releases page.

  1. In Calibre, open Preferences > Plugins > Load plugin from file and pick the zip.
  2. Restart Calibre.

Configuring it:

  1. Open Preferences > Plugins, search for "crosspoint", and click Customize plugin.
  2. Set Host to your device's IP address.
  3. Leave the other fields alone, unless you want uploads in a subfolder: set Upload path

to a path relative to the root, for example /mybooks.

  1. Restart Calibre.

The CrossPoint Reader plugin settings dialog in Calibre

Sending books:

  1. On the device, open File Transfer > Calibre Wireless and join a network.
  2. In Calibre, select one or more books, right-click, then **Send to Device > Send to main

memory**.

The plugin creates a folder for the author and copies the book into it.

Sending books to the device from the Calibre library view

Books cannot be removed through Calibre. Delete them from the device or the web interface.

Nearby Reader

Two Lector devices can pass a file directly, with no network in between.

  1. On the receiving device, open File Transfer > Nearby Reader.
  2. On the sending device, select the file in the browser and choose Send to Nearby Reader,

or use the same row in the in-book menu's Device tab to send the open book.

  1. The receiving device asks before accepting, and reports the name and size.

A transfer that is interrupted, by walking out of range or by pressing Back, keeps what arrived. Send the same file again and it carries on from there rather than starting over. Both devices check the whole file against the sender's checksum before it is kept, so a resumed file that does not match is discarded rather than left in the library. Font families are the exception: a family that does not finish is removed whole and sent again from the start.

The list of readers found, and the accept/decline question, are chosen with the direction keys and Select, or by tapping the row twice on a device with a touch screen (see Tapping).

A font family goes over the same way, from Settings > Reader > Installed Fonts > Send font. The faces of the family are sent one after another and the receiving device asks once, naming the family, how many sizes it holds and the total size. The family installs into /.fonts/ and is ready to pick in Text Settings straight away. A family already installed on the receiving device is refused rather than merged or overwritten; delete it there first to replace it. A send that stops part way leaves nothing half-installed.

Turn Wi-Fi and File Transfer off first: the radio cannot do both at once, and the device says so if it is busy.

Sharing Wi-Fi and OPDS credentials

Settings > System > Share WiFi and OPDS sends this device's saved Wi-Fi networks and OPDS servers to another Lector over the same Nearby radio. Open File Transfer > Nearby Reader on the receiving device first, exactly as for a file. It asks before accepting, adds the networks and servers, and reports how many of each arrived.

The bundle carries the passwords in the clear and the Nearby radio is not encrypted, so anyone in range while it is sending can capture them. Both devices delete the bundle as soon as they are done with it. Share when you mean to, not out of habit.

OPDS catalogs

Settings > System > OPDS Servers stores up to 8 catalogs. Each entry has a name, the catalog root URL (for a Calibre Content Server, usually ending in /opds), and optional username and password. Authentication is HTTP Basic; set Calibre to Basic rather than Digest.

Browse and download from Home > OPDS Browser. With more than one catalog saved it opens a server picker, whose last row, Add Server, adds another. Where downloads land (Download folder) and how they are named (Filename format: Author - Title, Title - Author, or Title) are set from the OPDS screens and the web interface, not from the on-device Settings menu.

Catalogs can also be managed from the web interface at http://<device-ip>/settings.

HTTPS servers and their certificates

An https:// OPDS catalog or KOReader sync server is checked before your password is sent. A server with a certificate from a public authority (Let's Encrypt, ZeroSSL, DigiCert and the like) just connects, including after its certificate renews.

A server those cannot vouch for, such as a self-signed home server, asks Trust this server's certificate? the first time, showing the start of the certificate's SHA-256 fingerprint and the server's name. Compare it with the fingerprint your server shows (for example openssl x509 -in cert.pem -noout -fingerprint -sha256) and choose Confirm to trust it. Lector remembers it for that server and asks again only when the certificate changes. Trusted certificates are kept in /.crosspoint/trusted_certs.txt on the SD card, one server per line; delete a line to forget one.

Plain http:// servers are not checked, and anything typed into them, passwords included, crosses the network readable by anyone on it.

10. Syncing reading position

Nearby Sync

To receive a position without opening a book, choose Nearby Sync > Receive position on Home. On the sending device, keep the book open and choose Nearby Sync from the in-book menu's Device tab. The receiver finds its own copy and shows the matched book's name. It keeps the furthest position, ready for the next time you open that book. No book file is sent.

Both devices must use the same Document Matching setting under KOReader Sync. The receiver checks recent books first, then other EPUBs with existing reading caches. It needs saved progress and a book metadata cache. Existing chapter caches must map the position exactly; a chapter with no cache is laid out at the received text offset when you next open the book. If the book was never opened, its metadata cache is missing, or the position cannot be mapped exactly, it refuses and leaves the saved place unchanged. Open the book and use in-book Nearby Sync in that case. Very large libraries can reach the search limit; the screen reports a refusal.

For the existing two-way sync, open the same book on both devices and choose Nearby Sync in each in-book menu. Both keep the furthest position automatically.

Home's Nearby Sync menu also offers Receive from Nearby Reader for file transfers and Send to browse files to send. File transfers keep duplicate files separate.

KOReader sync

Lector syncs progress with KOReader-compatible sync servers, so KOReader apps and devices can share a position with it.

Settings live in Settings > System > KOReader Sync: Username, Password, Sync Server URL, Document Matching (Filename or Binary), Send Document Metadata, Sync Behavior, and Auto Sync.

Sync Behavior is Smart sync for new configurations, which resolves the simple cases on its own: upload when the server has nothing, do nothing when both sides agree, apply the remote when the remote is ahead. When this device is ahead it shows both positions with Upload Local selected, so the server's position is never overwritten without asking. Configurations migrated from older firmware keep Ask every time, which offers Apply Remote and Upload Local on every sync. Either can be changed at any time.

To sync, open the in-book menu and pick Sync Progress from the Device tab, or bind a hold to KOSync in Settings > Controls.

Auto Sync (off by default) does it for you. When a book opens, the first time since the device last slept, Lector joins a saved Wi-Fi network, fetches the position and moves to it when the server is ahead. When the device goes to sleep after you turned pages, it sends the new position from behind the sleep screen. It uses saved networks only and never shows the network list. If no saved network answers, the book simply opens where you left it. A server whose certificate has not been trusted yet is skipped, so run Sync Progress once by hand first. Each pull costs a few seconds of Wi-Fi and a restart back into the book.

Option A: the CrossPoint sync server (default)

With Sync Server URL left empty, Lector uses https://sync.crosspointreader.com, which speaks the standard KOReader sync protocol. Positions are recorded as chapter-content offsets and sent as the matching KOReader XPath, so devices with different fonts and layouts land on the same text.

  1. Open Settings > System > KOReader Sync.
  2. Set Username and Password (type the plain password; the device computes the MD5

itself). Use the same values on every device.

  1. Leave Sync Server URL empty.
  2. On the first device run Sign Up once. On the others run Authenticate.

Accounts are per server. An account on sync.koreader.rocks does not exist on this one.

Option B: BookOrbit

BookOrbit speaks the KOReader sync protocol and shares the position with its web reader and apps, so a book continues where you stopped on either side.

  1. In BookOrbit, create a KOReader sync account (its KOReader settings page) and an OPDS

account (its OPDS settings page).

  1. Add the OPDS server https://<your-host>/api/v1/opds with the OPDS account, and download

books through it. A copied file is fine too, as long as it is the same file BookOrbit holds.

  1. Set Sync Server URL to https://<your-host>/api/v1/koreader, set Username and

Password to the KOReader sync account, and set Document Matching to Binary. BookOrbit finds the book by its contents, not its name.

  1. Run Authenticate, then turn on Auto Sync if you want it.

With Auto Sync on, Lector also watches for books you are reading in BookOrbit but have not put on the device. When it goes to sleep (after you read, or at most once every 6 hours), it reads the smart shelf named Reading in BookOrbit's OPDS catalogue. A book counts as on the device when the file an OPDS download would save exists, or a recent book has the same title. When some are missing, Home shows a row such as 2 on BookOrbit, not here. Select it to see only those books. Confirm downloads one and opens it at your BookOrbit position. BookOrbit needs a smart shelf called Reading (status is Reading) for this to work. Read-along books arrive without their audio, so their position does not sync.

Option C: the public KOReader server

  1. Set Sync Server URL to https://sync.koreader.rocks. An empty URL points at the

CrossPoint server instead, so this one has to be typed in.

  1. Set Username and Password to your existing KOReader Sync credentials.
  2. Run Authenticate.

If you have no account yet, run Sign Up on the device, or register 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\"}"

HTTP 402 with {"code":2002,"message":"Username is already registered."} means that name is taken.

Option D: your own server

  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
  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. The server authenticates on the MD5 of the password, so register

with that MD5:

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\"}"
  1. On each device, open Settings > System > KOReader Sync, set Username and

Password, set Sync Server URL to http://<server-ip>:17200, and run Authenticate. For the HTTPS listener use https://<server-ip>:7200.

11. Fonts and dictionaries

Fonts

Lector ships with Noto Serif and Noto Sans. Fonts on the SD card are added to that list, and can bring scripts the built-in fonts do not cover, including Chinese, Japanese and Korean.

Three ways to install one:

  1. From the device: Settings > Reader > Manage Fonts, then pick a family to download

over Wi-Fi. A file that fails or arrives damaged is fetched again, up to five attempts, and the screen says which attempt is running. A transfer cut short carries on from where it stopped rather than starting the file over, and a dropped Wi-Fi connection is waited out for up to 20 seconds per attempt. Files that did arrive are kept, so starting the download again fetches only what is still missing, a few styles at a time on a poor connection. Download all and Update all carry on past a family that will not install and name the ones that failed at the end. A file is only put in place once it matches the checksum published for it, so an update that fails leaves the copy already on the card untouched.

When it does not work, the screen names the reason rather than saying only that it failed: no Wi-Fi connection, could not reach the font server, the font server refused the request, the download stopped before it finished, could not write to the SD card, not enough memory, or a font list this firmware cannot read. Under that sits a short code line such as E4 no reply heap 28112/9216, which grows an oom section when the reader ran out of memory rather than out of network. That line is diagnostic, not something to act on; photograph it if you report the problem.

  1. From the web interface: in File Transfer mode, open the Fonts page and upload

.cpfont files. On the X4 Pro the page also takes .ttf and .otf files (2 MB at most per file); the X4 and X3 refuse them.

  1. From your computer: copy fonts into /.fonts/ (preferred) or /fonts/ on the card.

Files come from the lector-fonts repository.

Downloadable families are built at point sizes 10 through 18, so a family gives you nine reading sizes. OpenDyslexic is the exception, at 8 through 16, because its glyphs run larger for the same point size.

On the X4 Pro a family can also be an ordinary TrueType or OpenType font. Make a folder under /fonts/ (or /.fonts/) named after the family and copy its .ttf or .otf files into it, one per style, or upload them from the Fonts page of the web interface. The style comes from the file name (Regular, Bold, Italic, BoldItalic and the usual weight names); a folder holding a single file uses it as the regular face. Such a family offers every size from 8 to 40 pt and renders anti-aliased when Text Anti-Aliasing is on. The X4 and X3 skip these folders; they read .cpfont families only.

Installed families appear in Settings > Reader > Text Settings > Reader Font Family. Full details are in docs/sd-card-fonts.md.

Settings > Reader > Installed Fonts lists what is actually on the card, whichever way it got there, and needs no Wi-Fi. Each row shows the family, how many sizes it holds and how much space it takes, and the family the reader is currently set to is marked. Pick a family for two choices:

the reader back on a built-in font.

Dictionaries

Lector reads StarDict dictionaries from /dictionaries/<name>/ on the card. Pick one in Settings > Reader > Dictionary; the row only appears once a dictionary folder exists.

Look a word up from the in-book menu's Look Up row, or bind a hold to Dictionary in Settings > Controls. On a touch screen, hold the word itself for half a second: its definition opens straight away, and Back returns to the page. Every successful lookup is remembered: Lookup History, in the same menu, lists the last 100 words newest first and reopens any of them. Setup and usage are covered in docs/dictionary.md.

12. Settings reference

Settings are one scrolling list. Rows are grouped under section headings such as Text, Page or Library, and the sections run in four blocks, in this order: Display, Reader, Controls, System. Those four names order the list; they are not printed on screen, and a row is found by scrolling to its section heading.

Step through the list a row at a time. Hold the same button to scroll: it moves a row at a time, speeds up to five rows at a time after about a second, and stops at the end of the list.

Paths in this reference, such as Settings > Reader > Dictionary, name the block a row belongs to, so the rows here appear in the same order as on the device.

12.1 Display

Selection Style

Solid fills the row black and turns its text white (the original look). Brackets puts corner marks around the row's own text, hugging the label and its value separately, and leaves the text black. Caret puts an arrow at the left of the row, beside its first line of text, and leaves the text black. Brackets and Caret redraw faster and ghost less on e-ink, because they leave most of the row untouched.

Sleep screen

Wallpaper

Reading Stats** — what is drawn over the wallpaper. All off by default.

Frontlight (boards with a frontlight)

panel's brightness track runs from 0 to this, and a brightness above it is brought down.

In a book the light panel also has Align Left and Justify, which set the book's paragraph alignment (for that EPUB alone; in a TXT book, for every TXT book), and Paragraph Spacing, which turns the extra space between an EPUB's paragraphs on or off for that book.

Screen

turns off the page-counted refresh only; the reader still cleans the panel when enough ink has moved to need it, so a long session does not end up smeared.

default) keeps Refresh Frequency; any other value applies only to inverted pages.

each chapter you enter, on top of Refresh Frequency, so every chapter opens clean. EPUB only.

Home

12.2 Reader

Text — Text Settings (below), Manage Fonts, Installed Fonts, Dictionary.

Text Settings is one scrolling list, banded into Type, Spacing, Margins and Reading Aids, under a live preview. The preview is a split slice of a real page: the top of the page, a dashed cut, then the bottom of the page, so both vertical margins and the status bar are on screen at their true size while you tune them. Numeric rows are edited in the band across the top: Select arms the number and the header turns into a slider with a minus at one end and a plus at the other. Touch anywhere along the track to jump straight to that value, or drag along it and the value follows your finger. Left and Right move one step, the side buttons move five, and the preview under the band follows, so nothing ever covers the page you are judging. Back or Select puts the band away; there is nothing to confirm, because every change has already been applied. Sleep timeout, frontlight and the other numbers in Settings use the same band.

and below the text, inside your margins and status bar. Short pages stay at the top; EPUB pages with images, rules or ruby keep their layout. This balances line boxes (within one pixel), so letter shapes may still look slightly uneven.

Sides, where it is every side.

Bottom Margin separately; Top+Bottom replaces them with a single Vertical Margin; All Sides puts one number on all four sides and leaves Margin as the only margin row. All Sides also turns Dynamic Margins off and stops offering it, because Dynamic Margins works out a left and right margin of its own that the other two sides cannot match. Switching back does not turn it on again. New devices start at All Sides with 20 on every side; devices updating from an older build keep the margins and the link they had, and anyone still on the old Uniform Margins switch comes back to All Sides.

Justify distributes all spare horizontal space between eligible gaps; the last line keeps its natural spacing. Korean text wraps and stretches only at the spaces between words, never between syllables, unless a single word is wider than the line.

underline, superscript and subscript, writing direction, passages the book marks as hidden, and lists the book marks as having no bullets or numbers. Bold and italic written as <b> or <i> tags are always honoured, switch or not. Numbered lists always show their numbers, and a nested list counts from 1 again. An inline passage in another writing direction keeps the enclosing paragraph's base direction. Arabic and Persian text is shaped once, preserving Alef and Lam order; Latin ligatures remain supported.

first-line indent, margins, padding and image sizes. Paragraph Alignment: Book's Style and First Line Indent: Book both read the book's CSS, so they need this on.

margins and padding. Off drops them, so blocks sit flush with your page margins, and keeps the book's alignment, indents and image sizes. The book's fonts, sizes and line height are never used: the reader's own settings always win.

100% keeps the original spacing. Justified lines still stretch to the right margin; this does not limit their gaps. With Guide Dots, it adjusts the spaces on both sides of each dot, keeping the dot the same size. Changing it re-paginates the book.

Off sets every letter at its plain width. Only the reading text changes; menus keep it.

Off draws each letter on its own. Only the reading text changes; menus keep it.

Off leaves them as plain text; they still open from Footnotes.

fresh page, for books that run chapters or sections together. A heading straight after another heading ("Part One" then "Chapter 1") stays on the same page.

a half spaces, Some adds up to 1 pixel between letters and More up to 2, so the slack spreads into the words instead of opening wide holes. Lines with Focus Reading, Guide Dots, ruby or right-to-left text keep plain justification. Changing it re-paginates the book.

When a nested block ends, the enclosing block's top and bottom spacing is not added again.

the light grey edge pixels as dark grey; Max also draws the dark grey ones black, for crisper, darker anti-aliased text.

Page

text, set in the reading font. The numbers sit at the page's left edge, beside the first line of each paragraph.

Look

heavier paperback ink: ON adds one pixel, BOLDER a second pixel to vertical strokes. The in-book menu row cycles OFF, ON, BOLDER.

Customise Status Bar places each element in one of six slots (top left, top centre, top right, bottom left, bottom centre, bottom right) or turns it off: Battery, Clock, Chapter Title, Book Title, Page in Chapter, Book %, Chapter %, Chapter Number, Pages This Session, Pages to Paragraph, Chapter time left, Book time left. Alongside them:

and the chapter at the bottom. Put both on the same edge (both top or both bottom) and they stack in the Chapter Title's slot: the book title on the first line, the chapter title on the line below. A book without chapters (TXT) shows its title in the Book Title slot, or in the Chapter Title slot when Book Title is off.

with …. A Book Title in a slot of its own is always one line.

the book closes.

next one starts. >P.2 means it runs two more pages. In a TXT book each line break starts a paragraph, so a file broken into short lines always shows >P.0.

spend per page this sitting. They appear after three timed pages; turns under 2 seconds or over 10 minutes are not counted. On EPUB the book estimate scales the rest of the book by the current chapter, so it settles as you read. A TXT book has no chapters, so it shows Book time left only, counted from its exact pages left.

Medium 6 px, Fat 9 px). On EPUB books the Book Bar has a small notch where each chapter starts. A book with more than 64 chapters shows a plain bar.

picker has three fields, sign, hours and minutes: Confirm moves between them and the direction keys change the one being edited, or tap a field to move to it and tap it again to step it. The time the offset produces is shown under the fields.

Manual (UTC offset), the default, the clock uses the offset above.

12.3 Controls

Buttons

Power button

here, Short Power Button Click > Sleep stops sleeping on a single press, since that press is the first half of the double click. Most bindings act through the in-book menu, which only EPUB books have. In a .txt book the double click runs Status Bar and Hold Wallpaper; in an .xtc book, Hold Wallpaper. Bound to anything else, it stays inactive there and the power button keeps its normal, undelayed behaviour. A single power click waits about a quarter of a second while the reader watches for a second one, which is noticeable when Power also turns the page. That wait is only paid while the bound action can actually run: with Footnotes bound, a page without footnotes turns instantly, and a page with them does not.

Hold

Back

12.4 System

Power — Time to Sleep: 1 to 30 minutes, or Never. Default 10 minutes.

Library

Fast Page Turns — on by default on the X4, where it is validated. Page turns and menu moves use the panel's cheapest waveform, which is several times quicker than the standard one. Every eighth pass runs the standard waveform anyway, so the panel never works from a stale temperature reading, and the first paint after a wake never uses it. Turn it off if you ever see ink left behind that a full refresh does not clear.

Performance Timings — off by default, and free while it is off. On, Lector times every screen refresh and reports the numbers three ways: a small line in the top-left corner of the screen showing what the previous refresh cost, a breakdown of the last wake in place of the unlock screen footer, and a .csv file per session in the /perf folder on the card. It is there so a slow page turn can be measured rather than guessed at. Turn it off again when you are done; it writes to the card while it is on.

Network — Wi-Fi Networks, KOReader Sync, OPDS Servers, Share WiFi and OPDS.

Device

and Brazil), Russian, Swedish, Romanian, Catalan, Ukrainian, Belarusian, Italian, Polish, Finnish, Danish, Dutch, Turkish, Kazakh, Hungarian, Lithuanian, Slovenian, Valencian, Hebrew, Slovak, Vietnamese, Norwegian, Arabic, Bosnian and Indonesian.

empty, it falls back to a generated Lector-XXXX name derived from the MAC address.

keep their progress.

section 13.

13. Updating the firmware

Three routes:

offered, never experimental ones. A device already running an experimental build is offered the next stable release, which is how it gets back onto a stable line without a cable.

Card Firmware Update**, or open the .bin from the file browser.

installs over Web Serial from a browser.

A firmware written from the SD card is read back off the flash and compared against the file before the device is told to boot it, so a bad write is reported as Firmware check failed, nothing changed instead of restarting into the old firmware as though it had worked.

Every Lector release is signed. Check for updates installs only a signed release and refuses anything else with Update not signed by lector, so a tampered download can never become the firmware you boot. The SD card still takes any firmware, since other firmwares are not signed by Lector: an unsigned file asks Not signed by lector. Install? before it installs. A file that carries a Lector signature that does not match is refused as Invalid firmware file.

If the device will not boot far enough to reach Settings, hold Volume Up together with Power at boot (Volume Down on the X4 Pro, whose Volume Up pin doubles as the chip's boot-strap pin). That goes straight to the SD card firmware update screen. If no card is mounted, the screen asks for one and keeps trying, so a card swapped in at that point still gets you there.

Leaving Lector

Some Xteink X3 and X4 units are sold with USB flashing disabled in the factory, mostly ones bought through Chinese retailers. On a locked unit there is no serial fallback, so these are the ways off this firmware, safest first:

  1. SD card. Put the other firmware's .bin on the card and use **Settings > System > SD

Card Firmware Update**. Stock, CrossPoint, CrossInk and INX images all install this way. Lector points the bootloader at the new image with rollback left disabled, so the new firmware stays after its first boot rather than being sent back here.

  1. Recovery chord. Same thing when Lector will not start: Volume Up + Power at boot

(Volume Down + Power on the X4 Pro).

  1. Over Wi-Fi, with the OTA Unlocker. The

CrossPoint OTA Unlocker turns a computer into a Wi-Fi hotspot that answers the reader's own update check with a firmware you choose. On the reader, use Settings > System > Install Other Firmware: unlike Check for updates, it installs whatever the server offers, including the same version, an older one, or a different firmware entirely.

  1. Last resort: an SPI flash clip, wiring straight to the flash chip. See

docs/fix-bricked-xteink.md.

The X4 Pro is not supported by the OTA Unlocker; use routes 1 and 2 there.

14. Troubleshooting

The device is stuck in a bootloop. Press and release Reset, then hold Back and Power to boot to the Home screen. If that does not work, hold Volume Up and Power at boot (Volume Down on the X4 Pro) to reach the SD card firmware update screen.

This device cannot be flashed over USB. Some units ship with USB flashing disabled from the factory. See Leaving Lector in section 13 for the routes that still work.

Something is broken after a settings or cache change. Delete the .crosspoint folder on the card, or just the parts of it that matter: settings.json, state.json, or the epub_* cache folders.

A crash happened. Lector writes a crash report to the SD card without needing a USB connection. Attach that file to any bug report.

A firmware update failed, or ran to the end and the old firmware came back. Lector keeps lector-flash-diagnostics.txt at the root of the card: every install attempt from the card or over the air, where it stopped and at which byte, the battery and memory at the time, the partition table and boot record, the boot after an install, and any crash or watchdog restart. It also records Wi-Fi connection progress, so a stall at Connecting... leaves evidence even before an update starts. Leave it for two minutes, then send the same file. Send that whole file. It names no book, network or device. It is kept to the last two days and a few kilobytes, and the web interface home page links to it (the Diagnostics link).

More detail is needed. Connect the device over USB and run the debugging monitor (needs Python 3 with pyserial, colorama and matplotlib; install with pip3 install pyserial colorama matplotlib):

python3 scripts/debugging_monitor.py

It finds the serial port on its own, or takes one:

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

It colour-codes the log by category, graphs free memory once a second, sends commands you type back to the device, and saves screenshots the device triggers to screenshot.bmp.

OptionDescription
--baud RATEBaud rate (default: 115200)
--filter KEYWORDShow only lines containing the keyword (case-insensitive)
--suppress KEYWORDHide lines containing the keyword (case-insensitive)
 
# 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.

Known limits

seconds to convert for the sleep screen and the home thumbnail.

placeholder. Ordinary JPEG and PNG images render.

Bugs and logs are welcome as issue tickets.

This guide describes lector 0.47.0.