CI / build (push) Failing after 3m43s

Details

- Add crosspoint-ef fork notice to README with links to upstream
- Include feature overview, user guide, and technical comparison docs

2026-01-28 10:03:45 -05:00

19 KiB

Raw Blame History

CrossPoint-EF Branch Features

This document describes the features and enhancements unique to the crosspoint-ef branch, which diverged from CrossPoint Reader at version 0.15.0.

Overview

The crosspoint-ef branch introduces significant new functionality including:

Dictionary Support - Offline StarDict dictionary with word selection from reader
Bookmark System - Per-book bookmarks with visual indicators and management
Quick Menu - Fast access to common actions via power button
Library Search - Search across all books by title, author, or filename
CSS Support - Parse and apply CSS styles from EPUB files
Inline Images - PNG and Baseline JPEG image rendering within EPUBs
Custom Fonts - Atkinson Hyperlegible Next and Fern Micro accessibility fonts
Enhanced Web Server - File management, companion app API, mDNS discovery
Reading Lists - Create, manage, and pin custom book lists
Display Enhancements - High contrast mode, bezel compensation, sleep screen improvements

Major Features

1. Dictionary Support

Full offline dictionary lookup using the StarDict format with fast prefix-indexed search.

Features:

Word selection directly from EPUB pages
Manual word entry via on-screen keyboard
Rich HTML formatting in definitions (bold, italic, lists)
Multi-page definitions with pagination
Synonym support
Case-insensitive search with prefix optimization

Access Methods:

Quick Menu → Dictionary
Power Button (when configured to Dictionary action)

Dictionary Format:

StarDict format with dictzip compression
Files located at /dictionaries/dict-data on SD card:
- dict-data.ifo - Metadata
- dict-data.idx - Word index
- dict-data.dict.dz - Compressed definitions
- dict-data.syn - Synonyms (optional)

Technical Implementation:

Files: src/activities/dictionary/, lib/StarDict/
Prefix jump table for near-instant lookups
On-demand chunk decompression using miniz
HTML definition parsing with entity decoding

2. Bookmark System

Per-book bookmark storage with visual indicators and dedicated management interface.

Features:

Add/remove bookmarks from current page
Visual folded-corner indicator on bookmarked pages
Bookmarks tab in library showing all books with bookmarks
Long-press to delete bookmarks
Auto-generated bookmark names ("Chapter Title - Page X")
Maximum 100 bookmarks per book

Storage:

Binary file per book: /.crosspoint/{epub_|txt_}<hash>/bookmarks.bin
Stores: name, spine index, content offset, page number, timestamp

Technical Implementation:

Files: src/BookmarkStore.cpp/.h, src/activities/home/BookmarkListActivity.cpp/.h
Bookmark identification by spineIndex + contentOffset (stable across re-renders)

In-reader quick access menu for common actions, triggered by short power button press.

Menu Options:

Dictionary - Look up a word
Bookmark - Add/Remove bookmark (state-aware text)
Clear Cache - Free up storage space
Settings - Open settings menu

Configuration:

Settings → Controls → Short Power Button Click → Quick Menu

Technical Implementation:

File: src/activities/util/QuickMenuActivity.cpp/.h
Renders overlay with navigation and selection

4. Library Search with Character Picker

Search across all books using a dynamic character picker interface.

Features:

Character picker with dynamically generated character set from library content
Weighted search scoring:
- Title match: 100 points (+50 if at start)
- Author match: 80 points (+40 if at start)
- Path match: 30 points
Results sorted by relevance score
Special controls: SPC (space), ← (backspace), CLR (clear)

Navigation:

Left/Right: Select character
Confirm: Add character to query
Up/Down: Switch between picker and results

Technical Implementation:

Integrated in src/activities/home/MyLibraryActivity.cpp
Search tab accessible from library tab bar

5. CSS Support for EPUBs

Parse and apply CSS styles from EPUB stylesheets.

Supported Selectors:

Element selectors: p, div, h1, etc.
Class selectors: .classname
Combined selectors: element.classname
Grouped selectors: h1, h2, h3
Inline styles: style="..."

Supported Properties:

text-align (left, center, right, justify)
font-style (normal, italic)
font-weight (normal, bold)
text-decoration (underline)
text-indent
margin-top, margin-bottom
padding-top, padding-bottom

Cascade Order:

Element styles
Class styles
Element.class styles
Inline styles

Technical Implementation:

Files: lib/Epub/Epub/css/CssParser.cpp/.h, CssStyle.h
CSS files parsed during EPUB loading
Styles applied during HTML parsing via ChapterHtmlSlimParser

6. Inline Image Support (PNG/Baseline JPEG)

Render embedded images within EPUB content.

Supported Formats:

Baseline JPEG (.jpg, .jpeg)
PNG (.png)

Features:

Images decoded to 2-bit grayscale with dithering
Image caching as .pxc files (2 bits per pixel, packed format)
Row-by-row rendering to minimize memory usage
Automatic scaling to fit page width

Technical Implementation:

Files: lib/Epub/Epub/blocks/ImageBlock.cpp/.h
Converters: JpegToFramebufferConverter, PngToFramebufferConverter
Factory: ImageDecoderFactory routes to appropriate decoder

7. Custom Fonts

Additional accessibility-focused fonts beyond the standard Bookerly and Noto Sans.

Available Fonts:

Atkinson Hyperlegible Next - Designed for low-vision readers
Fern Micro - Optimized for small screens

Font Sizes:

12pt, 14pt, 16pt, 18pt for each font
Full style support: Regular, Italic, Bold, Bold Italic

Configuration:

Settings → Reader → Font Family → Custom
Settings → Reader → Custom Font → [Select font]
Settings → Reader → Fallback Font → [Bookerly/Noto Sans]

Technical Implementation:

Files: src/customFonts.cpp, src/fontIds.h
Font headers: lib/EpdFont/builtinFonts/custom/
Conversion scripts: lib/EpdFont/scripts/convert-builtin-fonts.sh

8. Enhanced Web Server

Extended web server with file management operations and companion app support.

File Operations:

Endpoint	Method	Description
`/api/files`	GET	List files with MD5 hashes for EPUBs
`/api/status`	GET	Device status (version, IP, heap, uptime)
`/api/archived`	GET	List archived books
`/api/hash`	GET	Compute/retrieve MD5 hash for sync
`/download`	GET	Download files
`/upload`	POST	Upload files (multipart)
`/delete`	POST	Delete files/folders
`/archive`	POST	Archive a book
`/unarchive`	POST	Restore archived book
`/rename`	POST	Rename files/folders
`/copy`	POST	Copy files/folders
`/move`	POST	Move files/folders
`/mkdir`	POST	Create folders
`/list`	GET/POST	Manage reading lists

WebSocket Upload (Port 81):

Fast binary uploads for large files
Protocol: START:<filename>:<size>:<path> → READY → binary chunks → DONE
Progress updates: PROGRESS:<received>:<total>

mDNS Discovery:

Hostname: crosspoint.local
Service: _http._tcp on port 80
UDP discovery on port 8134

Deep Link Support:

URL scheme: crosspoint://<path>?host=<ip>&port=<port>&wsPort=<wsPort>
Paths: files, library, lists, settings

Technical Implementation:

Files: src/network/CrossPointWebServer.cpp/.h
MD5 Utils: src/util/Md5Utils.cpp/.h
Docs: docs/webserver-api-reference.md, docs/companion-app-deep-link-API.md

9. Reading Lists with Pinning

Create and manage custom book lists with pinning support.

Features:

Create, load, delete lists
Pin a list to show on home screen
List contents displayed with book metadata
Web API for list upload/download (CSV format)

Storage:

Lists stored in /.lists/ as .bin files
CSV format for API: order,title,author,path

Configuration:

Library → Lists tab → Long-press → Pin/Unpin
Pinned list name shown on home screen Lists button

Technical Implementation:

Files: src/BookListStore.cpp/.h
Pinned list stored in SETTINGS.pinnedListName

10. Display Enhancements

High Contrast Mode

System-wide display contrast adjustment for improved readability.

Normal mode: Standard grayscale thresholds
High contrast mode: Pushes mid-grays toward black/white

Configuration:

Settings → Display → High Contrast → On/Off

Bezel Compensation

Compensate for physical screen edge defects with configurable margin.

Range: 0-10 pixels
Edges: Bottom, Top, Left, Right
Behavior: Margin rotates with screen orientation

Configuration:

Settings → Display → Bezel Compensation → [0-10]
Settings → Display → Bezel Edge → [Bottom/Top/Left/Right]

Sleep Screen Improvements

Enhanced sleep screen with edge-aware color filling.

Edge luminance detection: Samples edge pixels for dominant color
Letterbox fill: Fills letterbox regions with edge colors for seamless appearance
Two-level caching:
- Per-BMP cache: .bmp.perim files store edge luminance
- Book-level cache: edge.bin stores cover data

11. Recents View Improvements

Enhanced recent books display with metadata and management.

Features:

Badges: Extension and suffix tags (e.g., "epub", "X4")
Metadata display: Title and author from EPUB
Remove from recents: Long-press → Remove from Recents
Clear all: Long-press → Clear All Recents

Badge Configuration:

Extension badges: .epub → "epub", .txt → "txt"
Suffix badges: -x4 → "X4", -x4p → "X4P"

Technical Implementation:

Files: src/RecentBooksStore.cpp/.h
Badge config: src/BadgeConfig.h
String utils: src/util/StringUtils.cpp/.h

12. Enhanced Tab Bar

Unified tab bar with scrolling and overflow indicators.

Features:

Horizontal scrolling when tabs exceed available width
Overflow indicators (< >) when content extends beyond view
Selected tab highlighting with underline
Bullet cursors for focus mode

Tabs:

Recent, Lists, Bookmarks, Search, Files

Technical Implementation:

Files: src/ScreenComponents.cpp/.h
Used in MyLibraryActivity for library navigation

13. Progress Bar Status Bar

Additional status bar option showing visual progress bar.

Options:

Full w/ Progress Bar - Full status bar with progress bar
Progress Bar - Only progress bar, no other status info

Configuration:

Settings → Display → Status Bar

14. Additional Settings

New configuration options unique to crosspoint-ef:

Setting	Options	Description
Short Power Button Click	Ignore, Sleep, Page Turn, Dictionary, Quick Menu	Map power button to action
Bezel Compensation	0-10 pixels	Edge defect compensation
Bezel Edge	Bottom, Top, Left, Right	Which edge to compensate
High Contrast	Off, On	System-wide contrast boost
Custom Font	[Font list]	Select custom font
Fallback Font	Bookerly, Noto Sans	Fallback for custom fonts

15. OPDS Browser Enhancements

Improved OPDS catalog browsing experience.

Features:

Navigation history stack - Back button navigates through visited feeds
Page skipping - Hold Up/Down for 700ms to skip 23 items at once
Error retry mechanism - Retry button on error screens with WiFi status check
HTTP Basic Authentication - Username/password support for protected OPDS servers

Configuration:

Settings → System → Calibre Settings → OPDS Server URL
Settings → System → Calibre Settings → Username/Password

Technical Implementation:

Files: src/activities/browser/OpdsBookBrowserActivity.cpp
Authentication: src/network/HttpDownloader.cpp

16. Development Tools

Scripts and utilities for firmware development.

Scripts:

Script	Purpose
`pre_flash.py`	Displays "Flashing firmware..." screen during upload
`debugging_monitor.py`	Enhanced serial monitor with memory graphs and color output
`pio_helper.py`	Interactive PlatformIO workflow helper with presets
`version_hash.py`	Embeds git commit hash in dev builds
`build_html.py`	Minifies HTML files for web server

Firmware Flashing Screen:

Full-screen display during firmware upload
Shows "Flashing firmware..." with version info
Lock icon indicates USB port location
Prevents accidental disconnection

Debug/Memory Monitoring:

DEBUG_MEMORY build mode for heap tracking at activity transitions
Periodic memory logging every 10 seconds (when Serial connected)
Loop duration warnings when exceeding 50ms
Detailed heap fragmentation info

Technical Implementation:

Scripts: scripts/pre_flash.py, scripts/debugging_monitor.py, scripts/pio_helper.py
Flash screen: src/main.cpp (lines 138-247)
Memory monitoring: src/main.cpp (lines 549-562)
Build config: platformio.ini (debug_memory environment)

17. Power Management Enhancements

Optimizations for battery life and responsiveness.

Features:

Auto-sleep prevention - Background tasks (web server, OTA, downloads) prevent auto-sleep
USB connection detection - Serial only starts when USB is connected (saves power)
Skip loop delay - Activities can request faster loop execution for responsive HTTP handling
Power button release wait - Prevents immediate wake if button is still held

Technical Implementation:

Files: src/main.cpp, src/activities/Activity.h
Methods: preventAutoSleep(), skipLoopDelay()

Bug Fixes

Unique to crosspoint-ef

Grayscale state corruption fix - Prevents ghosting and gray filter artifacts when anti-aliasing is enabled under memory pressure
Memory optimization - Graceful degradation when memory is low (skip anti-aliasing instead of corrupting display)

Shared with 0.16.0

Large EPUB indexing optimization (O(n²) → O(n))
Settings validation on read
Line break fixes (flush word before <br/>)
Rotate origin in drawImage()
Short-press power button to wakeup
Add txt books to recent tab
B&W filters for cover images

Missing or Removed Features from 0.16.0

The following features are present in the upstream 0.16.0 release but are missing or were removed in crosspoint-ef:

Removed Features

1. KOReader Sync Support (Removed)

The entire KOReader sync functionality has been removed.

What was removed:

lib/KOReaderSync/ library (8 files deleted)
Progress sync with KOReader sync server (sync.koreader.rocks)
Document MD5 binary matching for progress synchronization
KOReader credential storage

Impact:

Cannot sync reading progress with KOReader app
Chapter Selection UI fixes for KOReader sync (#501) not applicable

Files deleted:

KOReaderSyncClient.cpp/.h
KOReaderCredentialStore.cpp/.h
KOReaderDocumentId.cpp/.h
ProgressMapper.cpp/.h

2. Non-English Hyphenation Patterns (Removed)

Hyphenation pattern files for non-English languages have been removed.

What was removed:

hyph-es.trie.h - Spanish hyphenation
hyph-de.trie.h - German hyphenation
hyph-fr.trie.h - French hyphenation
hyph-ru.trie.h - Russian hyphenation

Impact:

Only English hyphenation patterns remain
Non-English books will not hyphenate correctly
Spanish hyphenation support (#558) not available

Note: These can be restored by copying the trie files from 0.16.0.

3. XTC/XTCH File Support (Removed)

Support for the XTC/XTCH proprietary format has been removed.

What was removed:

Author extraction from XTC/XTCH files (#563)
XTC format handling in file browsers

Impact:

XTC/XTCH files cannot be read
Author metadata not extracted from these formats

Missing Bug Fixes

The following bug fixes from 0.16.0 have not been applied to crosspoint-ef:

PR	Description	Impact
#567	Multi-line keyboard entry	Long text input truncated with "..." instead of wrapping
#569	Italics on image alt text	Image alt placeholders don't render in italics
#564	Front layout in mapLabels()	Button mapping may be incorrect in some layouts
#486	Relative position on settings change	Reader may jump to different location when settings change
#501	Chapter Selection UI (KOReader)	N/A - KOReader sync removed
#529	KOReader MD5 binary matching	N/A - KOReader sync removed

Missing UX Enhancements

PR	Description	Impact
#451	Page turn on button press	When long-press chapter skip is disabled, 0.16.0 allows page turn on button press; crosspoint-ef does not

Different Implementation: OTA Updates

The OTA update mechanism uses a different implementation:

Aspect	crosspoint-ef	0.16.0
HTTP Client	Arduino `HTTPClient`	ESP-IDF `esp_http_client`
OTA Library	Arduino `Update`	ESP-IDF `esp_https_ota`
Memory Management	Standard	Improved with custom buffer handling

Impact:

Both implementations work, but 0.16.0's ESP-IDF approach may be more memory-efficient
Consider evaluating 0.16.0's OTA rework (#509) for potential adoption

Recommendation for Missing Features

High Priority to Cherry-pick:

Multi-line keyboard entry (#567) - Improves UX for long inputs
Front layout fix (#564) - Bug fix for button mapping
Relative position on settings change (#486) - Improves reader UX

Medium Priority: 4. Restore hyphenation patterns for non-English languages 5. Italics on image alt (#569) - Minor visual improvement 6. Page turn on button press (#451) - UX enhancement

Evaluate: 7. OTA rework (#509) - Compare implementations for memory benefits 8. KOReader sync - Restore if sync functionality is desired

File Summary

Feature	Primary Files
Dictionary	`src/activities/dictionary/`, `lib/StarDict/`
Bookmarks	`src/BookmarkStore.`, `src/activities/home/BookmarkListActivity.`
Quick Menu	`src/activities/util/QuickMenuActivity.*`
Search	`src/activities/home/MyLibraryActivity.cpp`
CSS	`lib/Epub/Epub/css/`
Images	`lib/Epub/Epub/blocks/ImageBlock.*`, `lib/Epub/Epub/converters/`
Custom Fonts	`src/customFonts.cpp`, `lib/EpdFont/builtinFonts/custom/`
Web Server	`src/network/CrossPointWebServer.`, `src/util/Md5Utils.`
Lists	`src/BookListStore.*`
Settings	`src/CrossPointSettings.*`
Tab Bar	`src/ScreenComponents.*`
Recents	`src/RecentBooksStore.*`, `src/BadgeConfig.h`
OPDS Browser	`src/activities/browser/OpdsBookBrowserActivity.*`
Dev Tools	`scripts/pre_flash.py`, `scripts/debugging_monitor.py`, `scripts/pio_helper.py`
Power Management	`src/main.cpp`, `src/activities/Activity.h`

Version Information

Base version: 0.15.0
Branch: crosspoint-ef
Commits since divergence: 90+
Files changed: 250+

19 KiB Raw Blame History

CrossPoint-EF Branch Features

Overview

Major Features

1. Dictionary Support

2. Bookmark System

3. Quick Menu

4. Library Search with Character Picker

5. CSS Support for EPUBs

6. Inline Image Support (PNG/Baseline JPEG)

7. Custom Fonts

8. Enhanced Web Server

9. Reading Lists with Pinning

10. Display Enhancements

High Contrast Mode

Bezel Compensation

Sleep Screen Improvements

11. Recents View Improvements

12. Enhanced Tab Bar

13. Progress Bar Status Bar

14. Additional Settings

15. OPDS Browser Enhancements

16. Development Tools

17. Power Management Enhancements

Bug Fixes

Unique to crosspoint-ef

Shared with 0.16.0

Missing or Removed Features from 0.16.0

Removed Features

1. KOReader Sync Support (Removed)

2. Non-English Hyphenation Patterns (Removed)

3. XTC/XTCH File Support (Removed)

Missing Bug Fixes

Missing UX Enhancements

Different Implementation: OTA Updates

Recommendation for Missing Features

File Summary

Version Information

19 KiB

Raw Blame History