# CrossPoint Reader -- Project Summary

> This document is a condensed reference for quickly re-familiarizing with the CrossPoint Reader firmware project. It consolidates hardware specs, codebase layout, build/CI details, architecture patterns, and current mod work. For full detail see `hardware.md`, `file-structure.md`, and `ci-build-and-code-style.md` in this directory.

## What This Is

CrossPoint Reader is an open-source, community-driven firmware replacement for the **Xteink X4** e-paper reader. It is **not affiliated with Xteink**. The project's sole mission is focused, high-quality ebook reading -- no apps, games, browsers, or audio. See `SCOPE.md` for the full boundary definition.

Repository: `https://github.com/crosspoint-reader/crosspoint-reader`
License: MIT
Governance: `GOVERNANCE.md` (critique code not people, public-by-default decisions, `@daveallie` for moderation)

## Hardware at a Glance

| Component | Spec |
|---|---|
| MCU | ESP32-C3, RISC-V, **single-core** |
| RAM | ~380 KB usable (aggressive SD caching required) |
| Flash | 16 MB total, DIO mode |
| Display | 480x800 e-ink, 2-bit grayscale (4 levels), SPI |
| Refresh | FULL (best quality), HALF (~1720ms), FAST (default, custom LUT) |
| Frame buffer | 48,000 bytes, single-buffer mode |
| Buttons | 7 total: 4 front (remappable), 2 side (page nav), 1 power (deep-sleep wake) |
| Storage | SD card via SPI (shared bus with display), SdFat, UTF-8 long filenames |
| Battery | GPIO 0, BatteryMonitor SDK lib, 0-100% |
| WiFi | 802.11 b/g/n 2.4GHz, STA + AP modes |
| USB | USB-C, CDC on boot, connection detection via GPIO 20 |
| Power | Deep sleep with GPIO wakeup, configurable inactivity timeout |

### Flash Partition Layout

```
NVS        0x9000    20KB    Key/value storage
OTA Data   0xE000     8KB    Boot selection
ota_0      0x10000  6.25MB   Primary firmware
ota_1      0x650000 6.25MB   Secondary firmware (OTA)
SPIFFS     0xC90000 3.375MB  On-flash filesystem
Coredump   0xFF0000   64KB   Crash dumps
```

### Key GPIO Assignments

Display SPI: SCLK=8, MOSI=10, CS=21, DC=4, RST=5, BUSY=6, MISO=7 (shared with SD)
Battery: GPIO 0 | USB detect: GPIO 20

## Architecture Overview

### Application Loop

Standard Arduino `setup()` / `loop()` in `src/main.cpp`. The loop polls buttons via `HalGPIO`, delegates to the current `Activity`, handles auto-sleep timeout, and power button hold detection. Memory stats are logged every 10s over serial (when USB connected).

### Activity System

UI screens are `Activity` subclasses with lifecycle methods `onEnter()`, `onExit()`, `loop()`. Only one activity is active at a time. Routing functions in `main.cpp` (`onGoHome()`, `onGoToReader()`, etc.) manage transitions by deleting the old activity and creating the new one.

`ActivityWithSubactivity` provides composition for activities that host child activities (menus, overlays).

### Hardware Abstraction Layer (lib/hal/)

Three classes wrap the SDK drivers:
- `HalDisplay` -- display refresh, buffer ops, grayscale, deep sleep
- `HalGPIO` -- buttons, battery, USB detection, deep sleep, wakeup reason
- `HalStorage` -- SD card file ops via singleton `Storage`

### Rendering Pipeline

`GfxRenderer` wraps `HalDisplay` for drawing operations. Fonts are registered by ID at startup from compiled headers in `lib/EpdFont/builtinFonts/`. The renderer supports a `fadingFix` setting.

### Data Caching

EPUB data is aggressively cached to SD under `.crosspoint/epub_<hash>/` to conserve RAM:
- `progress.bin` -- reading position
- `cover.bmp` -- extracted cover image
- `book.bin` -- metadata (title, author, spine, TOC)
- `sections/*.bin` -- pre-parsed chapter layout data

Cache is NOT auto-cleaned on book deletion. Moving a book file resets its cache/progress.

## Key Source Locations

### Where to find things

| What | Where |
|---|---|
| Entry point | `src/main.cpp` -- `setup()`, `loop()`, activity routing, font init |
| User settings | `src/CrossPointSettings.cpp/.h` -- load/save to SD |
| App state | `src/CrossPointState.cpp/.h` -- open book path, sleep tracking |
| Button mapping | `src/MappedInputManager.cpp/.h` -- remappable buttons, labels |
| Boot screen | `src/activities/boot_sleep/BootActivity.cpp/.h` |
| Sleep screen | `src/activities/boot_sleep/SleepActivity.cpp/.h` |
| Home screen | `src/activities/home/HomeActivity.cpp/.h` |
| Library browser | `src/activities/home/MyLibraryActivity.cpp/.h` |
| EPUB reader | `src/activities/reader/EpubReaderActivity.cpp/.h` |
| Reader menu | `src/activities/reader/EpubReaderMenuActivity.cpp/.h` |
| TXT reader | `src/activities/reader/TxtReaderActivity.cpp/.h` |
| XTC reader | `src/activities/reader/XtcReaderActivity.cpp/.h` |
| Settings | `src/activities/settings/SettingsActivity.cpp/.h` |
| Button remap | `src/activities/settings/ButtonRemapActivity.cpp/.h` |
| OTA update UI | `src/activities/settings/OtaUpdateActivity.cpp/.h` |
| Web server | `src/network/CrossPointWebServer.cpp/.h` |
| OTA client | `src/network/OtaUpdater.cpp/.h` |
| HTTP download | `src/network/HttpDownloader.cpp/.h` |
| Web UI HTML | `src/network/html/{HomePage,FilesPage,SettingsPage}.html` |
| Themes | `src/components/themes/BaseTheme.cpp/.h`, `lyra/LyraTheme.cpp/.h` |
| Theme manager | `src/components/UITheme.cpp/.h` |

### Library code (lib/)

| What | Where |
|---|---|
| EPUB engine | `lib/Epub/` -- parsing, rendering, sections, pages |
| EPUB parsers | `lib/Epub/Epub/parsers/` -- container, OPF, HTML, TOC (nav+ncx) |
| CSS parser | `lib/Epub/Epub/css/CssParser.cpp/.h` |
| Hyphenation | `lib/Epub/Epub/hyphenation/` -- Liang algorithm, 5 language tries |
| Display HAL | `lib/hal/HalDisplay.cpp/.h` |
| GPIO HAL | `lib/hal/HalGPIO.cpp/.h` |
| Storage HAL | `lib/hal/HalStorage.cpp/.h` |
| Font rendering | `lib/EpdFont/EpdFont.cpp/.h` |
| Built-in fonts | `lib/EpdFont/builtinFonts/` -- Bookerly, NotoSans, OpenDyslexic, Ubuntu |
| Graphics | `lib/GfxRenderer/` -- renderer, bitmap, bitmap helpers |
| XML parsing | `lib/expat/` |
| ZIP/compression | `lib/miniz/`, `lib/ZipFile/` |
| JPEG decoding | `lib/picojpeg/`, `lib/JpegToBmpConverter/` |
| OPDS parsing | `lib/OpdsParser/` |
| KOReader sync | `lib/KOReaderSync/` |
| UTF-8 utils | `lib/Utf8/` |

### SDK (open-x4-sdk/ submodule)

Provides: `BatteryMonitor`, `InputManager`, `EInkDisplay`, `SDCardManager`
Linked as symlinks in `platformio.ini` lib_deps.

## Build & CI Quick Reference

### Build locally

```bash
pio run                    # Dev build (version: 1.0.0-dev)
pio run -e gh_release      # Release build (version: 1.0.0)
pio run --target upload    # Build and flash via USB
pio check                  # Run cppcheck static analysis
```

### Code formatting

```bash
./bin/clang-format-fix     # Format all tracked C/C++ files
./bin/clang-format-fix -g  # Format only modified files
```

Key style rules: 2-space indent, 120-char column limit, K&R braces (Attach), pointer-left (`int* x`), sorted/regrouped includes, spaces not tabs, LF line endings.

Excludes `lib/EpdFont/builtinFonts/` (generated).

### CI (GitHub Actions)

On push to `master` or any PR, 4 parallel jobs run:
1. **clang-format** -- formatting check (clang-format-21)
2. **cppcheck** -- static analysis (fails on low/medium/high)
3. **build** -- compilation + firmware.bin artifact
4. **test-status** -- aggregated PR gate

PR titles must follow semantic format (`feat:`, `fix:`, `refactor:`, etc.).

### Releases

- **Official:** Push a git tag -> `release.yml` builds `gh_release` env -> uploads bootloader, firmware, ELF, map, partitions
- **RC:** Manually trigger `release_candidate.yml` on a `release/*` branch -> embeds commit SHA in version

### Version scheme

```
1.0.0-dev           # default env (local dev)
1.0.0               # gh_release env (tagged release)
1.0.0-rc+a1b2c3d    # gh_release_rc env (release candidate)
```

### Dependencies

| Dependency | Version | Purpose |
|---|---|---|
| espressif32 | 6.12.0 | PlatformIO platform |
| ArduinoJson | 7.4.2 | JSON parsing |
| QRCode | 0.0.1 | QR code generation |
| WebSockets | 2.7.3 | WebSocket server |

### Pre-build step

`scripts/build_html.py` minifies `src/network/html/*.html` -> `.generated.h` PROGMEM strings.

### Debugging

```bash
python3 scripts/debugging_monitor.py                       # Linux
python3 scripts/debugging_monitor.py /dev/cu.usbmodem2101  # macOS
```

Requires: `pyserial`, `colorama`, `matplotlib`.

## Supported Document Formats

- **EPUB** (primary) -- EPUB 2 and EPUB 3, CSS subset, hyphenation (EN, DE, ES, FR, RU)
- **TXT** -- plain text
- **XTC** -- proprietary format with chapter support
- Image support within EPUB is listed as incomplete (per README checklist)

## Constraints to Remember

- **~380KB RAM** -- everything large must be cached to SD card
- **Single-core CPU** -- WiFi and main loop compete for cycles; no true background tasks
- **6.25MB firmware slot** -- maximum firmware binary size
- **48KB frame buffer** -- 1-bit per pixel in normal mode, 2-bit for grayscale
- **Shared SPI bus** -- display and SD card share MISO; cannot access simultaneously
- **No PSRAM** -- all memory is internal SRAM
- **Font headers are generated** -- do not hand-edit `lib/EpdFont/builtinFonts/` (excluded from formatting)
- **HTML headers are generated** -- `.generated.h` files in `src/network/html/` are auto-built from `.html` files