Pocket Daily Firmware

Pocket Daily is offline-first firmware for Xteink X3/X4: resume the book already on the device, carry a small daily study deck, retain last-synced weather and schedule context, and keep a useful E-ink sleep frame without requiring Wi-Fi.

The firmware does not depend on any daemon or cloud service. Weather and today's events come from the companion app over Pocket Sync (docs/pocket-glance-v1.md); the former AgentDeck daemon integration was removed on 2026-09-25.

Pocket Daily is built on the open-source CrossPoint Reader engine and preserves its reader, storage, format, and recovery foundations.

The independent Pocket Daily app provides the account-free iOS and macOS management experience for books, learning packs, firmware, diagnostics, and direct SD-card transfers.

• Offline-first Pocket Home with local continue-reading and daily study cards.
• SD-backed Japanese learning packs: offline daily kanji with licensed, integrity-checked content and optional updates through Pocket Sync.
• SD-backed weather and today's schedule sent by the companion app.
• Retained sleep screen based only on locally durable information.
• Coverage-tested PocketSansJP UI font bundle with reproducible OFL sources.

CrossPoint is open-source e-reader firmware - community-built, fully hackable, free forever. It's maintained by a growing community of developers and readers who believe your device should do what you want - not what a manufacturer decided for you.

Now running on: ESP32C3-based Xteink X4 and X3.

• Reader engine: EPUB 2/3 rendering with embedded-style option, image handling, hyphenation, kerning, chapter navigation, footnotes, bookmarks, go-to-percent, auto page turn, orientation control, focus reading, KOReader progress sync and more.

• Various formats: native handling for .epub, .xtc/.xtch, .txt, and .bmp.

• Screenshots.

• Custom fonts: install your favorite fonts on the SD card.

• Tilt page turn (X3 only).

• Library workflow: folder browser, hidden-file toggle, long-press delete, recent books, SD-cache management.

• Wireless workflows:

  • File transfer web UI
  • EPUB Optimizer
  • Web settings UI/API (edit many device settings from browser)
  • WebSocket fast uploads
  • WebDAV handler
  • AP mode (hotspot) and STA mode (join existing Wi-Fi), both with QR helpers
  • Calibre wireless connect flow
  • OPDS browser with saved servers (up to 8), search, pagination, and direct download
  • OTA update checks and installs from GitHub releases

• Customization: multiple themes (Classic, Lyra, Lyra Extended, RoundedRaff), sleep screen modes, front/side button remapping, status bar controls, power-button behavior, refresh cadence, and more.

• Localization: 24 UI languages and counting. RTL support.

• Dictionary lookup — inline word lookup without leaving the reader.

• More themes.

• Much more! stay tuned.

Some Xteink units purchased from third-party stores (e.g. AliExpress) ship with USB flashing locked from the factory. If your device is locked, you will need to use the Xteink Unlocker tool available at https://crosspointreader.com/#unlock-tool before you can flash CrossPoint.

You do not need this tool if you bought your device directly from xteink.com. Those units are not locked.

Not sure if your device is locked? Power it on, connect the USB-C cable, and try flashing via the web flasher first (see Install firmware below). If the browser's serial device picker does not show your device, try a different USB port or browser before assuming the device is locked. Only reach for the unlocker if the device still doesn't appear.

⚠️ WARNING: READ THIS BEFORE USING THE UNLOCKER ⚠️

The only officially supported firmwares in the unlock tool are CrossPoint and CrossInk.

Flashing any other firmware on a USB-locked device may permanently brick the device or leave it permanently stuck on that firmware with no recovery path. Once USB flashing is re-locked, your only way back is via OTA, and if the firmware you flashed doesn't support OTA, there is no way out.

The Papyrix fork has removed OTA update support from its code. If you flash Papyrix onto a USB-locked unit, you will have zero update or recovery path and will be stuck on it forever. Do not flash Papyrix (or any other unsupported firmware) on a locked device.

Pocket Daily releases are published at github.com/puritysb/pocket-daily-firmware/releases. One firmware.bin serves both X3 and X4.

• From the Pocket Daily app (recommended): on the reader press Sync → Same Wi-Fi, then tap Update reader in the app. The app downloads the latest release, validates it and sends it. When you leave the transfer screen, the reader shows Update firmware? and flashes only after you confirm. You can also send a firmware.bin you downloaded yourself under Files, over the same Wi-Fi or a direct connection.
• On the reader: press Sync and choose Check for updates (also under Settings). The reader joins a saved Wi-Fi network and installs only after you confirm. It needs memory for an HTTPS session that an X3 does not have with the stock TLS buffers; there the screen says so and points to the app.

Nothing installs automatically after a transfer.

A recent CrossPoint Reader can receive firmware.bin from the Pocket Daily app over the same Wi-Fi (or copy it to the SD card root) and install it with Settings → System → SD Card Firmware Update. No USB flashing is needed.

The app cannot talk to factory firmware, so the first install is over USB:

1. Connect the reader via USB-C and wake/unlock it.
2. Download firmware.bin from the Pocket Daily releases page.
3. Go to https://crosspointreader.com/#flash-tools, select the device (X3 or X4), click "Custom .bin" and upload that firmware.bin.

Check the USB-lock warning above first. Later updates use the reader or the app.

Flash upstream CrossPoint or the official firmware with https://crosspointreader.com/#flash-tools.

1. Install esptool:

pip install esptool

2. Download firmware.bin from the Pocket Daily releases page.
3. Connect your device via USB-C.
4. Find the device port. On Linux, run dmesg after connecting. On macOS:

log stream --predicate 'subsystem == "com.apple.iokit"' --info

5. Flash:

esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin

Adjust /dev/ttyACM0 to match your system.

Every successful local build stages firmware/update.bin. Send it with the app or scripts/pocket_put.py, or copy it to the SD card root and install it from Settings. See Development quick start below.

Bump version in platformio.ini, then push a vX.Y.Z tag. The release workflow builds gh_release and publishes the GitHub release that readers check for updates.

Convert your own TTF/OTF files into .cpfont files that load from the SD card. No firmware reflash is needed.

1. Go to https://crosspointreader.com/fonts and open the "SD-card font builder" form.
2. Upload up to four styles (regular, bold, italic, bold-italic), set the family name, point sizes, and Unicode range.
3. Download the generated .cpfont files.
4. Copy them to your SD card under /fonts/YourFont/ (or /.fonts/YourFont/ to hide the folder).
5. Select the font on the device from the font settings.

Conversion runs the firmware repo's lib/EpdFont/scripts/fontconvert_sdcard.py script unmodified, so output matches a local host build.

• User Guide
• Web server usage
• Web server endpoints
• Bilingual book pipeline
• Project scope
• Contributing docs

• pioarduino or VS Code + pioarduino plugin
• Python 3.8+
• clang-format 21
• USB-C cable supporting data transfer

git clone --recursive https://github.com/puritysb/pocket-daily-firmware
cd pocket-daily-firmware

# keep the reader-engine source available for controlled merges
git remote add upstream https://github.com/crosspoint-reader/crosspoint-reader.git

# if cloned without --recursive:
git submodule update --init --recursive

./scripts/pio.sh run --target upload

./bin/clang-format-fix
./scripts/pio.sh check -e default
./scripts/pio.sh run -e default
cmake -S test -B build/host-tests -DCMAKE_BUILD_TYPE=Release
cmake --build build/host-tests
ctest --test-dir build/host-tests --output-on-failure -j

After flashing the new features, it’s recommended to capture detailed logs from the serial port.

First, make sure all required Python packages are installed:

python3 -m pip install pyserial colorama matplotlib

After that run the script:

# For Linux
# This was tested on Debian and should work on most Linux systems.
python3 scripts/debugging_monitor.py

# For macOS
python3 scripts/debugging_monitor.py /dev/cu.usbmodem2101

Minor adjustments may be required for Windows.

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.

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_<hash>/         # one directory per book, named by content hash
│   ├── progress.bin     # reading position (chapter, page, etc.)
│   ├── cover.bmp        # generated cover image
│   ├── book.bin         # metadata: title, author, spine, TOC
│   ├── css_rules.cache  # parsed CSS rule cache
│   ├── img_*            # rendered image cache files
│   └── sections/        # per-chapter layout cache
│       ├── 0.bin
│       ├── 1.bin
│       └── ...
├── settings.json        # device settings
├── state.json           # resume/runtime state
└── recent.json          # recent books list

Removing /.crosspoint clears all cached metadata and forces a full regeneration on next open. Book deletes, overwrites, and moves done through the firmware or web UI clear or re-key matching caches; manual SD-card edits may leave stale cache directories behind.

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

Contributions are welcome. If you're new to the codebase, start with the contributing docs. For things to work on, check the ideas discussion board — leave a comment before starting so we don't duplicate effort.

Everyone here is a volunteer, so please be respectful and patient. For governance and community expectations, see GOVERNANCE.md.

One of the best things about open source is that anyone can take the code in a different direction. If you need something outside CrossPoint's scope, check out the community forks:

• CrossInk — Typography and reading tracking: Bionic Reading (bolds word stems to create fixation points), guide dots between words, improved paragraph indents, and replaces the default fonts with ChareInk/Lexend/Bitter.

• papyrix-reader — Adds FB2 and MD format support. Actively maintained with Arabic script support. Custom themes via SD card.

• crosspet — A Vietnamese fork that adds a Tamagotchi-style virtual chicken that grows based on your reading milestones (pages read, streaks, care). Also: Flashcards, Weather, Pomodoro timer, and mini-games.

• crosspoint-reader-cjk — Purpose-built for Chinese, Japanese, and Korean reading.

• inx — Completely reimagines the user interface with tabbed navigation.

• PlusPoint — custom JS apps support. (Unmaintained)

• crosspoint-reader-papers3 — Crosspoint port for M5Stack Paper S3.

• t5s3-reader — Crosspoint port for LilyGo T5 ePaper S3 / T5S3 4.7-inch e-paper device.

Note: Many of these features will make their way into CrossPoint over time. We maintain a slower pace to ensure rock-solid stability and squash bugs before they reach your device.

Want to build your own device? Be sure to check out the de-link project.

CrossPoint Reader is not affiliated with Xteink or any device manufacturer.

Huge shoutout to diy-esp32-epub-reader, which inspired this project.