Duet v0.1.0-alpha.1

Duet is a reading-first CrossInk fork for the Xteink X3 and X4. This first public alpha brings the same shared feature set to both devices, with device-specific builds and deliberately candid testing notes.

Download the Correct File

  • Xteink X3: Duet-X3-v0.1.0-alpha.1.bin
  • Xteink X4: Duet-X4-v0.1.0-alpha.1.bin

Verify the file against SHA256SUMS.txt. Never flash an X3 BIN onto an X4 or an X4 BIN onto an X3.

Highlights

  • Cover libraries: list, 2x2, 3x3, 4x4, and five-cover carousel views with title/author sorting, smart search, filters, reading badges, and More Info.
  • Reader controls: quick in-book overlay, chapter picker, dictionary, spacing, font and layout options, bookmarks, clippings, stats, and explicit position sync.
  • Reading analytics: 31 top-level views including calendars, heatmaps, streaks, sessions, trends, Reader DNA, per-book timelines, device split, Reading Wrapped, and tracker-backed library/series/taste pages.
  • Two-device reading: nearby stats/history sync over ESP-NOW and in-book position sync, plus KOReader-compatible online progress sync.
  • Custom homes and apps: multiple dashboards, configurable stats slots, reorderable shortcuts, favorites, 108 persistent achievements, Tetris, If Found, Screen Clean, and an on-device guide.
  • Typography and accessibility: device-specific built-in sizes, categorized SD-card fonts that expose their installed sizes, regular/italic/bold styles with measured synthetic fallbacks, A/B preview, OpenDyslexic, Bionic Reading, line-spacing presets, darkness, and refresh controls.
  • StarDict dictionaries with in-book lookup and per-book word history.
  • Custom sleep screens, full-refresh display care, and configurable locked Power-click cycling.

Alpha 1 Repairs

  • Public-facing firmware, boot/crash text, Settings, simulator, translations, web portal, updater, artifacts, and documentation now use the Duet identity. Compatibility storage paths and internal IDs remain unchanged so existing settings, progress, statistics, bookmarks, and caches survive the rename.
  • Nearby Stats Sync protocol 5 now exchanges the CRC-protected Stats Date after totals, book summaries/details, journal, and attribution ledger. This is intended to align Days Read, Daily Average, streak, and calendar grouping on both readers without rewriting reading duration or book dates.
  • Passive sync receive gates reset for every attempt, preventing a prior transfer from falsely completing a later one.
  • OTA now checks the canonical Duet repository, selects the correct X3/X4 artifact, accepts legacy release names during migration, and correctly orders alpha, beta, RC, and stable versions.
  • Grid and carousel caches use exact device-specific dimensions and can be prefilled on a desktop before browsing.
  • Carousel movement reuses the four covers that remain visible instead of decoding them again on every button press. One hidden cover is prefetched beyond each visible edge, so an ordinary next or previous move can paint all five cards without blanking the new outside cover once the seven-cover window has hydrated. Center-quality upgrades remain silent.
  • Low-memory grid cursor updates on both X3 and X4 now shed off-page prefetches and safely fall back to a full fast refresh when a partial update is unsafe. The X4 panel driver also uses one no-throw display scratch buffer, fixing the X4-specific allocation abort captured in physical-device logs.
  • Desktop cover overrides support malformed or coverless EPUBs without modifying the book file.

Large-Library Cover Prefill

Duet can build new thumbnails on-device, but a large or multiply organized library is much nicer when the computer does the one-time bulk pass:

# X3
python3 scripts/prefill_cover_thumbnails.py "/Volumes/XTeink X3" --device x3

# X4
python3 scripts/prefill_cover_thumbnails.py "/Volumes/XTeink X4" --device x4

The script extracts each EPUB’s real cover and writes all five exact grid and carousel sizes to the hashed paths Duet requests. It is incremental: valid thumbnails persist, and Duet still handles genuinely new books later. Confirm failed_books is empty in /.crossink/desktop_cover_prefill.json. See Desktop Cover Prefill and the AI-assistant prompt.

Known Issues and Active Test Targets

  • First-time on-device cover generation can still be slow on large folders, especially on the X3 or a slow SD card. Desktop prefill is strongly recommended.
  • Grid and carousel input is designed to move before cover hydration finishes; consistent behavior under unfamiliar cards and 1,000+ file folders needs broader physical testing.
  • Complex or image-heavy chapters may still show a visible indexing pause when guarded pre-indexing is cancelled or cannot fit in memory.
  • Nearby Stats Sync can finish at slightly different times on the two readers. Both must remain on the sync screen until both report success. Repeated date/history convergence is an explicit alpha test target.
  • X3 and X4 have different screen geometry and memory pressure, so behavior that passes on one is not automatically accepted on the other.
  • Cache migration or regeneration can make the first boot, first book open, or first folder visit slower than later visits.
  • SD-card filesystem damage can look like a firmware crash because Duet keeps books, settings, progress, statistics, and caches on the card. If unrelated screens begin failing, back up the card and run a read-only filesystem check before deleting state or reformatting. See Troubleshooting.

Before Installing

  1. Back up the complete SD card.
  2. Keep the last known-good firmware BIN.
  3. Preserve /.crossink, /.crosspoint, books, fonts, dictionaries, and sleep images.
  4. Put exactly one update BIN at the card root.
  5. Confirm Settings > System shows Duet 0.1.0-alpha.1 after flashing.
  6. Test sleep/wake and one known-good book before a long reading session.

First installation and recovery can use the CrossPoint web flasher’s Custom .bin option. Existing Duet installations can use Settings > System > SD Firmware Update.

Useful Bug-Report Files

  • /.crossink/reader_timing.txt
  • /.crossink/picker_timing.txt
  • /.crossink/picker_hb.txt
  • /.crossink/nearby_sync_timing.txt
  • /.crossink/home_timing.txt
  • /.crossink/boot_timing.txt
  • /.crossink/desktop_cover_prefill.json
  • /crash_report.txt

Review files before posting: book paths, device names, and library metadata may be personal. Never upload an ebook, complete SD-card archive, credentials, or real reading-history snapshots.

Credits

Duet descends from CrossPoint Reader through CrossInk and includes credited adaptations or design lineage from CrossInk Carousel, CrumBLE, CPR-vCodex, CrossPet, Biscuit, SEEK Reader, aalu CrossPoint, and CrossPoint Flow. See Authors and Third-Party Notices for the full provenance and license record.

This site uses Just the Docs, a documentation theme for Jekyll.