A fork of https://github.com/crosspoint-reader/crosspoint-reader
1# Architecture Overview
2
3CrossPoint is firmware for the Xteink X4 (unaffiliated with Xteink), built with PlatformIO targeting the ESP32-C3 microcontroller.
4
5At a high level, it is firmware that uses an activity-driven application architecture loop with persistent settings/state, SD-card-first caching, and a rendering pipeline optimized for e-ink constraints.
6
7## System at a glance
8
9```mermaid
10graph TD
11 A[Hardware: ESP32-C3 + SD + E-ink + Buttons] --> B[open-x4-sdk HAL]
12 B --> C[src/main.cpp runtime loop]
13 C --> D[Activities layer]
14 C --> E[State and settings]
15 D --> F[Reader flows]
16 D --> G[Home/Library/Settings flows]
17 D --> H[Network/Web server flows]
18 F --> I[lib/Epub parsing + layout + hyphenation]
19 I --> J[SD cache in .crosspoint]
20 D --> K[GfxRenderer]
21 K --> L[E-ink display buffer]
22```
23
24## Runtime lifecycle
25
26Primary entry point is `src/main.cpp`.
27
28```mermaid
29flowchart TD
30 A[Boot] --> B[Init GPIO and optional serial]
31 B --> C[Init SD storage]
32 C --> D[Load settings and app state]
33 D --> E[Init display and fonts]
34 E --> F{Resume reader?}
35 F -->|No| G[Enter Home activity]
36 F -->|Yes| H[Enter Reader activity]
37 G --> I[Main loop]
38 H --> I
39 I --> J[Poll input and run current activity]
40 J --> K{Sleep condition met?}
41 K -->|No| I
42 K -->|Yes| L[Persist state and enter deep sleep]
43```
44
45In each loop iteration, the firmware updates input, runs the active activity, handles auto-sleep/power behavior, and applies a short delay policy to balance responsiveness and power.
46
47## Activity model
48
49Activities are screen-level controllers deriving from `src/activities/Activity.h`.
50Some flows use `src/activities/ActivityWithSubactivity.h` to host nested activities.
51
52- `onEnter()` and `onExit()` manage setup/teardown
53- `loop()` handles per-frame behavior
54- `skipLoopDelay()` and `preventAutoSleep()` are used by long-running flows (for example web server mode)
55
56Top-level activity groups:
57
58- `src/activities/home/`: home and library navigation
59- `src/activities/reader/`: EPUB/XTC/TXT reading flows
60- `src/activities/settings/`: settings menus and configuration
61- `src/activities/network/`: WiFi selection, AP/STA mode, file transfer server
62- `src/activities/boot_sleep/`: boot and sleep transitions
63
64## Reader and content pipeline
65
66Reader orchestration starts in `src/activities/reader/ReaderActivity.h` and dispatches to format-specific readers.
67EPUB processing is implemented in `lib/Epub/`.
68
69```mermaid
70flowchart LR
71 A[Select book] --> B[ReaderActivity]
72 B --> C{Format}
73 C -->|EPUB| D[lib/Epub/Epub]
74 C -->|XTC| E[lib/Xtc reader]
75 C -->|TXT| F[lib/Txt reader]
76 D --> G[Parse OPF/TOC/CSS]
77 G --> H[Layout pages/sections]
78 H --> I[Write section and metadata caches]
79 I --> J[Render current page via GfxRenderer]
80```
81
82Why caching matters:
83
84- RAM is limited on ESP32-C3, so expensive parsed/layout data is persisted to SD
85- repeat opens/page navigation can reuse cached data instead of full reparsing
86
87## Reader internals call graph
88
89This diagram zooms into the EPUB path to show the main control and data flow from activity entry to on-screen draw.
90
91```mermaid
92flowchart TD
93 A[ReaderActivity onEnter] --> B{File type}
94 B -->|EPUB| C[Create Epub object]
95 B -->|XTC/TXT| Z[Use format-specific reader]
96
97 C --> D[Epub load]
98 D --> E[Locate container and OPF]
99 E --> F[Build or load BookMetadataCache]
100 F --> G[Load TOC and spine]
101 G --> H[Load or parse CSS rules]
102
103 H --> I[EpubReaderActivity]
104 I --> J{Section cache exists for current settings?}
105 J -->|Yes| K[Read section bin from SD cache]
106 J -->|No| L[Parse chapter HTML and layout text]
107 L --> M[Apply typography settings and hyphenation]
108 M --> N[Write section cache bin]
109
110 K --> O[Build page model]
111 N --> O
112 O --> P[GfxRenderer draw calls]
113 P --> Q[HAL display framebuffer update]
114 Q --> R[E-ink refresh policy]
115
116 S[SETTINGS singleton] -. influences .-> J
117 S -. influences .-> M
118 T[APP_STATE singleton] -. persists .-> U[Reading progress and resume context]
119 U -. used by .-> I
120```
121
122Notes:
123
124- "section cache exists" depends on cache-busting parameters such as font and layout-related settings
125- rendering favors reusing precomputed layout data to keep page turns responsive on constrained hardware
126- progress/session state is persisted so the reader can reopen at the last position after reboot/sleep
127
128## State and persistence
129
130Two singletons are central:
131
132- `src/CrossPointSettings.h` (`SETTINGS`): user preferences and behavior flags
133- `src/CrossPointState.h` (`APP_STATE`): runtime/session state such as current book and sleep context
134
135Typical persisted areas on SD:
136
137```text
138/.crosspoint/
139 epub_<hash>/
140 book.bin
141 progress.bin
142 cover.bmp
143 sections/*.bin
144 settings.bin
145 state.bin
146```
147
148For binary cache formats, see `docs/file-formats.md`.
149
150## Networking architecture
151
152Network file transfer is controlled by `src/activities/network/CrossPointWebServerActivity.h` and served by `src/network/CrossPointWebServer.h`.
153
154Modes:
155
156- STA: join existing WiFi network
157- AP: create hotspot
158
159Server behavior:
160
161- HTTP server on port 80
162- WebSocket upload server on port 81
163- file operations backed by SD storage
164- activity requests faster loop responsiveness while server is running
165
166Endpoint reference: `docs/webserver-endpoints.md`.
167
168## Build-time generated assets
169
170Some sources are generated and should not be edited manually.
171
172- `scripts/build_html.py` generates `src/network/html/*.generated.h` from HTML files
173- `scripts/generate_hyphenation_trie.py` generates hyphenation headers under `lib/Epub/Epub/hyphenation/generated/`
174
175When editing related source assets, regenerate via normal build steps/scripts.
176
177## Key directories
178
179- `src/`: app orchestration, settings/state, and activity implementations
180- `src/network/`: web server and OTA/update networking
181- `src/components/`: theming and shared UI components
182- `lib/Epub/`: EPUB parser, layout, CSS handling, and hyphenation
183- `lib/`: supporting libraries (fonts, text, filesystem helpers, etc.)
184- `open-x4-sdk/`: hardware SDK submodule (display, input, storage, battery)
185- `docs/`: user and technical documentation
186
187## Embedded constraints that shape design
188
189- constrained RAM drives SD-first caching and careful allocations
190- e-ink refresh cost drives render/update batching choices
191- main loop responsiveness matters for input, power handling, and watchdog safety
192- background/network flows must cooperate with sleep and loop timing logic
193
194## Scope guardrails
195
196Before implementing larger ideas, check:
197
198- [SCOPE.md](../../SCOPE.md)
199- [GOVERNANCE.md](../../GOVERNANCE.md)