{"id":51479291,"url":"https://github.com/sfoulad/foulad-eink","last_synced_at":"2026-07-26T11:00:45.264Z","repository":{"id":369027941,"uuid":"1287699438","full_name":"sfoulad/foulad-eink","owner":"sfoulad","description":"Arabic-first e-reader firmware for Xteink X4/X3 — fork of CrossPoint Reader with full Arabic UI, RTL, Naskh reading font, reading stats, and Foulad eBooks OPDS integration","archived":false,"fork":false,"pushed_at":"2026-07-21T22:52:12.000Z","size":159627,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-07-22T00:31:24.821Z","etag":null,"topics":["arabic","e-reader","eink","epub","esp32-c3","firmware","opds","rtl"],"latest_commit_sha":null,"homepage":"https://foulad.one","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sfoulad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/README.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://app.royalty.dev/crosspoint-reader/crosspoint-reader"]}},"created_at":"2026-07-02T23:46:57.000Z","updated_at":"2026-07-21T22:52:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sfoulad/foulad-eink","commit_stats":null,"previous_names":["sfoulad/foulad-eink"],"tags_count":192,"template":false,"template_full_name":null,"purl":"pkg:github/sfoulad/foulad-eink","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfoulad%2Ffoulad-eink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfoulad%2Ffoulad-eink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfoulad%2Ffoulad-eink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfoulad%2Ffoulad-eink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sfoulad","download_url":"https://codeload.github.com/sfoulad/foulad-eink/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfoulad%2Ffoulad-eink/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35911748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arabic","e-reader","eink","epub","esp32-c3","firmware","opds","rtl"],"created_at":"2026-07-07T00:01:36.751Z","updated_at":"2026-07-26T11:00:45.253Z","avatar_url":"https://github.com/sfoulad.png","language":"C","funding_links":["https://app.royalty.dev/crosspoint-reader/crosspoint-reader"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e📖 Foulad eInk\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003cb\u003eAn e-reader built around Arabic.\u003c/b\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Foulad eInk is a free, open-source firmware for Xteink e-ink readers — a fork of\n  \u003ca href=\"https://github.com/crosspoint-reader/crosspoint-reader\"\u003eCrossPoint Reader\u003c/a\u003e, rebuilt so Arabic, and the\n  languages that share its script, read the way they're supposed to. It updates itself over the air, straight from\n  this repository.\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ci\u003e📱 Runs on Xteink \u003ca href=\"https://www.xteink.com/products/xteink-x4\"\u003eX4\u003c/a\u003e and\n  \u003ca href=\"https://www.xteink.com/products/xteink-x3\"\u003eX3\u003c/a\u003e.\u003c/i\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/sfoulad/foulad-eink/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/sfoulad/foulad-eink?label=release\u0026color=blue\u0026style=flat-square\" alt=\"Latest release\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/sfoulad/foulad-eink?color=brightgreen\u0026style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Arabic-100%25-orange?style=flat-square\" alt=\"Arabic support\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/updates-over--the--air-blueviolet?style=flat-square\" alt=\"OTA updates\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\n    ✨ \u003ca href=\"#highlights\"\u003eHighlights\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n    📋 \u003ca href=\"#what-can-it-do\"\u003eEverything it does\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n    🚀 \u003ca href=\"#install-firmware\"\u003eInstall\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n    🔤 \u003ca href=\"#custom-sd-card-fonts\"\u003eFonts\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n    🛠️ \u003ca href=\"#development\"\u003eDevelopment\u003c/a\u003e\n  \u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/home.png\" width=\"380\" alt=\"Foulad eInk home screen\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e🏠 Everything, from one screen.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Pick up where you left off, browse your library, and check your reading stats — a home screen designed to get out\n  of your way.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/reading.png\" width=\"380\" alt=\"Reading the Quran on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e🕌 Reads Arabic like it was made for it.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Correct letter shaping, right-to-left layout, and a bundled Quran in full Uthmani script with proper ayah markers.\n  The same engine reads Persian, Ottoman Turkish, and Kurdish text correctly too.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/fonts/font-browser.png\" width=\"380\" alt=\"Font Browser on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e🔤 Download fonts, Arabic and English, on the go.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Browse and download font families for both scripts straight over Wi-Fi — no SD card swap, no computer required.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/stats.png\" width=\"380\" alt=\"Reading statistics on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e📊 See your reading, at a glance.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Daily streaks, a monthly heatmap, and per-book progress — set a daily goal and watch it add up.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/books-apps/books-apps.png\" width=\"380\" alt=\"My Books \u0026 Apps grid on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e📚 Books and apps, in one place.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Every book sits in the same grid as Tasbih, Stop Watch, Gym, and Games — no separate launcher, no digging through menus.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/settings-apps/settings-apps.png\" width=\"380\" alt=\"Settings — Apps tab on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e🎛️ Enable and disable apps, to taste.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Don't want Games or Gym cluttering your library? Turn off whatever you don't use, right from Settings — Apps.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/games/games-slideshow-v2.gif\" width=\"380\" alt=\"Snake, Tetris, Sudoku, and Maze on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e🎮 Four games, zero downloads.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Snake, Tetris, Sudoku, and Maze, built right into the firmware — pinned in My Books \u0026 Apps for whenever you want a\n  break from reading.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/gym/gym-slideshow.gif\" width=\"380\" alt=\"Gym workout planner on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e🏋️ Plan your week, log every set.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  A 7-day workout split with a day at a glance — muscle group, exercise count, rest days — then a per-set logger\n  that remembers your last weight and reps, and shows the exercise photo right on the page.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/stopwatch/stopwatch.png\" width=\"380\" alt=\"Stop Watch on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e⏱️ Every second, on the dot.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Start, pause, and lap tracking with a Casio-style MM:SS:CS display — pinned right alongside your books.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/tasbih/tasbih.png\" width=\"380\" alt=\"Tasbih dhikr counter on Foulad eInk\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e📿 Count your dhikr, track your best day.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Either side button counts — no need to look away from your recitation — with a running total for the year and\n  your all-time best day, plus a flash at 33, 99, and 100.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/images/devices.png\" width=\"700\" alt=\"Foulad eInk running on Xteink X4 and X3\"\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003e📱 One firmware, both devices.\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Foulad eInk runs natively on the Xteink X4 and X3, adapting to each device's screen and buttons automatically.\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n---\n\n\u003ch2 id=\"highlights\"\u003e✨ Highlights\u003c/h2\u003e\n\n- 🕌 **A fully Arabic interface** — mirrored, translated, and with page-turn buttons that swap direction automatically so \"forward\" is always where your thumb expects it.\n- 🌍 **Reads Arabic, Persian, Ottoman Turkish, and Kurdish correctly** — proper letter shaping and right-to-left text, everywhere it shows up.\n- 📖 **A bundled Quran** — Uthmani script, ayah and surah markers, and justified lines that stretch the way a real mushaf does.\n- ☁️ **Foulad eBooks** — connect to a self-hosted library and browse it as a cover grid, right from the home screen.\n- 📊 **Reading stats** — streaks, a monthly heatmap, and per-book progress.\n- 🎮 **Four built-in games** — Snake, Tetris, Sudoku, and Maze.\n- 🏋️ **Gym workout planner** — a 7-day split, per-set weight/reps logging, and exercise photos, synced from a shared catalog.\n- 📿 **Tasbih counter, Stop Watch, and Dictionary** — a dhikr counter with daily/yearly stats, a lap-tracking stopwatch, and offline word lookup right from the reading drawer.\n- 🎨 **A live Dashboard screensaver** — clock, battery, current book, streak, and a rotating ayah, instead of a static sleep screen.\n- 🔋 **Free, open source, and self-updating** — flash it once, and it keeps itself up to date over Wi-Fi from here on out.\n\n---\n\n\u003ch2 id=\"what-can-it-do\"\u003e📋 What can it do?\u003c/h2\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSee the full feature list\u003c/b\u003e — click to expand\u003c/summary\u003e\n\n\u003cbr\u003e\n\n**🏠 Home \u0026 library**\n\n- A hero card for the book you're reading (cover, progress bar, time read, and estimated time left), a \"My Books\" row of recent covers, and a bottom icon menu with physical-button hints.\n- Folder browser, hidden-file toggle, long-press delete, recent books with cover thumbnails, SD-cache management.\n- Native handling for `.epub`, `.xtc/.xtch`, `.txt`, and `.bmp`.\n\n**📖 Reading**\n\n- 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, and KOReader progress sync.\n- Custom fonts — install your favorite fonts on the SD card.\n- Tilt page turn (X3 only).\n- Offline dictionary — select a word while reading and look it up right from the drawer, no connection needed once a dictionary is installed.\n\n**📊 Reading statistics**\n\n- Total and per-day reading time, a monthly heatmap of your reading activity, per-book time tracking, and a configurable daily reading goal.\n- A live Dashboard sleep screen — clock, battery, current book and progress, reading streak, and a rotating Quran ayah, as an alternative to a static cover/blank sleep screen.\n\n**🧩 Apps**\n\n- Snake, Tetris, Sudoku, and Maze, pinned as their own tile in your library — no setup, nothing to install.\n- **Gym**: a 7-day workout split shown as a day-at-a-glance grid (muscle group, exercise count, rest days), an exercise picker synced from a shared catalog, and a per-set logger that remembers your last weight/reps and shows the exercise photo on the page.\n- **Tasbih**: a dhikr counter with a top-count leaderboard and daily/yearly totals.\n- **Stop Watch**: start/pause, lap tracking, and a MM:SS:CS Casio-style display.\n\n**☁️ Foulad eBooks**\n\n- A dedicated home-screen entry that opens a self-hosted OPDS catalog directly — cover-grid browsing, search, pagination, and one-tap downloads that keep the catalog's cover art. No manual server setup beyond a one-time username/password prompt on first use.\n\n**📶 Wireless**\n\n- File transfer web UI\n- EPUB Optimizer\n- Web settings UI/API (edit many device settings from a browser)\n- WebSocket fast uploads\n- WebDAV handler\n- AP mode (hotspot) and STA mode (join existing Wi-Fi), both with QR helpers\n- Calibre wireless connect flow\n- OPDS browser with saved servers (up to 8), search, pagination, and direct download\n- OTA update checks and installs from this repo's GitHub releases — the updater restarts the device into a clean-memory state before downloading, so updates install reliably even after long reading sessions\n\n**🎨 Customization**\n\n- Sleep screen modes, front/side button remapping, status bar controls, power-button behavior, refresh cadence, sunlight fading fix, and more.\n\n**⚙️ Under the hood**\n\n- Lean firmware, trimmed to the two languages it's actually for (English and Arabic) and a curated font set (Noto Serif for Latin reading, Noto Naskh Arabic for Arabic) — the whole image is a few MB, which keeps OTA updates fast.\n- Full English and Arabic UI localization with complete RTL support.\n\n\u003c/details\u003e\n\n---\n\n## 🔒 USB-locked devices\n\nSome Xteink units bought from third-party stores (like AliExpress) ship with USB flashing locked from the factory.\nIf yours is one of them, you'll need the free **Xteink Unlocker** tool before you can flash this firmware — it's\nmaintained by the upstream CrossPoint project, not this fork.\n\n\u003e [!NOTE]\n\u003e **Bought directly from xteink.com?** You can skip this — those units aren't locked.\n\u003e\n\u003e **Not sure if yours is locked?** Just try the [web installer](#install-firmware) below first. If your browser\n\u003e can't find the device, then it's worth grabbing the unlocker.\n\n\u003e [!WARNING]\n\u003e If you do need the unlocker, only flash this firmware as a **\"Custom .bin\"** — the tool's built-in options don't\n\u003e include this fork. Flashing the wrong thing on a locked device can leave it stuck with no way to recover it, so\n\u003e follow the [Install firmware](#install-firmware) steps below exactly. Once this firmware is on the device, every\n\u003e future update comes safely over Wi-Fi — no unlocker needed again.\n\n---\n\n\u003ch2 id=\"install-firmware\"\u003e🚀 Install firmware\u003c/h2\u003e\n\n### 🌐 Easiest: web installer\n\n1. Connect your device via USB-C and wake it up.\n2. Download `firmware.bin` from the [Releases](https://github.com/sfoulad/foulad-eink/releases) page.\n3. Open the [web flasher](https://crosspointreader.com/#flash-tools), pick your device (X3 or X4), choose **Custom\n   .bin**, and upload the file. That's it.\n\n\u003e [!TIP]\n\u003e **After that first flash**, you'll never need a cable again — updates install straight from the device via\n\u003e Settings → OTA Update.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e💻 Prefer the command line?\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n1. Install [`esptool`](https://github.com/espressif/esptool):\n\n   ```bash\n   pip install esptool\n   ```\n\n2. Download `firmware.bin` from the [Releases](https://github.com/sfoulad/foulad-eink/releases) page.\n3. Connect your device via USB-C.\n4. Find the device port. On Linux, run `dmesg` after connecting. On macOS:\n\n   ```bash\n   log stream --predicate 'subsystem == \"com.apple.iokit\"' --info\n   ```\n\n5. Flash it:\n\n   ```bash\n   esptool.py --chip esp32c3 --port /dev/ttyACM0 --baud 921600 write_flash 0x10000 /path/to/firmware.bin\n   ```\n\n   Adjust `/dev/ttyACM0` to match your system.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔧 Building it yourself?\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\nSee [Development](#development) below.\n\n\u003c/details\u003e\n\n---\n\n\u003ch2 id=\"custom-sd-card-fonts\"\u003e🔤 Custom SD-card fonts\u003c/h2\u003e\n\nWant a different look for your books? Convert any TTF/OTF font into a device-ready file — no reflashing needed.\n\n1. Open the [SD-card font builder](https://crosspointreader.com/fonts).\n2. Upload up to four styles (regular, bold, italic, bold-italic), and set a name, sizes, and character range.\n3. Download the generated `.cpfont` files.\n4. Copy them to your SD card under `/fonts/YourFont/` (or `/.fonts/YourFont/` to keep the folder hidden).\n5. Pick the font on the device from the font settings.\n\n### 🕌 Arabic, out of the box\n\nBook titles, author names, filenames, chapter titles, and full EPUB body text render Arabic script correctly with no\nsetup at all — proper letter shaping, right-to-left order, and the extra letters Persian, Ottoman Turkish, and\nKurdish add on top of the Arabic alphabet. Two Arabic fonts already ship in the firmware:\n\n- **Noto Naskh Arabic** for reading, at every text size.\n- **Noto Sans Arabic** for menus and titles.\n\nPrefer a different Arabic look? You can swap in your own font too:\n\n\u003cdetails\u003e\n\u003csummary\u003eShow me how\u003c/summary\u003e\n\n\u003cbr\u003e\n\n1. Download an Arabic-capable TTF/OTF (e.g. [IBM Plex Sans Arabic](https://fonts.google.com/specimen/IBM+Plex+Sans+Arabic)).\n2. Convert it locally — the hosted web builder doesn't know about this fork's Arabic support, so run the script\n   directly:\n\n   ```bash\n   cd lib/EpdFont/scripts\n   python3 fontconvert_sdcard.py --intervals reading,arabic --reposition-marks --name \"PlexArabic\" /path/to/IBMPlexSansArabic-Regular.ttf\n   ```\n\n   `--reposition-marks` is required for correct diacritics (harakat/tashkeel). Most Arabic fonts position\n   combining marks using an OpenType table (GPOS) that this converter doesn't read; without the flag, marks\n   commonly render overlapping each other or over the wrong letter.\n\n3. Copy the generated `.cpfont` files to your SD card under `/fonts/PlexArabic/` (or `/.fonts/PlexArabic/`).\n4. On the device: **Settings → Reader → Arabic Font** → select the family you just installed. Selecting the\n   built-in font again reverts to it.\n\n\u003c/details\u003e\n\n---\n\n## 📚 Documentation\n\n| | |\n|---|---|\n| 📗 [User Guide](./USER_GUIDE.md) | How to use the device day to day |\n| 🌐 [Web server usage](./docs/webserver.md) | Using the built-in file-transfer/settings web UI |\n| 🔌 [Web server endpoints](./docs/webserver-endpoints.md) | API reference for the web server |\n| 🗺️ [Project scope](./SCOPE.md) | What this fork will and won't take on |\n\n---\n\n\u003ch2 id=\"development\"\u003e🛠️ Development\u003c/h2\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePrerequisites, setup, and build commands\u003c/b\u003e — click to expand\u003c/summary\u003e\n\n\u003cbr\u003e\n\n### Prerequisites\n\n- [pioarduino](https://github.com/pioarduino/pioarduino) or VS Code + pioarduino plugin\n- Python 3.8+\n- `clang-format` 21\n- USB-C cable supporting data transfer\n\n### Setup\n\n```bash\ngit clone --recursive https://github.com/sfoulad/foulad-eink\ncd foulad-eink\n\n# if cloned without --recursive:\ngit submodule update --init --recursive\n```\n\n### Build / flash / monitor\n\n```bash\npio run --target upload\n```\n\n### Pre-commit checks\n\n```bash\n./bin/clang-format-fix\npio check -e default\npio run -e default\npio run -t unit-tests\n```\n\n### Debugging\n\nAfter flashing new changes, it's worth capturing detailed logs from the serial port. First, install the required\nPython packages:\n\n```bash\npython3 -m pip install pyserial colorama matplotlib\n```\n\nThen run the monitor script:\n\n```bash\n# Linux (tested on Debian, should work on most distros)\npython3 scripts/debugging_monitor.py\n\n# macOS\npython3 scripts/debugging_monitor.py /dev/cu.usbmodem2101\n```\n\nMinor adjustments may be needed on Windows.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e⚙️ How the caching works internally\u003c/b\u003e — for the curious\u003c/summary\u003e\n\n\u003cbr\u003e\n\nThis firmware is aggressive about caching data down to the SD card to keep RAM usage low — the ESP32-C3 only has\n~380KB of usable RAM, so most of the internal design works around that constraint.\n\nThe first time a book's chapters are loaded, they're cached to the SD card; subsequent loads are served from the\ncache. The cache directory lives at `.crosspoint` on the SD card (an internal path inherited from upstream, unrelated\nto this fork's name):\n\n```text\n.crosspoint/\n├── epub_\u003chash\u003e/         # one directory per book, named by content hash\n│   ├── progress.bin     # reading position (chapter, page, etc.)\n│   ├── cover.bmp        # generated cover image\n│   ├── book.bin         # metadata: title, author, spine, TOC\n│   ├── css_rules.cache  # parsed CSS rule cache\n│   ├── img_*            # rendered image cache files\n│   └── sections/        # per-chapter layout cache\n│       ├── 0.bin\n│       ├── 1.bin\n│       └── ...\n├── settings.json        # device settings\n├── state.json           # resume/runtime state\n└── recent.json          # recent books list\n```\n\nRemoving `/.crosspoint` clears all cached metadata and forces a full regeneration on next open. Book deletes,\noverwrites, and moves done through the firmware or web UI clear or re-key matching caches; manual SD-card edits may\nleave stale cache directories behind.\n\nFor more detail on the internal file formats, see the [file formats document](./docs/file-formats.md).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔄 Staying up to date with upstream\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\nThis fork tracks [crosspoint-reader/crosspoint-reader](https://github.com/crosspoint-reader/crosspoint-reader) as a\ngit remote named `upstream`. To pull in new upstream releases:\n\n```bash\ngit fetch upstream\ngit merge upstream/develop\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\n    Not affiliated with Xteink or any device manufacturer. Based on\n    \u003ca href=\"https://github.com/crosspoint-reader/crosspoint-reader\"\u003eCrossPoint Reader\u003c/a\u003e, MIT licensed, which\n    itself credits \u003ca href=\"https://github.com/atomic14/diy-esp32-epub-reader\"\u003ediy-esp32-epub-reader\u003c/a\u003e as its\n    original inspiration.\n  \u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfoulad%2Ffoulad-eink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsfoulad%2Ffoulad-eink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfoulad%2Ffoulad-eink/lists"}