[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11311":3},{"id":4,"name":5,"fullName":6,"owner":5,"repo":5,"description":7,"homepage":8,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},11311,"crosspoint-reader","crosspoint-reader\u002Fcrosspoint-reader","Firmware for the Xteink X3 and X4 e-paper display readers","",null,"C",5167,926,47,207,0,23,134,687,98,39.9,"MIT License",false,"master",[],"2026-06-12 02:02:30","# CrossPoint Reader\n\nFirmware for the **Xteink X4** e-paper display reader (unaffiliated with Xteink).\nBuilt using **PlatformIO** and targeting the **ESP32-C3** microcontroller.\n\nCrossPoint Reader is a purpose-built firmware designed to be a drop-in, fully open-source replacement for the official \nXteink firmware. It aims to match or improve upon the standard EPUB reading experience.\n\n![](.\u002Fdocs\u002Fimages\u002Fcover.jpg)\n\n## Motivation\n\nE-paper devices are fantastic for reading, but most commercially available readers are closed systems with limited \ncustomisation. The **Xteink X4** is an affordable, e-paper device, however the official firmware remains closed.\nCrossPoint exists partly as a fun side-project and partly to open up the ecosystem and truly unlock the device's\npotential.\n\nCrossPoint Reader aims to:\n* Provide a **fully open-source alternative** to the official firmware.\n* Offer a **document reader** capable of handling EPUB content on constrained hardware.\n* Support **customisable font, layout, and display** options.\n* Run purely on the **Xteink X4 hardware**.\n\nThis project is **not affiliated with Xteink**; it's built as a community project.\n\n## Features & Usage\n\n- [x] EPUB parsing and rendering (EPUB 2 and EPUB 3)\n- [x] Image support within EPUB\n- [x] Saved reading position\n- [x] File explorer with file picker\n  - [x] Basic EPUB picker from root directory\n  - [x] Support nested folders\n  - [ ] EPUB picker with cover art\n- [x] Custom sleep screen\n  - [x] Cover sleep screen\n- [x] Wifi book upload\n- [x] Wifi OTA updates\n- [x] KOReader Sync integration for cross-device reading progress\n- [x] Configurable font, layout, and display options\n  - [ ] User provided fonts\n  - [ ] Full UTF support\n- [x] Screen rotation\n\nMulti-language support: Read EPUBs in various languages, including English, Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Polish, Swedish, Norwegian, [and more](.\u002FUSER_GUIDE.md#supported-languages).\n\nSee [the user guide](.\u002FUSER_GUIDE.md) for instructions on operating CrossPoint, including the\n[KOReader Sync quick setup](.\u002FUSER_GUIDE.md#365-koreader-sync-quick-setup).\n\nFor more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document.\n\n## Installing\n\n### Web (latest firmware)\n\n1. Connect your Xteink X4 to your computer via USB-C and wake\u002Funlock the device\n2. Go to https:\u002F\u002Fxteink.dve.al\u002F and click \"Flash CrossPoint firmware\"\n\nTo revert back to the official firmware, you can flash the latest official firmware from https:\u002F\u002Fxteink.dve.al\u002F, or swap\nback to the other partition using the \"Swap boot partition\" button here https:\u002F\u002Fxteink.dve.al\u002Fdebug.\n\n### Web (specific firmware version)\n\n1. Connect your Xteink X4 to your computer via USB-C\n2. Download the `firmware.bin` file from the release of your choice via the [releases page](https:\u002F\u002Fgithub.com\u002Fcrosspoint-reader\u002Fcrosspoint-reader\u002Freleases)\n3. Go to https:\u002F\u002Fxteink.dve.al\u002F and flash the firmware file using the \"OTA fast flash controls\" section\n\nTo revert back to the official firmware, you can flash the latest official firmware from https:\u002F\u002Fxteink.dve.al\u002F, or swap\nback to the other partition using the \"Swap boot partition\" button here https:\u002F\u002Fxteink.dve.al\u002Fdebug.\n\n### Command line (specific firmware version)\n\n1. Install [`esptool`](https:\u002F\u002Fgithub.com\u002Fespressif\u002Fesptool) :\n```bash\npip install esptool\n```\n2. Download the `firmware.bin` file from the release of your choice via the [releases page](https:\u002F\u002Fgithub.com\u002Fcrosspoint-reader\u002Fcrosspoint-reader\u002Freleases)\n3. Connect your Xteink X4 to your computer via USB-C.\n4. Note the device location. On Linux, run `dmesg` after connecting. On MacOS, run :\n```bash\nlog stream --predicate 'subsystem == \"com.apple.iokit\"' --info\n```\n5. Flash the firmware :\n```bash\nesptool.py --chip esp32c3 --port \u002Fdev\u002FttyACM0 --baud 921600 write_flash 0x10000 \u002Fpath\u002Fto\u002Ffirmware.bin\n```\nChange `\u002Fdev\u002FttyACM0` to the device for your system.\n\n### Manual\n\nSee [Development](#development) below.\n\n## Development\n\n### Prerequisites\n\n* **PlatformIO Core** (`pio`) or **VS Code + PlatformIO IDE**\n* Python 3.8+\n* USB-C cable for flashing the ESP32-C3\n* Xteink X4\n\n### Checking out the code\n\nCrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:\n\n```\ngit clone --recursive https:\u002F\u002Fgithub.com\u002Fcrosspoint-reader\u002Fcrosspoint-reader\n\n# Or, if you've already cloned without --recursive:\ngit submodule update --init --recursive\n```\n\n### Flashing your device\n\nConnect your Xteink X4 to your computer via USB-C and run the following command.\n\n```sh\npio run --target upload\n```\n### Debugging\n\nAfter flashing the new features, it’s recommended to capture detailed logs from the serial port.\n\nFirst, make sure all required Python packages are installed:\n\n```python\npython3 -m pip install pyserial colorama matplotlib\n```\nafter that run the script:\n```sh\n# For Linux\n# This was tested on Debian and should work on most Linux systems.\npython3 scripts\u002Fdebugging_monitor.py\n\n# For macOS\npython3 scripts\u002Fdebugging_monitor.py \u002Fdev\u002Fcu.usbmodem2101\n```\nMinor adjustments may be required for Windows.\n\n## Internals\n\nCrossPoint Reader is pretty aggressive about caching data down to the SD card to minimise RAM usage. The ESP32-C3 only\nhas ~380KB of usable RAM, so we have to be careful. A lot of the decisions made in the design of the firmware were based\non this constraint.\n\n### Data caching\n\nThe first time chapters of a book are loaded, they are cached to the SD card. Subsequent loads are served from the \ncache. This cache directory exists at `.crosspoint` on the SD card. The structure is as follows:\n\n\n```\n.crosspoint\u002F\n├── epub_12471232\u002F       # Each EPUB is cached to a subdirectory named `epub_\u003Chash>`\n│   ├── progress.bin     # Stores reading progress (chapter, page, etc.)\n│   ├── cover.bmp        # Book cover image (once generated)\n│   ├── book.bin         # Book metadata (title, author, spine, table of contents, etc.)\n│   └── sections\u002F        # All chapter data is stored in the sections subdirectory\n│       ├── 0.bin        # Chapter data (screen count, all text layout info, etc.)\n│       ├── 1.bin        #     files are named by their index in the spine\n│       └── ...\n│\n└── epub_189013891\u002F\n```\n\nDeleting the `.crosspoint` directory will clear the entire cache. \n\nDue the way it's currently implemented, the cache is not automatically cleared when a book is deleted and moving a book\nfile will use a new cache directory, resetting the reading progress.\n\nFor more details on the internal file structures, see the [file formats document](.\u002Fdocs\u002Ffile-formats.md).\n\n## Contributing\n\nContributions are very welcome!\n\nIf you are new to the codebase, start with the [contributing docs](.\u002Fdocs\u002Fcontributing\u002FREADME.md).\n\nIf you're looking for a way to help out, take a look at the [ideas discussion board](https:\u002F\u002Fgithub.com\u002Fcrosspoint-reader\u002Fcrosspoint-reader\u002Fdiscussions\u002Fcategories\u002Fideas).\nIf there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.\n\nEveryone here is a volunteer, so please be respectful and patient. For more details on our governance and community \nprinciples, please see [GOVERNANCE.md](GOVERNANCE.md).\n\n### To submit a contribution:\n\n1. Fork the repo\n2. Create a branch (`feature\u002Fdithering-improvement`)\n3. Make changes\n4. Submit a PR\n\n---\n\nCrossPoint Reader is **not affiliated with Xteink or any manufacturer of the X4 hardware**.\n\nHuge shoutout to [**diy-esp32-epub-reader** by atomic14](https:\u002F\u002Fgithub.com\u002Fatomic14\u002Fdiy-esp32-epub-reader), which was a project I took a lot of inspiration from as I\nwas making CrossPoint.\n","CrossPoint Reader 是为 Xteink X4 电子墨水屏阅读器设计的开源固件。该项目基于 C 语言开发，使用 PlatformIO 构建，并针对 ESP32-C3 微控制器进行优化。其核心功能包括支持 EPUB 2 和 EPUB 3 格式的解析与渲染、图片显示、保存阅读进度、文件浏览及选择、自定义睡眠屏幕、Wi-Fi 书籍上传和 OTA 更新等。此外，它还提供了可配置的字体、布局和显示选项，以及 KOReader Sync 集成以实现跨设备同步阅读进度。该固件适用于希望在 Xteink X4 上获得更开放、可定制化阅读体验的用户。",2,"2026-06-11 03:31:37","top_language"]