Eunchurn Park eabd149371
Add retry logic and progress bar for chapter indexing (#128)
## Summary

* **What is the goal of this PR?**

Improve reliability and user experience during chapter indexing by
adding retry logic for SD card operations and a visual progress bar.

* **What changes are included?**

- **Retry logic**: Add 3 retry attempts with 50ms delay for ZIP to SD
card streaming to handle timing issues after display refresh
- **Progress bar**: Display a visual progress bar (0-100%) during
chapter indexing based on file read progress, updating every 10% to
balance responsiveness with e-ink display limitations

## Additional Context

* **Problem observed**: When navigating quickly through books with many
chapters (before chapter titles finish rendering), the "Indexing..."
screen would appear frozen. Checking the serial log revealed the
operation had silently failed, but the UI showed no indication of this.
Users would likely assume the device had crashed. Pressing the next
button again would resume operation, but this behavior was confusing and
unexpected.

* **Solution**:
- Retry logic handles transient SD card timing failures automatically,
so users don't need to manually retry
- Progress bar provides visual feedback so users know indexing is
actively working (not frozen)

* **Why timing issues occur**: After display refresh operations, there
can be timing conflicts when immediately starting SD card write
operations. This is more likely to happen when rapidly navigating
through chapters.

* **Progress bar design**: Updates every 10% to avoid excessive e-ink
refreshes while still providing meaningful feedback during long indexing
operations (especially for large chapters with CJK characters).

* **Performance**: Minimal overhead - progress calculation is simple
byte counting, and display updates use `FAST_REFRESH` mode.
2025-12-28 15:59:44 +11:00
2025-12-26 12:13:40 +11:00
2025-12-03 22:06:45 +11:00
2025-12-20 01:15:20 +11:00
2025-12-03 22:06:45 +11:00
2025-12-03 22:06:45 +11:00
2025-12-03 22:06:45 +11:00
2025-12-03 22:06:45 +11:00
2025-12-03 22:06:45 +11:00
2025-12-03 22:06:45 +11:00
2025-12-26 12:13:40 +11:00
2025-12-20 01:44:39 +11:00
2025-12-21 18:42:06 +11:00

CrossPoint Reader

Firmware for the Xteink X4 e-paper display reader (unaffiliated with Xteink). Built using PlatformIO and targeting the ESP32-C3 microcontroller.

CrossPoint Reader is a purpose-built firmware designed to be a drop-in, fully open-source replacement for the official Xteink firmware. It aims to match or improve upon the standard EPUB reading experience.

Motivation

E-paper devices are fantastic for reading, but most commercially available readers are closed systems with limited customisation. The Xteink X4 is an affordable, e-paper device, however the official firmware remains closed. CrossPoint exists partly as a fun side-project and partly to open up the ecosystem and truely unlock the device's potential.

CrossPoint Reader aims to:

  • Provide a fully open-source alternative to the official firmware.
  • Offer a document reader capable of handling EPUB content on constrained hardware.
  • Support customisable font, layout, and display options.
  • Run purely on the Xteink X4 hardware.

This project is not affiliated with Xteink; it's built as a community project.

Features & Usage

  • EPUB parsing and rendering
  • Image support within EPUB
  • Saved reading position
  • File explorer with file picker
    • Basic EPUB picker from root directory
    • Support nested folders
    • EPUB picker with cover art
  • Custom sleep screen
    • Cover sleep screen
  • Wifi book upload
  • Wifi OTA updates
  • Configurable font, layout, and display options
  • Screen rotation

See the user guide for instructions on operating CrossPoint.

Installing

Web (latest firmware)

  1. Connect your Xteink X4 to your computer via USB-C
  2. Go to https://xteink.dve.al/ and click "Flash CrossPoint firmware"

To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.

Web (specific firmware version)

  1. Connect your Xteink X4 to your computer via USB-C
  2. Download the firmware.bin file from the release of your choice via the releases page
  3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section

To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.

Manual

See Development below.

Development

Prerequisites

  • PlatformIO Core (pio) or VS Code + PlatformIO IDE
  • Python 3.8+
  • USB-C cable for flashing the ESP32-C3
  • Xteink X4

Checking out the code

CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:

git clone --recursive https://github.com/daveallie/crosspoint-reader

# Or, if you've already cloned without --recursive:
git submodule update --init --recursive

Flashing your device

Connect your Xteink X4 to your computer via USB-C and run the following command.

pio run --target upload

Internals

CrossPoint Reader is pretty aggressive about caching data down to the SD card to minimise RAM usage. The ESP32-C3 only has ~380KB of usable RAM, so we have to be careful. A lot of the decisions made in the design of the firmware were based on this constraint.

EPUB caching

The first time chapters of an EPUB are loaded, they are cached to the SD card. Subsequent loads are served from the cache. This cache directory exists at .crosspoint on the SD card. The structure is as follows:

.crosspoint/
├── epub_12471232/       # Each EPUB is cached to a subdirectory named `epub_<hash>`
│   ├── progress.bin     # Stores reading progress (chapter, page, etc.)
│   ├── 0/               # Each chapter is stored in a subdirectory named by its index (based on the spine order)
│   │   ├── section.bin  # Section metadata (page count)
│   │   ├── page_0.bin   # Each page is stored in a separate file, it
│   │   ├── page_1.bin   #   contains the position (x, y) and text for each word
│   │   └── ...
│   ├── 1/
│   │   ├── section.bin
│   │   ├── page_0.bin
│   │   ├── page_1.bin
│   │   └── ...
│   └── ...
│
└── epub_189013891/

Deleting the .crosspoint directory will clear the cache.

Due the way it's currently implemented, the cache is not automatically cleared when the EPUB is deleted and moving an EPUB file will reset the reading progress.

Contributing

Contributions are very welcome!

If you're looking for a way to help out, take a look at the ideas discussion board. If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.

To submit a contribution:

  1. Fork the repo
  2. Create a branch (feature/dithering-improvement)
  3. Make changes
  4. Submit a PR

CrossPoint Reader is not affiliated with Xteink or any manufacturer of the X4 hardware.

Huge shoutout to diy-esp32-epub-reader by atomic14, which was a project I took a lot of inspiration from as I was making CrossPoint.

Description
Firmware for the Xteink X4 e-paper display reader
Readme MIT 133 MiB
Languages
C 95.1%
C++ 4.3%
Python 0.3%
HTML 0.2%