passes = 1

more resync
move requestResync to HAL
2026-04-29 10:26:52 -07:00 · 2026-02-16 21:48:09 +01:00 · 2026-02-16 11:13:34 +01:00 · 2026-02-16 10:56:40 +01:00 · 2026-02-15 21:14:52 -05:00 · 2026-02-15 19:58:37 -05:00
261 changed files with 87400 additions and 22085 deletions
@@ -1,10 +1,55 @@
-name: CI
-'on':
+name: CI (build)
+
+on:
  push:
    branches: [master]
  pull_request:

+permissions:
+  contents: read
+
 jobs:
+  clang-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install clang-format-21
+        run: |
+          wget https://apt.llvm.org/llvm.sh
+          chmod +x llvm.sh
+          sudo ./llvm.sh 21
+          sudo apt-get update
+          sudo apt-get install -y clang-format-21
+
+      - name: Run clang-format
+        run: |
+          PATH="/usr/lib/llvm-21/bin:$PATH" ./bin/clang-format-fix
+          git diff --exit-code || (echo "Please run 'bin/clang-format-fix' to fix formatting issues" && exit 1)
+
+  cppcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install PlatformIO Core
+        run: pip install --upgrade platformio
+
+      - name: Run cppcheck
+        run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+
  build:
    runs-on: ubuntu-latest
    steps:
@@ -19,19 +64,46 @@ jobs:
      - name: Install PlatformIO Core
        run: pip install --upgrade platformio

-      - name: Install clang-format-21
-        run: |
-          wget https://apt.llvm.org/llvm.sh
-          chmod +x llvm.sh
-          sudo ./llvm.sh 21
-          sudo apt-get update
-          sudo apt-get install -y clang-format-21
-
-      - name: Run cppcheck
-        run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
-
-      - name: Run clang-format
-        run: PATH="/usr/lib/llvm-21/bin:$PATH" ./bin/clang-format-fix && git diff --exit-code || (echo "Please run 'bin/clang-format-fix' to fix formatting issues" && exit 1)
-
      - name: Build CrossPoint
-        run: pio run
+        run: |
+          set -euo pipefail
+          pio run | tee pio.log
+
+      - name: Extract firmware stats
+
+        run: |
+          set -euo pipefail
+          ram_line="$(grep -E "RAM:\\s" -m1 pio.log || true)"
+          flash_line="$(grep -E "Flash:\\s" -m1 pio.log || true)"
+          echo "ram_line=${ram_line}" >> "$GITHUB_OUTPUT"
+          echo "flash_line=${flash_line}" >> "$GITHUB_OUTPUT"
+          {
+            echo "## Firmware build stats"
+            if [ -n "$ram_line" ]; then echo "- ${ram_line}"; else echo "- RAM: not found"; fi
+            if [ -n "$flash_line" ]; then echo "- ${flash_line}"; else echo "- Flash: not found"; fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload firmware.bin artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: firmware.bin
+          path: .pio/build/default/firmware.bin
+          if-no-files-found: error
+
+  # This job is used as the PR required actions check, allows for changes to other steps in the future without breaking
+  # PR requirements.
+  test-status:
+    name: Test Status
+    needs:
+      - build
+      - clang-format
+      - cppcheck
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail because needed jobs failed
+        # Fail if any job failed or was cancelled (skipped jobs are ok)
+        if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
+        run: exit 1
+      - name: Success
+        run: exit 0
@@ -0,0 +1,27 @@
+name: "PR Formatting"
+
+on:
+  pull_request:
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - edited
+
+permissions:
+  statuses: write
+
+jobs:
+  title-check:
+    name: Title Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        with:
+          egress-policy: audit
+
+      - name: Check PR Title
+        uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -0,0 +1,48 @@
+name: Compile Release Candidate
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-release-candidate:
+    if: startsWith(github.ref_name, 'release/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+          key: ${{ runner.os }}-pio
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install PlatformIO Core
+        run: pip install --upgrade platformio
+
+      - name: Extract env
+        run: |
+          echo "SHORT_SHA=${GITHUB_SHA::7}" >> $GITHUB_ENV
+          echo "BRANCH_SUFFIX=${GITHUB_REF_NAME#release/}" >> $GITHUB_ENV
+
+      - name: Build CrossPoint Release Candidate
+        env:
+          CROSSPOINT_RC_HASH: ${{ env.SHORT_SHA }}
+        run: pio run -e gh_release_rc
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: CrossPoint-RC-${{ env.BRANCH_SUFFIX }}
+          path: |
+            .pio/build/gh_release_rc/bootloader.bin
+            .pio/build/gh_release_rc/firmware.bin
+            .pio/build/gh_release_rc/firmware.elf
+            .pio/build/gh_release_rc/firmware.map
+            .pio/build/gh_release_rc/partitions.bin
@@ -4,3 +4,9 @@
 .vscode
 lib/EpdFont/fontsrc
 *.generated.h
+.vs
+build
+**/__pycache__/
+/compile_commands.json
+/.cache
+/notes.md
@@ -0,0 +1,38 @@
+# Project Governance & Community Principles
+
+CrossPoint Reader is a community-driven, open-source project. Our goal is to provide a high-quality, open-source
+firmware alternative for the Xteink X4 hardware. To keep this project productive and welcoming as we grow, we ask all
+contributors to follow these principles.
+
+### 1. The "Human First" Rule
+Technical discussions can get heated, but they should never be personal.
+- **Assume good intent:** We are all volunteers working on this in our free time. If a comment seems abrasive, assume
+  it’s a language barrier or a misunderstanding before taking offense.
+- **Focus on the code, not the person:** Critique the implementation, the performance, or the UX. Never the intelligence
+  or character of the contributor.
+- **Inflammatory language:** Personal attacks, trolling, or exclusionary language (based on race, gender, background,
+  etc.) are not welcome here and will be moderated.
+
+### 2. A "Do-ocracy" with Guidance
+CrossPoint thrives because people step up to build what they want to see.
+- If you want a feature, the best way to get it is to start an
+  [Idea Discussion](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas) or open a PR.
+- If you want to report a bug, check for duplicates and create an
+  [Issue](https://github.com/crosspoint-reader/crosspoint-reader/issues).
+- While we encourage experimentation, the maintainers reserve the right to guide the project’s technical direction to
+  ensure stability on the ESP32-C3’s constrained hardware.
+- For more guidance on the scope of the project, see the [SCOPE.md](SCOPE.md) document.
+
+### 3. Transparent Communication
+To keep the project healthy, we keep our "work" in the open.
+- **Public by Default:** All technical decisions and project management discussions happen in GitHub Issues, Pull
+  Requests, or the public Discussions tab.
+- **Clarity in Writing:** Because we have a global community with different levels of English proficiency, please be as
+  explicit and clear as possible in your PR descriptions and bug reports.
+
+### 4. Moderation & Safety
+The maintainers are responsible for keeping the community a safe place to contribute.
+- We reserve the right to hide comments, lock threads, or block users who repeatedly violate these principles or engage
+  in harassment.
+- **Reporting:** If you feel you are being harassed or see behavior that is damaging the community, please reach out
+  privately to @daveallie.
@@ -41,7 +41,11 @@ This project is **not affiliated with Xteink**; it's built as a community projec
  - [ ] Full UTF support
 - [x] Screen rotation

-See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint.
+Multi-language support: Read EPUBs in various languages, including English, Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Polish, Swedish, Norwegian, [and more](./USER_GUIDE.md#supported-languages).
+
+See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint. 
+
+For more details about the scope of the project, see the [SCOPE.md](SCOPE.md) document.

 ## Installing

@@ -56,7 +60,7 @@ back to the other partition using the "Swap boot partition" button here https://
 ### 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](https://github.com/daveallie/crosspoint-reader/releases)
+2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/crosspoint-reader/crosspoint-reader/releases)
 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
@@ -80,7 +84,7 @@ See [Development](#development) below.
 CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:

 ```
-git clone --recursive https://github.com/daveallie/crosspoint-reader
+git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader

 # Or, if you've already cloned without --recursive:
 git submodule update --init --recursive
@@ -93,6 +97,25 @@ Connect your Xteink X4 to your computer via USB-C and run the following command.
 ```sh
 pio run --target upload
 ```
+### Debugging
+
+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:
+
+```python
+python3 -m pip install pyserial colorama matplotlib
+```
+after that run the script:
+```sh
+# 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.

 ## Internals

@@ -131,9 +154,12 @@ For more details on the internal file structures, see the [file formats document

 Contributions are very welcome!

-If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/daveallie/crosspoint-reader/discussions/categories/ideas).
+If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/crosspoint-reader/crosspoint-reader/discussions/categories/ideas).
 If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.

+Everyone here is a volunteer, so please be respectful and patient. For more details on our goverance and community 
+principles, please see [GOVERNANCE.md](GOVERNANCE.md).
+
 ### To submit a contribution:

 1. Fork the repo
@@ -0,0 +1,48 @@
+# Project Vision & Scope: CrossPoint Reader
+
+The goal of CrossPoint Reader is to create an efficient, open-source reading experience for the Xteink X4. We believe a
+dedicated e-reader should do one thing exceptionally well: **facilitate focused reading.**
+
+## 1. Core Mission
+
+To provide a lightweight, high-performance firmware that maximizes the potential of the X4, prioritizing legibility and
+usability over "swiss-army-knife" functionality.
+
+## 2. Scope
+
+### In-Scope
+
+*These are features that directly improve the primary purpose of the device.*
+
+* **User Experience:** E.g. User-friendly interfaces, and interactions, both inside the reader and navigating the
+  firmware. This includes things like button mapping, book loading, and book navigation like bookmarks.
+* **Document Rendering:** E.g. Support for rendering documents (primarily EPUB) and improvements to the rendering
+  engine.
+* **Format Optimization:** E.g. Efficiently parsing EPUB (CSS/Images) and other documents within the device's
+  capabilities.
+* **Typography & Legibility:** E.g. Custom font support, hyphenation engines, and adjustable line spacing.
+* **E-Ink Driver Refinement:** E.g. Reducing full-screen flashes (ghosting management) and improving general rendering.
+* **Library Management:** E.g. Simple, intuitive ways to organize and navigate a collection of books.
+* **Local Transfer:** E.g. Simple, "pull" based book loading via a basic web-server or public and widely-used standards.
+* **Language Support:** E.g. Support for multiple languages both in the reader and in the interfaces.
+
+### Out-of-Scope
+
+*These items are rejected because they compromise the device's stability or mission.*
+
+* **Interactive Apps:** No Notepads, Calculators, or Games. This is a reader, not a PDA.
+* **Active Connectivity:** No RSS readers, News aggregators, or Web browsers. Background Wi-Fi tasks drain the battery
+  and complicate the single-core CPU's execution.
+* **Media Playback:** No Audio players or Audio-books.
+* **Complex Reader Features:** No highlighting, notes, or dictionary lookup. These features are better suited for
+  devices with better input capabilities and more powerful chips.
+
+## 3. Idea Evaluation
+
+While I appreciate the desire to add new and exciting features to CrossPoint Reader, CrossPoint Reader is designed to be
+a lightweight, reliable, and performant e-reader. Things which distract or compromise the device's core mission will not
+be accepted. As a guiding question, consider if your idea improve the "core reading experience" for the average user,
+and, critically, not distract from that reading experience.
+
+> **Note to Contributors:** If you are unsure if your idea fits the scope, please open a **Discussion** before you start
+> coding!
@@ -2,6 +2,30 @@

 Welcome to the **CrossPoint** firmware. This guide outlines the hardware controls, navigation, and reading features of the device.

+- [CrossPoint User Guide](#crosspoint-user-guide)
+  - [1. Hardware Overview](#1-hardware-overview)
+    - [Button Layout](#button-layout)
+  - [2. Power \& Startup](#2-power--startup)
+    - [Power On / Off](#power-on--off)
+    - [First Launch](#first-launch)
+  - [3. Screens](#3-screens)
+    - [3.1 Home Screen](#31-home-screen)
+    - [3.2 Book Selection](#32-book-selection)
+    - [3.3 Reading Mode](#33-reading-mode)
+    - [3.4 File Upload Screen](#34-file-upload-screen)
+    - [3.4.1 Calibre Wireless Transfers](#341-calibre-wireless-transfers)
+    - [3.5 Settings](#35-settings)
+    - [3.6 Sleep Screen](#36-sleep-screen)
+  - [4. Reading Mode](#4-reading-mode)
+    - [Page Turning](#page-turning)
+    - [Chapter Navigation](#chapter-navigation)
+    - [System Navigation](#system-navigation)
+    - [Supported Languages](#supported-languages)
+  - [5. Chapter Selection Screen](#5-chapter-selection-screen)
+  - [6. Current Limitations \& Roadmap](#6-current-limitations--roadmap)
+  - [7. Troubleshooting Issues \& Escaping Bootloop](#7-troubleshooting-issues--escaping-bootloop)
+
+
 ## 1. Hardware Overview

 The device utilises the standard buttons on the Xtink X4 (in the same layout as the manufacturer firmware, by default):
@@ -20,9 +44,10 @@ Button layout can be customized in **[Settings](#35-settings)**.

 ### Power On / Off

-To turn the device on or off, **press and hold the Power button for half a second**. In **[Settings](#35-settings)** you can configure the power button to trigger on a short press instead of a long one.
+To turn the device on or off, **press and hold the Power button for approximately half a second**.
+In **[Settings](#35-settings)** you can configure the power button to turn the device off with a short press instead of a long one.

-To reboot the device (for example if it's frozen, or after a firmware update), press and release the Reset button, and then hold the Power button for a few seconds.
+To reboot the device (for example if it's frozen, or after a firmware update), press and release the Reset button, and then quickly press and hold the Power button for a few seconds.

 ### First Launch

@@ -59,22 +84,53 @@ See the [webserver docs](./docs/webserver.md) for more information on how to con
 > [!TIP]
 > Advanced users can also manage files programmatically or via the command line using `curl`. See the [webserver docs](./docs/webserver.md) for details.

+### 3.4.1 Calibre Wireless Transfers
+
+CrossPoint supports sending books from Calibre using the CrossPoint Reader device plugin.
+
+1. Install the plugin in Calibre:
+   - Head to https://github.com/crosspoint-reader/calibre-plugins/releases to download the latest version of the crosspoint_reader plugin.
+   - Download the zip file.
+   - Open Calibre → Preferences → Plugins → Load plugin from file → Select the zip file.
+2. On the device: File Transfer → Connect to Calibre → Join a network.
+3. Make sure your computer is on the same WiFi network.
+4. In Calibre, click "Send to device" to transfer books.
+
 ### 3.5 Settings

 The Settings screen allows you to configure the device's behavior. There are a few settings you can adjust:
 - **Sleep Screen**: Which sleep screen to display when the device sleeps:
-  - "Dark" (default) - The default dark sleep screen
+  - "Dark" (default) - The default dark Crosspoint logo sleep screen
  - "Light" - The same default sleep screen, on a white background
-  - "Custom" - Custom images from the SD card, see [Sleep Screen](#36-sleep-screen) below for more information
+  - "Custom" - Custom images from the SD card; see [Sleep Screen](#36-sleep-screen) below for more information
  - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
-  - "Blank" - A blank screen
+  - "None" - A blank screen
+  - "Cover + Custom" - The book cover image, fallbacks to "Custom" behavior
+- **Sleep Screen Cover Mode**: How to display the book cover when "Cover" sleep screen is selected:
+  - "Fit" (default) - Scale the image down to fit centered on the screen, padding with white borders as necessary
+  - "Crop" - Scale the image down and crop as necessary to try to to fill the screen (Note: this is experimental and may not work as expected)
+- **Sleep Screen Cover Filter**: What filter will be applied to the book cover when "Cover" sleep screen is selected 
+  - "None" (default) - The cover image will be converted to a grayscale image and displayed as it is
+  - "Contrast" - The image will be displayed as a black & white image without grayscale conversion
+  - "Inverted" - The image will be inverted as in white&black and will be displayed without grayscale conversion
 - **Status Bar**: Configure the status bar displayed while reading:
  - "None" - No status bar
  - "No Progress" - Show status bar without reading progress
-  - "Full" - Show status bar with reading progress
+  - "Full w/ Percentage" - Show status bar with book progress (as percentage)
+  - "Full w/ Book Bar" - Show status bar with book progress (as bar)
+  - "Book Bar Only" - Show book progress (as bar)
+  - "Full w/ Chapter Bar" - Show status bar with chapter progress (as bar)
+- **Hide Battery %**: Configure where to suppress the battery pecentage display in the status bar; the battery icon will still be shown:
+  - "Never" - Always show battery percentage (default)
+  - "In Reader" - Show battery percentage everywhere except in reading mode
+  - "Always" - Always hide battery percentage
 - **Extra Paragraph Spacing**: If enabled, vertical space will be added between paragraphs in the book. If disabled, paragraphs will not have vertical space between them, but will have first-line indentation.
- **Short Power Button Click**: Whether to trigger the power button on a short press or a long press.
- **Reading Orientation**: Set the screen orientation for reading:
+- **Text Anti-Aliasing**: Whether to show smooth grey edges (anti-aliasing) on text in reading mode. Note this slows down page turns slightly.
+- **Short Power Button Click**: Controls the effect of a short click of the power button:
+  - "Ignore" - Require a long press to turn off the device
+  - "Sleep" - A short press powers the device off
+  - "Page Turn" - A short press in reading mode turns to the next page; a long press turns the device off
+- **Reading Orientation**: Set the screen orientation for reading EPUB files:
  - "Portrait" (default) - Standard portrait orientation
  - "Landscape CW" - Landscape, rotated clockwise
  - "Inverted" - Portrait, upside down
@@ -83,16 +139,26 @@ The Settings screen allows you to configure the device's behavior. There are a f
  - Back, Confirm, Left, Right (default)
  - Left, Right, Back, Confirm
  - Left, Back, Confirm, Right
- **Side Button Layout**: Swap the order of the up and down volume buttons from Previous/Next to Next/Previous. This change is only in effect when reading.
+  - Back, Confirm, Right, Left
+- **Side Button Layout (reader)**: Swap the order of the up and down volume buttons from Previous/Next to Next/Previous. This change is only in effect when reading.
+- **Long-press Chapter Skip**: Set whether long-pressing page turn buttons skip to the next/previous chapter.
+  - "Chapter Skip" (default) - Long-pressing skips to next/previous chapter
+  - "Page Scroll" - Long-pressing scrolls a page up/down
+- Swap the order of the up and down volume buttons from Previous/Next to Next/Previous. This change is only in effect when reading.
 - **Reader Font Family**: Choose the font used for reading:
  - "Bookerly" (default) - Amazon's reading font
  - "Noto Sans" - Google's sans-serif font
  - "Open Dyslexic" - Font designed for readers with dyslexia
 - **Reader Font Size**: Adjust the text size for reading; options are "Small", "Medium", "Large", or "X Large".
 - **Reader Line Spacing**: Adjust the spacing between lines; options are "Tight", "Normal", or "Wide".
+- **Reader Screen Margin**: Controls the screen margins in reader mode between 5 and 40 pixels in 5 pixel increments.
 - **Reader Paragraph Alignment**: Set the alignment of paragraphs; options are "Justified" (default), "Left", "Center", or "Right".
 - **Time to Sleep**: Set the duration of inactivity before the device automatically goes to sleep.
 - **Refresh Frequency**: Set how often the screen does a full refresh while reading to reduce ghosting.
+- **Sunlight Fading Fix**: Configure whether to enable a software-fix for the issue where white X4 models may fade when used in direct sunlight
+  - "OFF" (default) - Disable the fix
+  - "ON" - Enable the fix
+- **OPDS Browser**: Configure OPDS server settings for browsing and downloading books. Set the server URL (for Calibre Content Server, add `/opds` to the end), and optionally configure username and password for servers requiring authentication. Note: Only HTTP Basic authentication is supported. If using Calibre Content Server with authentication enabled, you must set it to use Basic authentication instead of the default Digest authentication.
 - **Check for updates**: Check for firmware updates over WiFi.

 ### 3.6 Sleep Screen
@@ -124,15 +190,29 @@ Once you have opened a book, the button layout changes to facilitate reading.

 The role of the volume (side) buttons can be swapped in **[Settings](#35-settings)**.

+If the **Short Power Button Click** setting is set to "Page Turn", you can also turn to the next page by briefly pressing the Power button.
+
 ### Chapter Navigation
 * **Next Chapter:** Press and **hold** the **Right** (or **Volume Down**) button briefly, then release.
 * **Previous Chapter:** Press and **hold** the **Left** (or **Volume Up**) button briefly, then release.

+This feature can be disabled in **[Settings](#35-settings)** to help avoid changing chapters by mistake.
+
+
 ### System Navigation
 * **Return to Book Selection:** Press **Back** to close the book and return to the **[Book Selection](#32-book-selection)** screen.
 * **Return to Home:** Press and **hold** the **Back** button to close the book and return to the **[Home](#31-home-screen)** screen.
 * **Chapter Menu:** Press **Confirm** to open the **[Table of Contents/Chapter Selection](#5-chapter-selection-screen)**.

+### Supported Languages
+
+CrossPoint renders text using the following Unicode character blocks, enabling support for a wide range of languages:
+
+*   **Latin Script (Basic, Supplement, Extended-A):** Covers English, German, French, Spanish, Portuguese, Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Hungarian, Romanian, Slovak, Slovenian, Turkish, and others.
+*   **Cyrillic Script (Standard and Extended):** Covers Russian, Ukrainian, Belarusian, Bulgarian, Serbian, Macedonian, Kazakh, Kyrgyz, Mongolian, and others.
+
+What is not supported: Chinese, Japanese, Korean, Vietnamese, Hebrew, Arabic, Greek and Farsi.
+
 ---

 ## 5. Chapter Selection Screen
@@ -150,3 +230,18 @@ Accessible by pressing **Confirm** while inside a book.
 Please note that this firmware is currently in active development. The following features are **not yet supported** but are planned for future updates:

 * **Images:** Embedded images in e-books will not render.
+* **Cover Images:** Large cover images embedded into EPUB require several seconds (~10s for ~2000 pixel tall image) to convert for sleep screen and home screen thumbnail. Consider optimizing the EPUB with e.g. https://github.com/bigbag/epub-to-xtc-converter to speed this up.
+
+---
+
+## 7. Troubleshooting Issues & Escaping Bootloop
+
+If an issue or crash is encountered while using Crosspoint, feel free to raise an issue ticket and attach the serial monitor logs. The logs can be obtained by connecting the device to a computer and starting a serial monitor. Either [Serial Monitor](https://www.serialmonitor.org/) or the following command can be used:
+
+```
+pio device monitor
+```
+
+If the device is stuck in a bootloop, press and release the Reset button. Then, press and hold on to the configured Back button and the Power Button to boot to the Home Screen.
+
+There can be issues with broken cache or config. In this case, delete the `.crosspoint` directory on your SD card (or consider deleting only `settings.bin`, `state.bin`, or `epub_*` cache directories in the `.crosspoint/` folder).
@@ -13,7 +13,9 @@ fi
 # --modified: files tracked by git that have been modified (staged or unstaged)
 # --exclude-standard: ignores files in .gitignore
 # Additionally exclude files in 'lib/EpdFont/builtinFonts/' as they are script-generated.
+# Also exclude files in 'lib/Epub/Epub/hyphenation/generated/' as they are script-generated.
 git ls-files  --exclude-standard ${GIT_LS_FILES_FLAGS} \
    | grep -E '\.(c|cpp|h|hpp)$' \
    | grep -v -E '^lib/EpdFont/builtinFonts/' \
+    | grep -v -E '^lib/Epub/Epub/hyphenation/generated/' \
    | xargs -r clang-format -style=file -i
@@ -0,0 +1,66 @@
+# Hypher Binary Tries
+
+CrossPoint embeds the exact binary automata produced by
+[Typst's `hypher`](https://github.com/typst/hypher). 
+
+## File layout
+
+Each `.bin` blob is a single self-contained automaton:
+
+```
+uint32_t root_addr_be;  // big-endian offset of the root node
+uint8_t  levels[];      // shared "levels" tape (dist/score pairs)
+uint8_t  nodes[];       // node records packed back-to-back
+```
+
+The size of the `levels` tape is implicit. Individual nodes reference slices
+inside that tape via 12-bit offsets, so no additional pointers are required.
+
+### Node encoding
+
+Every node starts with a single control byte:
+
+- Bit 7 – set when the node stores scores (`levels`).
+- Bits 5-6 – stride of the target deltas (1, 2, or 3 bytes, big-endian).
+- Bits 0-4 – transition count (values ≥ 31 spill into an extra byte).
+
+If the `levels` flag is set, two more bytes follow. Together they encode a
+12-bit offset into the global `levels` tape and a 4-bit length. Each byte in the
+levels tape packs a distance/score pair as `dist * 10 + score`, where `dist`
+counts how many UTF-8 bytes we advanced since the previous digit.
+
+After the optional levels header come the transition labels (one byte per edge)
+followed by the signed target deltas. Targets are stored as relative offsets
+from the current node address. Deltas up to ±128 fit in a single byte, larger
+distances grow to 2 or 3 bytes. The runtime walks the transitions with a simple
+linear scan and materializes the absolute address by adding the decoded delta
+to the current node’s base.
+
+## Embedding blobs into the firmware
+
+The helper script `scripts/generate_hyphenation_trie.py` acts as a thin
+wrapper: it reads the hypher-generated `.bin` files, formats them as `constexpr`
+byte arrays, and emits headers under
+`lib/Epub/Epub/hyphenation/generated/`. Each header defines the raw data plus a
+`SerializedHyphenationPatterns` descriptor so the reader can keep the automaton
+in flash.
+
+To refresh the firmware assets after updating the `.bin` files, run:
+
+```
+./scripts/generate_hyphenation_trie.py \
+    --input lib/Epub/Epub/hyphenation/tries/en.bin \
+    --output lib/Epub/Epub/hyphenation/generated/hyph-en.trie.h
+
+./scripts/generate_hyphenation_trie.py \
+    --input lib/Epub/Epub/hyphenation/tries/fr.bin \
+    --output lib/Epub/Epub/hyphenation/generated/hyph-fr.trie.h
+
+./scripts/generate_hyphenation_trie.py \
+    --input lib/Epub/Epub/hyphenation/tries/de.bin \
+    --output lib/Epub/Epub/hyphenation/generated/hyph-de.trie.h
+
+./scripts/generate_hyphenation_trie.py \
+    --input lib/Epub/Epub/hyphenation/tries/ru.bin \
+    --output lib/Epub/Epub/hyphenation/generated/hyph-ru.trie.h
+```
@@ -0,0 +1,57 @@
+# Troubleshooting
+
+This document show most common issues and possible solutions while using the device features.
+
+- [Troubleshooting](#troubleshooting)
+    - [Cannot See the Device on the Network](#cannot-see-the-device-on-the-network)
+    - [Connection Drops or Times Out](#connection-drops-or-times-out)
+    - [Upload Fails](#upload-fails)
+    - [Saved Password Not Working](#saved-password-not-working)
+
+### Cannot See the Device on the Network
+
+**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
+
+**Solutions:**
+
+1. Verify both devices are on the **same WiFi network**
+   - Check your computer/phone WiFi settings
+   - Confirm the CrossPoint Reader shows "Connected" status
+2. Double-check the IP address
+   - Make sure you typed it correctly
+   - Include `http://` at the beginning
+3. Try disabling VPN if you're using one
+4. Some networks have "client isolation" enabled - check with your network administrator
+
+### Connection Drops or Times Out
+
+**Problem:** WiFi connection is unstable
+
+**Solutions:**
+
+1. Move closer to the WiFi router
+2. Check signal strength on the device (should be at least `||` or better)
+3. Avoid interference from other devices
+4. Try a different WiFi network if available
+
+### Upload Fails
+
+**Problem:** File upload doesn't complete or shows an error
+
+**Solutions:**
+
+1. Ensure the file is a valid `.epub` file
+2. Check that the SD card has enough free space
+3. Try uploading a smaller file first to test
+4. Refresh the browser page and try again
+
+### Saved Password Not Working
+
+**Problem:** Device fails to connect with saved credentials
+
+**Solutions:**
+
+1. When connection fails, you'll be prompted to "Forget Network"
+2. Select **Yes** to remove the saved password
+3. Reconnect and enter the password again
+4. Choose to save the new password
@@ -0,0 +1,331 @@
+# Webserver Endpoints
+
+This document describes all HTTP and WebSocket endpoints available on the CrossPoint Reader webserver.
+
+- [Webserver Endpoints](#webserver-endpoints)
+  - [Overview](#overview)
+  - [HTTP Endpoints](#http-endpoints)
+    - [GET `/` - Home Page](#get----home-page)
+    - [GET `/files` - File Browser Page](#get-files---file-browser-page)
+    - [GET `/api/status` - Device Status](#get-apistatus---device-status)
+    - [GET `/api/files` - List Files](#get-apifiles---list-files)
+    - [POST `/upload` - Upload File](#post-upload---upload-file)
+    - [POST `/mkdir` - Create Folder](#post-mkdir---create-folder)
+    - [POST `/delete` - Delete File or Folder](#post-delete---delete-file-or-folder)
+  - [WebSocket Endpoint](#websocket-endpoint)
+    - [Port 81 - Fast Binary Upload](#port-81---fast-binary-upload)
+  - [Network Modes](#network-modes)
+    - [Station Mode (STA)](#station-mode-sta)
+    - [Access Point Mode (AP)](#access-point-mode-ap)
+  - [Notes](#notes)
+
+
+## Overview
+
+The CrossPoint Reader exposes a webserver for file management and device monitoring:
+
+- **HTTP Server**: Port 80
+- **WebSocket Server**: Port 81 (for fast binary uploads)
+
+---
+
+## HTTP Endpoints
+
+### GET `/` - Home Page
+
+Serves the home page HTML interface.
+
+**Request:**
+```bash
+curl http://crosspoint.local/
+```
+
+**Response:** HTML page (200 OK)
+
+---
+
+### GET `/files` - File Browser Page
+
+Serves the file browser HTML interface.
+
+**Request:**
+```bash
+curl http://crosspoint.local/files
+```
+
+**Response:** HTML page (200 OK)
+
+---
+
+### GET `/api/status` - Device Status
+
+Returns JSON with device status information.
+
+**Request:**
+```bash
+curl http://crosspoint.local/api/status
+```
+
+**Response (200 OK):**
+```json
+{
+  "version": "1.0.0",
+  "ip": "192.168.1.100",
+  "mode": "STA",
+  "rssi": -45,
+  "freeHeap": 123456,
+  "uptime": 3600
+}
+```
+
+| Field      | Type   | Description                                               |
+| ---------- | ------ | --------------------------------------------------------- |
+| `version`  | string | CrossPoint firmware version                               |
+| `ip`       | string | Device IP address                                         |
+| `mode`     | string | `"STA"` (connected to WiFi) or `"AP"` (access point mode) |
+| `rssi`     | number | WiFi signal strength in dBm (0 in AP mode)                |
+| `freeHeap` | number | Free heap memory in bytes                                 |
+| `uptime`   | number | Seconds since device boot                                 |
+
+---
+
+### GET `/api/files` - List Files
+
+Returns a JSON array of files and folders in the specified directory.
+
+**Request:**
+```bash
+# List root directory
+curl http://crosspoint.local/api/files
+
+# List specific directory
+curl "http://crosspoint.local/api/files?path=/Books"
+```
+
+**Query Parameters:**
+
+| Parameter | Required | Default | Description            |
+| --------- | -------- | ------- | ---------------------- |
+| `path`    | No       | `/`     | Directory path to list |
+
+**Response (200 OK):**
+```json
+[
+  {"name": "MyBook.epub", "size": 1234567, "isDirectory": false, "isEpub": true},
+  {"name": "Notes", "size": 0, "isDirectory": true, "isEpub": false},
+  {"name": "document.pdf", "size": 54321, "isDirectory": false, "isEpub": false}
+]
+```
+
+| Field         | Type    | Description                              |
+| ------------- | ------- | ---------------------------------------- |
+| `name`        | string  | File or folder name                      |
+| `size`        | number  | Size in bytes (0 for directories)        |
+| `isDirectory` | boolean | `true` if the item is a folder           |
+| `isEpub`      | boolean | `true` if the file has `.epub` extension |
+
+**Notes:**
+- Hidden files (starting with `.`) are automatically filtered out
+- System folders (`System Volume Information`, `XTCache`) are hidden
+
+---
+
+### POST `/upload` - Upload File
+
+Uploads a file to the SD card via multipart form data.
+
+**Request:**
+```bash
+# Upload to root directory
+curl -X POST -F "file=@mybook.epub" http://crosspoint.local/upload
+
+# Upload to specific directory
+curl -X POST -F "file=@mybook.epub" "http://crosspoint.local/upload?path=/Books"
+```
+
+**Query Parameters:**
+
+| Parameter | Required | Default | Description                     |
+| --------- | -------- | ------- | ------------------------------- |
+| `path`    | No       | `/`     | Target directory for the upload |
+
+**Response (200 OK):**
+```
+File uploaded successfully: mybook.epub
+```
+
+**Error Responses:**
+
+| Status | Body                                            | Cause                       |
+| ------ | ----------------------------------------------- | --------------------------- |
+| 400    | `Failed to create file on SD card`              | Cannot create file          |
+| 400    | `Failed to write to SD card - disk may be full` | Write error during upload   |
+| 400    | `Failed to write final data to SD card`         | Error flushing final buffer |
+| 400    | `Upload aborted`                                | Client aborted the upload   |
+| 400    | `Unknown error during upload`                   | Unspecified error           |
+
+**Notes:**
+- Existing files with the same name will be overwritten
+- Uses a 4KB buffer for efficient SD card writes
+
+---
+
+### POST `/mkdir` - Create Folder
+
+Creates a new folder on the SD card.
+
+**Request:**
+```bash
+curl -X POST -d "name=NewFolder&path=/" http://crosspoint.local/mkdir
+```
+
+**Form Parameters:**
+
+| Parameter | Required | Default | Description                  |
+| --------- | -------- | ------- | ---------------------------- |
+| `name`    | Yes      | -       | Name of the folder to create |
+| `path`    | No       | `/`     | Parent directory path        |
+
+**Response (200 OK):**
+```
+Folder created: NewFolder
+```
+
+**Error Responses:**
+
+| Status | Body                          | Cause                         |
+| ------ | ----------------------------- | ----------------------------- |
+| 400    | `Missing folder name`         | `name` parameter not provided |
+| 400    | `Folder name cannot be empty` | Empty folder name             |
+| 400    | `Folder already exists`       | Folder with same name exists  |
+| 500    | `Failed to create folder`     | SD card error                 |
+
+---
+
+### POST `/delete` - Delete File or Folder
+
+Deletes a file or folder from the SD card.
+
+**Request:**
+```bash
+# Delete a file
+curl -X POST -d "path=/Books/mybook.epub&type=file" http://crosspoint.local/delete
+
+# Delete an empty folder
+curl -X POST -d "path=/OldFolder&type=folder" http://crosspoint.local/delete
+```
+
+**Form Parameters:**
+
+| Parameter | Required | Default | Description                      |
+| --------- | -------- | ------- | -------------------------------- |
+| `path`    | Yes      | -       | Path to the item to delete       |
+| `type`    | No       | `file`  | Type of item: `file` or `folder` |
+
+**Response (200 OK):**
+```
+Deleted successfully
+```
+
+**Error Responses:**
+
+| Status | Body                                          | Cause                         |
+| ------ | --------------------------------------------- | ----------------------------- |
+| 400    | `Missing path`                                | `path` parameter not provided |
+| 400    | `Cannot delete root directory`                | Attempted to delete `/`       |
+| 400    | `Folder is not empty. Delete contents first.` | Non-empty folder              |
+| 403    | `Cannot delete system files`                  | Hidden file (starts with `.`) |
+| 403    | `Cannot delete protected items`               | Protected system folder       |
+| 404    | `Item not found`                              | Path does not exist           |
+| 500    | `Failed to delete item`                       | SD card error                 |
+
+**Protected Items:**
+- Files/folders starting with `.`
+- `System Volume Information`
+- `XTCache`
+
+---
+
+## WebSocket Endpoint
+
+### Port 81 - Fast Binary Upload
+
+A WebSocket endpoint for high-speed binary file uploads. More efficient than HTTP multipart for large files.
+
+**Connection:**
+```
+ws://crosspoint.local:81/
+```
+
+**Protocol:**
+
+1. **Client** sends TEXT message: `START:<filename>:<size>:<path>`
+2. **Server** responds with TEXT: `READY`
+3. **Client** sends BINARY messages with file data chunks
+4. **Server** sends TEXT progress updates: `PROGRESS:<received>:<total>`
+5. **Server** sends TEXT when complete: `DONE` or `ERROR:<message>`
+
+**Example Session:**
+
+```
+Client -> "START:mybook.epub:1234567:/Books"
+Server -> "READY"
+Client -> [binary chunk 1]
+Client -> [binary chunk 2]
+Server -> "PROGRESS:65536:1234567"
+Client -> [binary chunk 3]
+...
+Server -> "PROGRESS:1234567:1234567"
+Server -> "DONE"
+```
+
+**Error Messages:**
+
+| Message                           | Cause                              |
+| --------------------------------- | ---------------------------------- |
+| `ERROR:Failed to create file`     | Cannot create file on SD card      |
+| `ERROR:Invalid START format`      | Malformed START message            |
+| `ERROR:No upload in progress`     | Binary data received without START |
+| `ERROR:Write failed - disk full?` | SD card write error                |
+
+**Example with `websocat`:**
+```bash
+# Interactive session
+websocat ws://crosspoint.local:81
+
+# Then type:
+START:mybook.epub:1234567:/Books
+# Wait for READY, then send binary data
+```
+
+**Notes:**
+- Progress updates are sent every 64KB or at completion
+- Disconnection during upload will delete the incomplete file
+- Existing files with the same name will be overwritten
+
+---
+
+## Network Modes
+
+The device can operate in two network modes:
+
+### Station Mode (STA)
+- Device connects to an existing WiFi network
+- IP address assigned by router/DHCP
+- `mode` field in `/api/status` returns `"STA"`
+- `rssi` field shows signal strength
+
+### Access Point Mode (AP)
+- Device creates its own WiFi hotspot
+- Default IP is typically `192.168.4.1`
+- `mode` field in `/api/status` returns `"AP"`
+- `rssi` field returns `0`
+
+---
+
+## Notes
+
+- These examples use `crosspoint.local`. If your network does not support mDNS or the address does not resolve, replace it with the specific **IP Address** displayed on your device screen (e.g., `http://192.168.1.102/`).
+- All paths on the SD card start with `/`
+- Trailing slashes are automatically stripped (except for root `/`)
+- The webserver uses chunked transfer encoding for file listings
@@ -153,7 +153,7 @@ Click **File Manager** to access file management features.

 1. Click the **+ Add** button in the top-right corner
 2. Select **New Folder** from the dropdown menu
-3. Enter a folder name (letters, numbers, underscores, and hyphens only)
+3. Enter a folder name (must not contain characters \" * : < > ? / \\ | and must not be . or ..)
 4. Click **Create Folder**

 This is useful for organizing your ebooks by genre, author, or series.
@@ -172,89 +172,7 @@ This is useful for organizing your ebooks by genre, author, or series.

 ## Command Line File Management

-For power users, you can manage files directly from your terminal using `curl` while the device is in File Upload mode. 
-
-### Uploading a File
-To upload a file to the root directory, use the following command:
-```bash
-curl -F "file=@book.epub" "http://crosspoint.local/upload?path=/"
-```
-
-* **`-F "file=@filename"`**: Points to the local file on your computer.
-* **`path=/`**: The destination folder on the device SD card.
-
-### Deleting a File
-
-To delete a specific file, provide the full path on the SD card:
-
-```bash
-curl -F "path=/folder/file.epub" "http://crosspoint.local/delete"
-```
-
-### Advanced Flags
-
-For more reliable transfers of large EPUB files, consider adding these flags:
-
-* `-#`: Shows a simple progress bar.
-* `--connect-timeout 30`: Limits how long curl waits to establish a connection (in seconds).
-* `--max-time 300`: Sets a maximum duration for the entire transfer (5 minutes).
-
-> [!NOTE]
-> These examples use `crosspoint.local`. If your network does not support mDNS or the address does not resolve, replace it with the specific **IP Address** displayed on your device screen (e.g., `http://192.168.1.102/`).
-
---
-
-## Troubleshooting
-
-### Cannot See the Device on the Network
-
-**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
-
-**Solutions:**
-
-1. Verify both devices are on the **same WiFi network**
-   - Check your computer/phone WiFi settings
-   - Confirm the CrossPoint Reader shows "Connected" status
-2. Double-check the IP address
-   - Make sure you typed it correctly
-   - Include `http://` at the beginning
-3. Try disabling VPN if you're using one
-4. Some networks have "client isolation" enabled - check with your network administrator
-
-### Connection Drops or Times Out
-
-**Problem:** WiFi connection is unstable
-
-**Solutions:**
-
-1. Move closer to the WiFi router
-2. Check signal strength on the device (should be at least `||` or better)
-3. Avoid interference from other devices
-4. Try a different WiFi network if available
-
-### Upload Fails
-
-**Problem:** File upload doesn't complete or shows an error
-
-**Solutions:**
-
-1. Ensure the file is a valid `.epub` file
-2. Check that the SD card has enough free space
-3. Try uploading a smaller file first to test
-4. Refresh the browser page and try again
-
-### Saved Password Not Working
-
-**Problem:** Device fails to connect with saved credentials
-
-**Solutions:**
-
-1. When connection fails, you'll be prompted to "Forget Network"
-2. Select **Yes** to remove the saved password
-3. Reconnect and enter the password again
-4. Choose to save the new password
-
---
+For power users, you can manage files directly from your terminal using `curl` while the device is in File Upload mode a detailed documentation can be found [here](./webserver-endpoints.md). 

 ## Security Notes

@@ -303,4 +221,5 @@ Your uploaded files will be immediately available in the file browser!
 ## Related Documentation

 - [User Guide](../USER_GUIDE.md) - General device operation
+- [Troubleshooting](./troubleshooting.md) - Troubleshooting
 - [README](../README.md) - Project overview and features
@@ -22,8 +22,7 @@ void EpdFont::getTextBounds(const char* string, const int startX, const int star
    const EpdGlyph* glyph = getGlyph(cp);

    if (!glyph) {
-      // TODO: Replace with fallback glyph property?
-      glyph = getGlyph('?');
+      glyph = getGlyph(REPLACEMENT_GLYPH);
    }

    if (!glyph) {
@@ -1,23 +1,19 @@
 #include "EpdFontFamily.h"

 const EpdFont* EpdFontFamily::getFont(const Style style) const {
-  if (style == BOLD && bold) {
+  // Extract font style bits (ignore UNDERLINE bit for font selection)
+  const bool hasBold = (style & BOLD) != 0;
+  const bool hasItalic = (style & ITALIC) != 0;
+
+  if (hasBold && hasItalic) {
+    if (boldItalic) return boldItalic;
+    if (bold) return bold;
+    if (italic) return italic;
+  } else if (hasBold && bold) {
    return bold;
-  }
-  if (style == ITALIC && italic) {
+  } else if (hasItalic && italic) {
    return italic;
  }
-  if (style == BOLD_ITALIC) {
-    if (boldItalic) {
-      return boldItalic;
-    }
-    if (bold) {
-      return bold;
-    }
-    if (italic) {
-      return italic;
-    }
-  }

  return regular;
 }
@@ -3,7 +3,7 @@

 class EpdFontFamily {
 public:
-  enum Style : uint8_t { REGULAR = 0, BOLD = 1, ITALIC = 2, BOLD_ITALIC = 3 };
+  enum Style : uint8_t { REGULAR = 0, BOLD = 1, ITALIC = 2, BOLD_ITALIC = 3, UNDERLINE = 4 };

  explicit EpdFontFamily(const EpdFont* regular, const EpdFont* bold = nullptr, const EpdFont* italic = nullptr,
                         const EpdFont* boldItalic = nullptr)
--- a/Show More
+++ b/Show More