dfbc931c14
Brings ~55 mod-exclusive files to the upstream-based mod/master-resync branch: Activities (migrated to new ActivityManager pattern): - Clock/Time: SetTimeActivity, SetTimezoneOffsetActivity, NtpSyncActivity - Dictionary: DictionaryDefinitionActivity, DictionarySuggestionsActivity, DictionaryWordSelectActivity, LookedUpWordsActivity - Bookmark: EpubReaderBookmarkSelectionActivity - Book management: BookManageMenuActivity, EndOfBookMenuActivity - OPDS: OpdsServerListActivity, OpdsSettingsActivity - Utility: DirectoryPickerActivity, NumericStepperActivity Utilities (unchanged): - BookManager, BookSettings, BookmarkStore, BootNtpSync - Dictionary, LookupHistory, TimeSync, OpdsServerStore Libraries: PlaceholderCover, TableData, ChapterXPathIndexer Scripts: inject_mod_version, generate_book_icon, preview_placeholder_cover Docs: KOReader sync XPath mapping Migration changes: - ActivityWithSubactivity -> Activity base class - Callback constructors -> finish()/setResult() pattern - enterNewActivity() -> startActivityForResult() - Activity::RenderLock&& -> RenderLock&& These files won't compile yet - they reference mod settings and I18n strings that will be added in subsequent phases. Made-with: Cursor
307 lines
14 KiB
Markdown
307 lines
14 KiB
Markdown
# CrossPoint Reader -- Project File Structure
|
|
|
|
This document maps the repository layout and describes where key pieces of code can be found.
|
|
|
|
## Root Directory
|
|
|
|
```
|
|
crosspoint-reader-mod/
|
|
├── platformio.ini # PlatformIO build config (environments, flags, deps)
|
|
├── partitions.csv # ESP32 flash partition table
|
|
├── .clang-format # C++ code formatting rules (clang-format 21)
|
|
├── .clangd # Language server configuration
|
|
├── .gitmodules # Git submodule reference (open-x4-sdk)
|
|
├── README.md # Project overview and getting started
|
|
├── LICENSE # MIT License
|
|
├── GOVERNANCE.md # Community governance principles
|
|
├── SCOPE.md # Project vision and feature scope
|
|
├── USER_GUIDE.md # End-user manual
|
|
├── bin/ # Developer scripts
|
|
├── docs/ # Upstream documentation
|
|
├── lib/ # Project libraries (HAL, EPUB, fonts, etc.)
|
|
├── src/ # Main application source code
|
|
├── scripts/ # Build and utility scripts (Python)
|
|
├── test/ # Unit/evaluation tests
|
|
├── open-x4-sdk/ # Hardware SDK (git submodule)
|
|
├── include/ # PlatformIO include directory (empty)
|
|
├── mod/ # Local modifications workspace
|
|
└── .github/ # CI workflows, templates, funding
|
|
```
|
|
|
|
## `src/` -- Application Source
|
|
|
|
The main firmware application code. Entry point is `main.cpp`.
|
|
|
|
```
|
|
src/
|
|
├── main.cpp # Arduino setup()/loop(), activity routing, font init
|
|
├── CrossPointSettings.cpp/.h # User settings (load/save to SD, defaults)
|
|
├── CrossPointState.cpp/.h # Runtime application state (open book, sleep tracking)
|
|
├── MappedInputManager.cpp/.h # User-remappable button abstraction over HalGPIO
|
|
├── Battery.h # Global BatteryMonitor instance
|
|
├── fontIds.h # Numeric font family identifiers
|
|
├── SettingsList.h # Setting definitions and enums
|
|
├── RecentBooksStore.cpp/.h # Recently opened books persistence
|
|
├── WifiCredentialStore.cpp/.h # Saved WiFi network credentials
|
|
│
|
|
├── activities/ # UI screens (Activity pattern, see below)
|
|
├── components/ # Shared UI components and themes
|
|
├── network/ # Web server, HTTP, OTA updater
|
|
├── images/ # Logo assets (SVG, PNG, compiled header)
|
|
└── util/ # String and URL utility functions
|
|
```
|
|
|
|
### `src/activities/` -- UI Activity System
|
|
|
|
Each screen is an `Activity` subclass with `onEnter()`, `onExit()`, and `loop()` lifecycle methods. Activities are swapped by the routing functions in `main.cpp`.
|
|
|
|
```
|
|
activities/
|
|
├── Activity.h # Base Activity interface
|
|
├── ActivityWithSubactivity.cpp/.h # Composition: activity that hosts a child
|
|
│
|
|
├── boot_sleep/
|
|
│ ├── BootActivity.cpp/.h # Boot splash screen
|
|
│ └── SleepActivity.cpp/.h # Sleep screen (cover image, clock, etc.)
|
|
│
|
|
├── browser/
|
|
│ └── OpdsBookBrowserActivity.cpp/.h # OPDS catalog browsing and download
|
|
│
|
|
├── home/
|
|
│ ├── HomeActivity.cpp/.h # Main menu / home screen
|
|
│ ├── MyLibraryActivity.cpp/.h # File browser for books on SD card
|
|
│ └── RecentBooksActivity.cpp/.h # Recently opened books list
|
|
│
|
|
├── network/
|
|
│ ├── CrossPointWebServerActivity.cpp/.h # Web server file transfer mode
|
|
│ ├── CalibreConnectActivity.cpp/.h # Calibre wireless device connection
|
|
│ ├── NetworkModeSelectionActivity.cpp/.h # WiFi/AP/Calibre mode picker
|
|
│ └── WifiSelectionActivity.cpp/.h # WiFi network scanner and connector
|
|
│
|
|
├── reader/
|
|
│ ├── ReaderActivity.cpp/.h # Format dispatcher (EPUB, TXT, XTC)
|
|
│ ├── EpubReaderActivity.cpp/.h # EPUB reading engine
|
|
│ ├── EpubReaderMenuActivity.cpp/.h # In-reader menu overlay
|
|
│ ├── EpubReaderChapterSelectionActivity.cpp/.h # Table of contents navigation
|
|
│ ├── EpubReaderPercentSelectionActivity.cpp/.h # Jump-to-percentage navigation
|
|
│ ├── TxtReaderActivity.cpp/.h # Plain text reader
|
|
│ ├── XtcReaderActivity.cpp/.h # XTC format reader
|
|
│ ├── XtcReaderChapterSelectionActivity.cpp/.h # XTC chapter navigation
|
|
│ └── KOReaderSyncActivity.cpp/.h # KOReader reading progress sync
|
|
│
|
|
├── settings/
|
|
│ ├── SettingsActivity.cpp/.h # Main settings screen
|
|
│ ├── ButtonRemapActivity.cpp/.h # Front button remapping UI
|
|
│ ├── CalibreSettingsActivity.cpp/.h # Calibre server configuration
|
|
│ ├── ClearCacheActivity.cpp/.h # Cache clearing utility
|
|
│ ├── KOReaderAuthActivity.cpp/.h # KOReader auth credential entry
|
|
│ ├── KOReaderSettingsActivity.cpp/.h # KOReader sync settings
|
|
│ └── OtaUpdateActivity.cpp/.h # Over-the-air firmware update UI
|
|
│
|
|
└── util/
|
|
├── FullScreenMessageActivity.cpp/.h # Full-screen status/error messages
|
|
└── KeyboardEntryActivity.cpp/.h # On-screen keyboard for text input
|
|
```
|
|
|
|
### `src/components/` -- UI Components and Themes
|
|
|
|
```
|
|
components/
|
|
├── UITheme.cpp/.h # Theme manager singleton
|
|
└── themes/
|
|
├── BaseTheme.cpp/.h # Default theme implementation
|
|
└── lyra/
|
|
└── LyraTheme.cpp/.h # Alternative "Lyra" theme
|
|
```
|
|
|
|
### `src/network/` -- Networking
|
|
|
|
```
|
|
network/
|
|
├── CrossPointWebServer.cpp/.h # HTTP web server (file management, upload, settings)
|
|
├── HttpDownloader.cpp/.h # HTTP/HTTPS file downloader
|
|
├── OtaUpdater.cpp/.h # OTA firmware update client
|
|
└── html/
|
|
├── HomePage.html # Web UI home page
|
|
├── FilesPage.html # Web UI file browser / upload page
|
|
└── SettingsPage.html # Web UI settings page
|
|
```
|
|
|
|
HTML files are minified at build time by `scripts/build_html.py` into `PROGMEM` C++ headers (`.generated.h`).
|
|
|
|
### `src/util/` -- Utilities
|
|
|
|
```
|
|
util/
|
|
├── StringUtils.cpp/.h # String manipulation helpers
|
|
└── UrlUtils.cpp/.h # URL encoding/decoding
|
|
```
|
|
|
|
## `lib/` -- Project Libraries
|
|
|
|
PlatformIO-managed libraries local to the project.
|
|
|
|
### `lib/hal/` -- Hardware Abstraction Layer
|
|
|
|
The HAL wraps the SDK drivers behind a stable API the rest of the firmware consumes.
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `HalDisplay.cpp/.h` | E-ink display control (refresh, buffer ops, grayscale, sleep) |
|
|
| `HalGPIO.cpp/.h` | Button input, battery reading, USB detection, deep sleep, wakeup |
|
|
| `HalStorage.cpp/.h` | SD card file operations (`Storage` singleton) |
|
|
|
|
### `lib/Epub/` -- EPUB Library
|
|
|
|
The core document parsing and rendering engine.
|
|
|
|
```
|
|
Epub/
|
|
├── Epub.cpp/.h # Top-level EPUB interface
|
|
├── Epub/
|
|
│ ├── Page.cpp/.h # Single rendered page
|
|
│ ├── Section.cpp/.h # Book section (chapter)
|
|
│ ├── ParsedText.cpp/.h # Parsed text representation
|
|
│ ├── BookMetadataCache.cpp/.h # Metadata caching to SD card
|
|
│ │
|
|
│ ├── blocks/
|
|
│ │ ├── Block.h # Base block type
|
|
│ │ ├── BlockStyle.h # Block styling
|
|
│ │ └── TextBlock.cpp/.h # Text block rendering
|
|
│ │
|
|
│ ├── css/
|
|
│ │ ├── CssParser.cpp/.h # CSS subset parser
|
|
│ │ └── CssStyle.h # Parsed CSS style representation
|
|
│ │
|
|
│ ├── hyphenation/
|
|
│ │ ├── Hyphenator.cpp/.h # Main hyphenation API
|
|
│ │ ├── LiangHyphenation.cpp/.h # Liang algorithm implementation
|
|
│ │ ├── HyphenationCommon.cpp/.h # Shared types
|
|
│ │ ├── LanguageHyphenator.h # Per-language interface
|
|
│ │ ├── LanguageRegistry.cpp/.h # Language detection and routing
|
|
│ │ ├── SerializedHyphenationTrie.h # Trie data format
|
|
│ │ └── generated/ # Pre-built hyphenation tries
|
|
│ │ ├── hyph-de.trie.h # German
|
|
│ │ ├── hyph-en.trie.h # English
|
|
│ │ ├── hyph-es.trie.h # Spanish
|
|
│ │ ├── hyph-fr.trie.h # French
|
|
│ │ └── hyph-ru.trie.h # Russian
|
|
│ │
|
|
│ └── parsers/
|
|
│ ├── ChapterHtmlSlimParser.cpp/.h # Chapter HTML content parser
|
|
│ ├── ContainerParser.cpp/.h # META-INF/container.xml parser
|
|
│ ├── ContentOpfParser.cpp/.h # content.opf (spine, manifest) parser
|
|
│ ├── TocNavParser.cpp/.h # EPUB3 nav TOC parser
|
|
│ └── TocNcxParser.cpp/.h # EPUB2 NCX TOC parser
|
|
```
|
|
|
|
### `lib/EpdFont/` -- Font Rendering
|
|
|
|
```
|
|
EpdFont/
|
|
├── EpdFont.cpp/.h # Font rendering engine
|
|
├── EpdFontData.h # Raw font data structure
|
|
├── EpdFontFamily.cpp/.h # Font family (regular, bold, italic, bold-italic)
|
|
├── builtinFonts/
|
|
│ ├── all.h # Aggregate include for all built-in fonts
|
|
│ ├── bookerly_*.h # Bookerly at sizes 12, 14, 16, 18
|
|
│ ├── notosans_*.h # Noto Sans at sizes 8, 12, 14, 16, 18
|
|
│ ├── opendyslexic_*.h # OpenDyslexic at sizes 8, 10, 12, 14
|
|
│ ├── ubuntu_*.h # Ubuntu at sizes 10, 12 (UI font)
|
|
│ └── source/ # Original TTF/OTF font files
|
|
└── scripts/
|
|
├── fontconvert.py # TTF/OTF to compiled header converter
|
|
├── convert-builtin-fonts.sh # Batch conversion script
|
|
├── build-font-ids.sh # Generate fontIds.h
|
|
└── requirements.txt # Python dependencies for font tools
|
|
```
|
|
|
|
### Other Libraries
|
|
|
|
| Library | Path | Purpose |
|
|
|---|---|---|
|
|
| `expat/` | `lib/expat/` | XML parser (used by EPUB parsers) |
|
|
| `miniz/` | `lib/miniz/` | Compression/decompression (ZIP support) |
|
|
| `ZipFile/` | `lib/ZipFile/` | ZIP file reading (EPUB is a ZIP) |
|
|
| `picojpeg/` | `lib/picojpeg/` | Lightweight JPEG decoder |
|
|
| `JpegToBmpConverter/` | `lib/JpegToBmpConverter/` | JPEG to bitmap conversion for display |
|
|
| `GfxRenderer/` | `lib/GfxRenderer/` | Graphics renderer, bitmap helpers |
|
|
| `Txt/` | `lib/Txt/` | Plain text (.txt) file reader |
|
|
| `Xtc/` | `lib/Xtc/` | XTC format parser and types |
|
|
| `OpdsParser/` | `lib/OpdsParser/` | OPDS feed XML parser and streaming |
|
|
| `KOReaderSync/` | `lib/KOReaderSync/` | KOReader sync client, credential store, progress mapping |
|
|
| `Utf8/` | `lib/Utf8/` | UTF-8 string utilities |
|
|
| `Serialization/` | `lib/Serialization/` | Binary serialization helper |
|
|
| `FsHelpers/` | `lib/FsHelpers/` | File system utility functions |
|
|
|
|
## `open-x4-sdk/` -- Hardware SDK (Git Submodule)
|
|
|
|
Community SDK providing low-level hardware drivers. Referenced in `.gitmodules` from `https://github.com/open-x4-epaper/community-sdk.git`.
|
|
|
|
Supplies four libraries linked as symlinks in `platformio.ini`:
|
|
|
|
| Library | SDK Path | Purpose |
|
|
|---|---|---|
|
|
| `BatteryMonitor` | `libs/hardware/BatteryMonitor` | Battery voltage ADC reading |
|
|
| `InputManager` | `libs/hardware/InputManager` | Physical button GPIO management |
|
|
| `EInkDisplay` | `libs/display/EInkDisplay` | E-ink display SPI driver |
|
|
| `SDCardManager` | `libs/hardware/SDCardManager` | SD card SPI initialization |
|
|
|
|
## `scripts/` -- Build and Utility Scripts
|
|
|
|
| Script | Language | Purpose |
|
|
|---|---|---|
|
|
| `build_html.py` | Python | **Pre-build step.** Minifies HTML files in `src/` into `PROGMEM` C++ headers (`.generated.h`). Strips comments, collapses whitespace, preserves `<pre>`, `<code>`, `<script>`, `<style>` content. |
|
|
| `generate_hyphenation_trie.py` | Python | Generates serialized hyphenation trie headers from TeX hyphenation patterns. |
|
|
| `debugging_monitor.py` | Python | Enhanced serial monitor for debugging output. |
|
|
|
|
## `test/` -- Tests
|
|
|
|
```
|
|
test/
|
|
├── README # PlatformIO test directory info
|
|
├── run_hyphenation_eval.sh # Test runner script
|
|
└── hyphenation_eval/
|
|
├── HyphenationEvaluationTest.cpp # Hyphenation accuracy evaluation
|
|
└── resources/
|
|
├── english_hyphenation_tests.txt
|
|
├── french_hyphenation_tests.txt
|
|
├── german_hyphenation_tests.txt
|
|
├── russian_hyphenation_tests.txt
|
|
├── spanish_hyphenation_tests.txt
|
|
└── generate_hyphenation_test_data.py
|
|
```
|
|
|
|
## `docs/` -- Upstream Documentation
|
|
|
|
| File | Topic |
|
|
|---|---|
|
|
| `comparison.md` | Feature comparison with stock firmware |
|
|
| `file-formats.md` | Supported document formats |
|
|
| `hyphenation-trie-format.md` | Hyphenation trie binary format specification |
|
|
| `troubleshooting.md` | Common issues and fixes |
|
|
| `webserver.md` | Web server feature guide |
|
|
| `webserver-endpoints.md` | Web server HTTP API reference |
|
|
| `images/` | Screenshots and cover image |
|
|
|
|
## `.github/` -- GitHub Configuration
|
|
|
|
```
|
|
.github/
|
|
├── workflows/
|
|
│ ├── ci.yml # Main CI: format check, cppcheck, build
|
|
│ ├── release.yml # Tag-triggered release build
|
|
│ ├── release_candidate.yml # Manual RC build (release/* branches)
|
|
│ └── pr-formatting-check.yml # Semantic PR title validation
|
|
├── PULL_REQUEST_TEMPLATE.md # PR template (summary, context, AI usage)
|
|
├── ISSUE_TEMPLATE/
|
|
│ └── bug_report.yml # Bug report form
|
|
└── FUNDING.yml # GitHub Sponsors configuration
|
|
```
|
|
|
|
## `bin/` -- Developer Tools
|
|
|
|
| Script | Purpose |
|
|
|---|---|
|
|
| `clang-format-fix` | Runs `clang-format` on all tracked `.c`, `.cpp`, `.h`, `.hpp` files (excluding generated font headers). Pass `-g` to format only modified files. |
|