FAQ & Known Limitations

CrossPet does not modify the ESP32-C3 bootloader or flash partition table layout used by the official firmware. You can revert to official firmware at any time. That said, flashing any custom firmware carries inherent risk — a power failure mid-flash can corrupt the device. Always use a reliable USB cable and cable connection, and keep the device plugged in throughout the process.

Almost certainly yes — modifying device firmware typically voids the manufacturer warranty. CrossPet is community-maintained software with no affiliation to Xteink. Proceed at your own risk and with that understanding.

If your device has WiFi configured, CrossPet can update itself over-the-air: go to Settings → System → Check for Updates. Alternatively, re-flash using the browser installer on this page or the PlatformIO CLI. OTA updates preserve your settings and SD card contents.

Yes. Download the official firmware from xteink.dve.al and flash it using their tool or esptool.py. Your SD card books are unaffected. If the device fails to boot, hold the Up side button while connecting USB to enter bootloader mode.

Yes — CrossPet is released under the GPL license. The full source is on GitHub. Contributions are welcome: bug reports, pull requests, translations, and feature ideas. Please read the contributing guide in the repository before submitting a PR.

CrossPet supports EPUB 2 and EPUB 3 with inline images. Plain text (.txt) files are also supported. PDF, MOBI, AZW, and CBZ are not supported. For the best experience, use DRM-free EPUB files from sources like Project Gutenberg, Standard Ebooks, or your local library's OverDrive/Libby collection (after removing DRM on books you own).

Three methods: (1) WiFi upload — connect to the same network, open the device's IP in your browser, drag-and-drop EPUB files. (2) Calibre — CrossPet exposes a Calibre Content Server-compatible endpoint; add the device in Calibre's "Send to device" menu. (3) SD card — eject the SD card, copy EPUB files to the /books/ directory on a computer, reinsert.

Yes, via KOReader Sync. Set up a KOReader Sync server (self-hosted or community instance) in Settings → Sync. CrossPet will push your position after each reading session and pull it on open, so you can switch between the X4 and KOReader on Android/iOS seamlessly.

The first time you open a book, CrossPet parses the EPUB, runs the full layout engine for every section, and writes binary cache files to the SD card. This can take 10–60 seconds for large books. Subsequent opens are near-instant because they read pre-computed layout from the cache. If you change font size or family, the cache is invalidated and regenerated automatically.

CrossPet supports JPEG (baseline) and PNG images embedded in EPUB files. Images are decoded, scaled to fit the viewport, and cached as pre-scaled bitmaps on the SD card. Progressive JPEG is not supported — the ESP32-C3's limited RAM cannot hold the full image in memory required for progressive decoding. If a book's images don't display, they are likely progressive JPEGs; re-export them as baseline JPEG or PNG using any image editor.

The ESP32-C3 supports 2.4GHz 802.11 b/g/n only. 5GHz networks are not supported. WPA2-Personal and WPA3 are supported. Enterprise (WPA2-Enterprise / 802.1X) networks are not supported. Captive portal networks (hotels, airports) will not work.

Make sure the device is awake (press the power button) before connecting USB — the serial interface is inactive in deep sleep. Also verify you're using a data-capable USB-C cable, not a charge-only cable. On Linux, you may need to add yourself to the dialout group: sudo usermod -a -G dialout $USER and log out/in.

Only BLE HID keyboards are supported — the ESP32-C3 has no Classic Bluetooth. Most modern compact keyboards advertised as "BLE" or "Bluetooth 5" work. Older keyboards that use Bluetooth Classic (pre-BT4.0) will not connect. Use the BLE pairing screen under Tools → BLE Remote to scan for and pair a keyboard.

Battery life depends heavily on WiFi usage and sleep screen type. With WiFi off and a static sleep screen, expect 3–6 weeks of standby. Active reading (frequent page turns) consumes more — e-ink only draws power during refresh, so reading speed matters less than page-turn frequency. WiFi transfers and OTA updates are the largest battery consumers; avoid leaving WiFi on continuously.

The Virtual Pet is a pixel-art companion that lives on your sleep screen and in the Tools menu. It tracks your reading sessions through the Reading Stats system — the more you read, the more your pet grows and evolves. Your pet's mood and appearance reflect your recent reading activity; long reading gaps will make it listless. The pet is purely cosmetic and does not affect firmware performance.

CrossPet tracks: today's reading time, all-time total reading time, number of reading sessions, books finished, current reading streak (consecutive days), and longest streak ever. Stats are stored locally in .crosspoint/reading_stats.bin on your SD card — no data is sent anywhere. The Reading Stats sleep screen displays a dashboard of these figures when your device is idle.

The weather widget fetches forecast data from Open-Meteo, a free open-source weather API that requires no API key. Your approximate coordinates are configured in Settings → Weather. Data is cached on the SD card and refreshed when WiFi is available. The current temperature appears in the header bar and on the clock sleep screen.

Most CrossPet features (weather, pet, games) only load when you actively navigate to them — they don't run in the background or consume RAM while you're reading. The reading stats system does record session start/end, but its memory footprint is minimal. If you need the absolute leanest experience, the slim build environment strips serial logging and produces the smallest possible binary.

Not noticeably. CrossPet uses the same deep sleep mechanism as the official firmware — the ESP32-C3 draws near-zero current when idle. Additional features like weather, games, and the virtual chicken only consume power when you actively use them. The reading stats system writes to SD only on session start/end (two brief writes per reading session), which has negligible battery impact. If you use WiFi-dependent features (weather, OTA updates) frequently, that will drain battery faster — but that's WiFi usage, not CrossPet overhead. In practice, standby and reading battery life are virtually identical to official firmware.

Check that: (1) your phone/computer is on the same 2.4GHz network as the device, (2) the device shows a WiFi icon in the header bar indicating it's connected, (3) you're using the IP address shown in Settings → Network → Device IP, not a hostname. Some routers block device-to-device traffic — try from a different device or temporarily disable AP isolation in your router settings.

Large EPUB files (50MB+) can time out on slow WiFi connections. Try moving the device closer to your router. If Calibre uploads stall, switch to the browser drag-and-drop method. For very large files, copying directly to the SD card on a computer is the most reliable option.

Hold the Up side button while connecting USB to force the ESP32-C3 into bootloader mode, bypassing the application. Then re-flash from a clean build. If the issue persists, try the pio run -t erase command to wipe flash before flashing — this resets all settings but guarantees a clean state.

Delete the book's cache directory: on the SD card, find .crosspoint/epub_<hash>/ and delete the entire folder, then open the book again. If the crash repeats, the EPUB may contain malformed HTML or CSS that the parser can't handle. Open an issue on GitHub with the book title (if DRM-free and publicly available) or a minimal repro.