ryOS CrossMux

English | 中文 | 日本語 | 한국어

ryOS CrossMux is reading-first firmware for the Xteink X3 and X4. It is a fork of CrossMux, built on CrossPoint Reader.

This fork focuses on Chinese and CJK books: vertical EPUB layout, broader font coverage, reliable SD-card fonts, and faster 4-level grayscale text. It keeps reading stats, WeRead (Chinese SKUs), and standby faces. The old game and toy apps are not part of the firmware.

Current firmware version: 1.4.13

What this fork adds

Vertical CJK EPUB reading

Choose Writing Mode > Vertical (RTL) in Reader Settings or the in-book menu. The layout engine then:

• lays out columns from right to left
• uses vertical presentation forms for CJK punctuation; Traditional Chinese keeps upright centered 點號 (、。，：；！？) per CLREQ / Taiwan practice, while Simplified Chinese follows Japanese-style FE remapping
• stacks repeated ellipses and dashes one character cell at a time
• rotates Latin runs and keeps short numeric references readable
• applies tate-chu-yoko to compact horizontal runs (isolated single letters/digits expand to fullwidth; two-character runs stay halfwidth)
• applies 標點擠壓 / 約物詰め (punctuation compression) on TC/SC/JA when enabled in Reader Settings (default on; Korean/Latin ignore)
• moves paragraph spacing and block margins along the column axis
• reverses page controls to follow the reading direction

Vertical mode activates only for EPUBs whose language metadata is tagged Chinese, Japanese, or Korean. Other books stay horizontal even if the global setting is vertical.

Localized CJK firmware (TC / SC / JA / KO)

Four CJK SKUs ship alongside international:

Env	Locale	UI	OTA asset
gh_release_tc	zh-TW	Traditional Chinese	firmware-tc.bin
gh_release_sc	zh-CN	Simplified Chinese (from Taiwan-terminology YAML via OpenCC tw2sp)	firmware-sc.bin
gh_release_ja	ja-JP	Japanese	firmware-ja.bin
gh_release_ko	ko-KR	Korean	firmware-ko.bin

Chinese SKUs include English + Chinese UI, CJK line-breaking, WeRead, dual-slot OTA from ryokun6/crossmux, and embedded CJK bitmap fonts from GenSen Rounded TW (Traditional SKU stores TC-keyed bitmaps; Simplified SKU subsets the same OTF by SC codepoints so glyph shapes stay Simplified).

Automatic text conversion while reading (Chinese SKUs only): book codepoints are remapped at glyph lookup so you can open the same EPUB/TXT on either Chinese SKU. The Traditional build maps Simplified → Traditional bitmaps; the Simplified build maps Traditional → Simplified. UI strings are converted at build time — the SC SKU runs OpenCC tw2sp on the shared Taiwan YAML (e.g. 檔案 → 文件).

Japanese / Korean SKUs use GenSen Rounded 2 JP and Resource Han Rounded KR respectively, with no OpenCC Han conversion. WeRead and the Chinese calendar face are Chinese-SKU only. See docs/engineering/japanese-korean-build.md and docs/engineering/chinese-build.md.

Better SD-card fonts

.cpfont families can live in either /.fonts/ or /fonts/ on the SD card. The loader indexes large CJK families on demand, prewarms upcoming page glyphs, and falls back to the regular style when a CJK bold or italic glyph is absent.

The repo also includes an EB Garamond plus regional Source Han Serif builder for locale families EBGaramondSHS-{TC,SC,JA,KO} (vendored sources under lib/EpdFont/scripts/source_fonts/). See SD-card fonts.

Faster grayscale text

Text anti-aliasing uses the display's four grayscale levels. The fork renders the two grayscale planes in narrow strips and writes them directly to the display, instead of keeping two extra full-screen buffers in RAM. Fast glyph blitting and strip rejection reduce repeated work on pages with SD fonts and vertical columns.

Cache and image handling

Section cache rebuilds write to a .tmp sidecar before replacing the active cache. If an SD card refuses to truncate or rename a stale section file, the reader can keep using the completed sidecar instead of failing the chapter rebuild.

The Large only image mode now drops inline icons, em-sized separators, and small standalone images while preserving full figures.

A smaller Apps menu

The firmware ships only reading-related apps:

• ryOS Books
• Reading Stats, including history, heatmap, profile, and achievements
• WeRead in the Chinese builds
• Standby faces, including Sloppy Clock and AirPage, plus Chinese Calendar in the Chinese builds

Sudoku, Gomoku, Minesweeper, 2048, Chinese Chess, Game of Life, and the avatar generator are intentionally excluded.

ryOS Cloud Sync and Books

Sign up at https://os.ryo.lu, then use the same ryOS Account username and password on the device:

• ryOS Cloud Sync (Settings → System → ryOS Cloud Sync) — sync reading progress across devices. The protocol is KOReader-compatible, so the same credentials also work with KOReader apps when pointed at the same server.
• ryOS Books (Apps → ryOS Books, or Settings → System → ryOS Books) — browse and download books from the catalog linked to your account. A default ryOS Books catalog is prefilled; you can add other OPDS servers (for example a home Calibre library) alongside it.

Reader features

ryOS CrossMux keeps the main CrossPoint reader:

• EPUB 2 and EPUB 3 rendering
• chapter navigation, footnotes, bookmarks, and go-to-percent
• embedded styles, images, kerning, hyphenation, and focus reading
• CJK vertical-rl layout, 禁則 (kinsoku) line/column breaks, and 標點擠壓 / 約物詰め (punctuation compression) on TC/SC/JA
• auto page turn, orientation control, screenshots, and QR display
• ryOS Cloud Sync with your ryOS Account (KOReader-compatible)
• .epub, .txt, .xtc, .xtch, and .bmp files
• recent books, folder browsing, cache management, and long-press delete
• installable SD-card font families with regular, bold, italic, and bold-italic styles
• international UI translations and RTL interface support

Wireless tools include file transfer, the EPUB Optimizer, web settings, fast WebSocket uploads, WebDAV, Calibre wireless connection, ryOS Books, and network OTA from the latest ryokun6/crossmux GitHub release. OTA selects firmware.bin, firmware-tc.bin, firmware-sc.bin, firmware-ja.bin, or firmware-ko.bin to match the installed build. Firmware can also be installed through USB, the web flasher, or SD Card Firmware Update.

X3 and X4 support

One firmware image runs on both devices. It detects the hardware at boot and adapts the panel size, controls, battery source, and available peripherals.

• X4: 800 x 480 SSD1677 display
• X3: 792 x 528 UC81xx display, DS3231 clock, fuel gauge, and tilt page turn

There is no separate X3 build. Build any language variant and flash the same firmware.bin to the matching target in the web flasher. See device variants for the detection and recovery details.

Before flashing

USB-locked device warning

The Xteink Unlocker officially supports CrossPoint and CrossInk. ryOS CrossMux is a community fork. Flashing it to a USB-locked device can leave the device permanently stuck without a supported recovery path. Do not install this fork on a locked unit unless you already have a verified way to recover it.

Units bought directly from xteink.com are normally not USB-locked. If a browser cannot see the serial device, try another data-capable cable, USB port, and Chromium-based browser before assuming the device is locked.

Build and install

Requirements

• pioarduino or its VS Code plugin
• Python 3.8 or newer
• Git with submodule support
• a data-capable USB-C cable

Clone

git clone --recursive https://github.com/ryokun6/crossmux.git
cd crossmux

If the repo was cloned without submodules:

git submodule update --init --recursive

Build

# International firmware
pio run -e gh_release

# Traditional Chinese (zh-TW)
pio run -e gh_release_tc

# Simplified Chinese (zh-CN)
pio run -e gh_release_sc

# Japanese (ja-JP)
pio run -e gh_release_ja

# Korean (ko-KR)
pio run -e gh_release_ko

Build outputs:

.pio/build/gh_release/firmware.bin
.pio/build/gh_release_tc/firmware.bin
.pio/build/gh_release_sc/firmware.bin
.pio/build/gh_release_ja/firmware.bin
.pio/build/gh_release_ko/firmware.bin

Flash over USB

# International
pio run -e gh_release -t upload

# Traditional Chinese
pio run -e gh_release_tc -t upload

# Simplified Chinese
pio run -e gh_release_sc -t upload

# Japanese
pio run -e gh_release_ja -t upload

# Korean
pio run -e gh_release_ko -t upload

You can also open the CrossPoint web flasher, select the physical device, choose Custom .bin, and upload the matching build output. The target selector patches the image for the device bootloader. It does not select a different firmware build.

To return to official firmware, flash an official CrossPoint release.

Regenerate CJK fonts (optional)

Only needed when changing character sets or refreshing embedded fonts. See chinese-build.md and japanese-korean-build.md.

Install custom fonts

You can install .cpfont files without rebuilding the firmware:

1. On the device, open Settings > System > Manage Fonts.
2. Or upload fonts through the file-transfer web interface.
3. Or copy a family directory to /.fonts/FamilyName/ or /fonts/FamilyName/ on the SD card.
4. Select the family under Settings > Reader > Reader Font Family.

The hidden /.fonts/ directory wins if the same family exists in both font roots. Conversion commands, Unicode presets, and the CJK font builder are documented in docs/sd-card-fonts.md.

Known limits

• Built-in CJK coverage is best at the default 14 pt Medium size. Large and Extra Large are intended mainly for English books / UI glyphs.
• Built-in CJK text has one weight. Install an SD-card family for distinct bold and italic styles.
• SC↔TC remapping (Chinese SKUs only) covers common pairs; rare characters outside the map or the embedded subset can still render as □.
• Japanese and Korean SKUs do not convert Han orthography; Chinese books may show □ for glyphs outside that SKU’s subset.
• Vertical mode depends on correct zh, ja, or ko EPUB language metadata.
• The desktop simulator currently models X4 geometry only. X3 display and peripheral testing needs real hardware.

Development

Useful checks before opening a pull request:

./bin/clang-format-fix
pio check -e default
pio run -e default
pio run -e gh_release_tc
pio run -e gh_release_sc
pio run -e gh_release_ja
pio run -e gh_release_ko

The ESP32-C3 has about 380 KB of usable RAM. Reader caches live on the SD card under /.crosspoint/, and code changes should avoid adding persistent heap pressure.

Start here:

• User guide
• Development guide
• Architecture
• Chinese build
• Japanese / Korean build
• Cache management
• Binary file formats
• Web server
• Desktop and WebAssembly simulator

Credits and license

ryOS CrossMux builds on work from CrossMux, CrossPoint Reader, and diy-esp32-epub-reader.

The project is not affiliated with Xteink or any device manufacturer.

Licensed under the MIT License.