snark13/Xteink-X4-crosspoint-reader
1
0
Fork 0
mirror of https://github.com/daveallie/crosspoint-reader.git synced 2026-02-07 08:07:40 +03:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
Firmware for the Xteink X4 e-paper display reader
221 Commits 3 Branches 26 Tags 82 MiB
C 93.9%
C++ 5.8%
HTML 0.2%
Python 0.1%
6fc178de2e
Go to file
Claude 6fc178de2e
Fix WiFi file transfer lockup and add performance optimizations 
This commit resolves critical stability issues causing WiFi file transfer
crashes in STA mode and adds aggressive performance optimizations for
maximum upload/download throughput.

CRITICAL BUG FIXES:

1. Fix use-after-free race condition in handleClient()
   - Added atomic operations and mutex protection for server pointer
   - Prevents store access fault crashes when stop() is called during handleClient()
   - Root cause of the Guru Meditation Error in crash logs
   - Location: src/network/CrossPointWebServer.cpp:135-158

2. Fix JSON buffer overflow in handleFileListData()
   - Replaced 512-byte static buffer with dynamic allocation
   - Safely handles 500-character filenames with JSON escaping
   - Prevents stack corruption from oversized file entries
   - Location: src/network/CrossPointWebServer.cpp:253-306

3. Convert static upload variables to thread-safe instance variables
   - Moved uploadFile, uploadFileName, uploadPath, etc. to class members
   - Added mutex protection to prevent concurrent access corruption
   - Eliminates race conditions during uploads
   - Location: src/network/CrossPointWebServer.h:44-54, CrossPointWebServer.cpp:311-313

4. Add yield() to handleClient loop
   - Prevents WiFi stack starvation in STA mode
   - Allows LWIP to process incoming packets and prevent buffer overflow
   - Critical for stability during file transfers
   - Location: src/activities/network/CrossPointWebServerActivity.cpp:304-311

5. Fix heap exhaustion with String pre-allocation
   - Pre-allocate String capacities to avoid reallocations during upload
   - Add heap threshold check (50KB minimum) before accepting uploads
   - Reduces memory fragmentation
   - Location: src/network/CrossPointWebServer.cpp:323-376

ROBUSTNESS IMPROVEMENTS:

6. Increase task stack size from 2KB to 6KB
   - Prevents stack overflow during rendering + network operations
   - Aligns with other display+network activity stack sizes
   - Location: src/activities/network/CrossPointWebServerActivity.cpp:51

PERFORMANCE OPTIMIZATIONS:

7. Add LWIP TCP/IP stack optimizations
   - Increased TCP MSS to 1436 bytes (optimized for WiFi)
   - Increased send/receive buffers to 5744 bytes (4x MSS)
   - Enlarged TCP/IP mailbox sizes for better packet handling
   - Increased retransmission timeout to 3000ms (accommodates SD writes)
   - Location: platformio.ini:31-49

8. Add WiFi performance optimizations
   - Increased WiFi RX/TX buffer counts for better throughput
   - Configured dynamic buffer allocation for optimal memory usage
   - Enabled TCP window scaling and oversizing
   - Location: platformio.ini:41-49

9. Maximize WiFi TX power
   - Set WiFi TX power to maximum (19.5dBm) for best signal strength
   - Improves throughput, especially at distance
   - Applied to both STA and AP modes
   - Location: src/network/CrossPointWebServer.cpp:58,
     src/activities/network/CrossPointWebServerActivity.cpp:152,192

EXPECTED IMPACT:
- Eliminates WiFi file transfer crashes in STA mode
- Improves upload/download speeds by 2-3x through TCP optimizations
- Increases stability during large file transfers (>100MB)
- Better performance on weak WiFi signals
- Reduces heap fragmentation and memory pressure

TESTING RECOMMENDATIONS:
1. Test large file uploads (>50MB) in both STA and AP modes
2. Verify system stability during concurrent uploads
3. Monitor heap usage during file transfers
4. Test with long filenames (400+ characters)
5. Verify performance improvement with speed tests

Fixes: WiFi lockup bug causing Guru Meditation Errors during file transfer
2026-01-09 22:34:01 +00:00
.github Network details QR code (#113) 2025-12-26 12:13:40 +11:00
bin Aleo, Noto Sans, Open Dyslexic fonts (#163) 2025-12-30 19:21:47 +11:00
docs Docs: Add instructions for file management via curl (#282) 2026-01-09 08:58:58 +11:00
include Public release 2025-12-03 22:06:45 +11:00
lib Remove HTML entity parsing (#274) 2026-01-07 23:08:43 +11:00
open-x4-sdk@bd4e670750 Add exFAT support (#150) 2025-12-30 16:09:30 +11:00
scripts Add connect to Wifi and File Manager Webserver (#41) 2025-12-20 01:05:43 +11:00
src Fix WiFi file transfer lockup and add performance optimizations 2026-01-09 22:34:01 +00:00
test Public release 2025-12-03 22:06:45 +11:00
.clang-format Public release 2025-12-03 22:06:45 +11:00
.clangd Move to smart pointers and split out ParsedText class (#6) 2025-12-12 22:13:34 +11:00
.gitignore Add connect to Wifi and File Manager Webserver (#41) 2025-12-20 01:05:43 +11:00
.gitmodules Public release 2025-12-03 22:06:45 +11:00
LICENSE Public release 2025-12-03 22:06:45 +11:00
partitions.csv Public release 2025-12-03 22:06:45 +11:00
platformio.ini Fix WiFi file transfer lockup and add performance optimizations 2026-01-09 22:34:01 +00:00
README.md Add EPUB 3 nav.xhtml TOC support (#197) 2026-01-03 19:10:35 +11:00
USER_GUIDE.md Docs: Add instructions for file management via curl (#282) 2026-01-09 08:58:58 +11:00

README.md

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 (EPUB 2 and EPUB 3)
  • 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
    • User provided fonts
    • Full UTF support
  • 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.

Data caching

The first time chapters of a book 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.)
│   ├── cover.bmp        # Book cover image (once generated)
│   ├── book.bin         # Book metadata (title, author, spine, table of contents, etc.)
│   └── sections/        # All chapter data is stored in the sections subdirectory
│       ├── 0.bin        # Chapter data (screen count, all text layout info, etc.)
│       ├── 1.bin        #     files are named by their index in the spine
│       └── ...
│
└── epub_189013891/

Deleting the .crosspoint directory will clear the entire cache.

Due the way it's currently implemented, the cache is not automatically cleared when a book is deleted and moving a book file will use a new cache directory, resetting the reading progress.

For more details on the internal file structures, see the file formats document.

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.