docs: refresh cache formats and web server workflows (#2233)
## Summary * **What is the goal of this PR?** Update project documentation to match the current master implementation for cache formats, i18n, file transfer/web server workflows, SD-card fonts, and root user-facing docs. * **What changes are included?** Refreshes `book.bin`/`section.bin` docs for v6/v25, updates File Transfer/Calibre/WebDAV/API docs, documents 24 UI languages and JSON language persistence, updates root README/USER_GUIDE cache and network details, and syncs the tracked CLAUDE skill doc cache-version notes. ## Additional Context * Docs-only change. Verified with `git diff --check origin/master..HEAD` and stale-reference greps for old cache versions, removed i18n APIs, old WiFi screen wording, and raw `Serial.printf` examples. No firmware build was run. --- ### AI Usage While CrossPoint doesn't have restrictions on AI tools in contributing, please be transparent about their usage as it helps set the right context for reviewers. Did you use AI tools to help write this code? _**NO**_
This commit is contained in:
Leopoldo Pla Sempere
+3
-3
@@ -896,8 +896,8 @@ rm -rf /path/to/sd/.crosspoint/epub_<hash>/sections/
|
||||
**Source**: `lib/Epub/Epub/Section.cpp`, `lib/Epub/Epub/BookMetadataCache.cpp`
|
||||
|
||||
**Current Versions** (as of docs/file-formats.md):
|
||||
- `book.bin`: **Version 5** (metadata structure)
|
||||
- `section.bin`: **Version 24** (layout structure)
|
||||
- `book.bin`: **Version 7** (metadata structure)
|
||||
- `section.bin`: **Version 25** (layout structure)
|
||||
|
||||
**Version Increment Rules**:
|
||||
1. **ALWAYS increment version** BEFORE changing binary structure
|
||||
@@ -907,7 +907,7 @@ rm -rf /path/to/sd/.crosspoint/epub_<hash>/sections/
|
||||
**Example** (incrementing section format version):
|
||||
```cpp
|
||||
// lib/Epub/Epub/Section.cpp
|
||||
static constexpr uint8_t SECTION_FILE_VERSION = 25; // Was 24, now 25
|
||||
static constexpr uint8_t SECTION_FILE_VERSION = 26; // Was 25, now 26
|
||||
|
||||
// Add new field to structure
|
||||
struct PageLine {
|
||||
|
||||
@@ -29,7 +29,7 @@ CrossPoint is open-source e-reader firmware - community-built, fully hackable, f
|
||||
- Web settings UI/API (edit many device settings from browser)
|
||||
- WebSocket fast uploads
|
||||
- WebDAV handler
|
||||
- AP mode (hotspot) and STA mode (join existing WiFi), both with QR helpers
|
||||
- AP mode (hotspot) and STA mode (join existing Wi-Fi), both with QR helpers
|
||||
- Calibre wireless connect flow
|
||||
- OPDS browser with saved servers (up to 8), search, pagination, and direct download
|
||||
- OTA update checks and installs from GitHub releases
|
||||
@@ -216,13 +216,18 @@ cache. This cache directory exists at `.crosspoint` on the SD card. The structur
|
||||
│ ├── progress.bin # reading position (chapter, page, etc.)
|
||||
│ ├── cover.bmp # generated cover image
|
||||
│ ├── book.bin # metadata: title, author, spine, TOC
|
||||
│ ├── css_rules.cache # parsed CSS rule cache
|
||||
│ ├── img_* # rendered image cache files
|
||||
│ └── sections/ # per-chapter layout cache
|
||||
│ ├── 0.bin
|
||||
│ ├── 1.bin
|
||||
│ └── ...
|
||||
├── settings.json # device settings
|
||||
├── state.json # resume/runtime state
|
||||
└── recent.json # recent books list
|
||||
```
|
||||
|
||||
Removing `/.crosspoint` clears all cached metadata and forces a full regeneration on next open. Note: the cache isn't cleared automatically when you delete a book, and moving a file to a new path resets its reading progress.
|
||||
Removing `/.crosspoint` clears all cached metadata and forces a full regeneration on next open. Book deletes, overwrites, and moves done through the firmware or web UI clear or re-key matching caches; manual SD-card edits may leave stale cache directories behind.
|
||||
|
||||
For more details on the internal file structures, see the [file formats document](./docs/file-formats.md).
|
||||
|
||||
|
||||
+19
-19
@@ -21,7 +21,7 @@ Welcome to the **CrossPoint** firmware. This guide outlines the hardware control
|
||||
- [3.6.3 Controls](#363-controls)
|
||||
- [3.6.4 System](#364-system)
|
||||
- [3.6.5 OPDS Servers (Multiple Libraries)](#365-opds-servers-multiple-libraries)
|
||||
- [3.6.6 Web Settings (WiFi + OPDS)](#366-web-settings-wifi--opds)
|
||||
- [3.6.6 Web Settings (Wi-Fi + OPDS)](#366-web-settings-wi-fi--opds)
|
||||
- [3.6.7 KOReader Sync Quick Setup](#367-koreader-sync-quick-setup)
|
||||
- [3.7 Sleep Screen](#37-sleep-screen)
|
||||
- [3.8 Custom Fonts (SD Card)](#38-custom-fonts-sd-card)
|
||||
@@ -103,15 +103,15 @@ The Recent Books screen lists the most recently opened books in a chronological
|
||||
|
||||
### 3.5 File Transfer Screen
|
||||
|
||||
The File Transfer screen allows you to upload new e-books to the device. When you enter the screen, you'll be prompted with a WiFi selection dialog and then your X4 will start hosting a web server.
|
||||
The File Transfer screen allows you to upload and manage files on the device. When you enter the screen, choose **Join a Network**, **Calibre Wireless**, or **Create Hotspot**. The reader then starts the web server for the selected mode.
|
||||
|
||||
See the [web server docs](./docs/webserver.md) for more information on how to connect to the web server and upload files.
|
||||
|
||||
The web interface also supports **WebDAV**, allowing you to mount the device as a network drive and manage files directly from your computer's file manager.
|
||||
|
||||
Download links for files already on the device are available in the web interface, so you can retrieve books or screenshots over WiFi without connecting a cable.
|
||||
Download links for files already on the device are available in the web interface, so you can retrieve books or screenshots over Wi-Fi without connecting a cable.
|
||||
|
||||
A **WiFi signal strength indicator** (dBm) is displayed on-screen during web server sessions.
|
||||
A **Wi-Fi signal strength indicator** (dBm) is displayed on-screen during joined-network web server sessions.
|
||||
|
||||
> [!TIP]
|
||||
> Advanced users can also manage files programmatically or via the command line using `curl`. See the [web server docs](./docs/webserver.md) for details.
|
||||
@@ -130,9 +130,9 @@ CrossPoint supports sending books from Calibre using the CrossPoint Reader devic
|
||||
|
||||
- Open Calibre → Preferences → Plugins → Load plugin from file → Select the zip file.
|
||||
|
||||
2. On the device: File Transfer → Connect to Calibre → Join a network.
|
||||
2. On the device: File Transfer -> Calibre Wireless, then join a network.
|
||||
|
||||
3. Make sure your computer is on the same WiFi network.
|
||||
3. Make sure your computer is on the same Wi-Fi network.
|
||||
|
||||
4. In Calibre, click "Send to device" to transfer books.
|
||||
|
||||
@@ -253,7 +253,7 @@ The Settings screen allows you to configure the device's behavior. There are a f
|
||||
|
||||
- **Time to Sleep**: Set the duration of inactivity before the device automatically goes to sleep; options are 1, 3, 5, 10 (default), 15 or 30 minutes.
|
||||
|
||||
- **WiFi Networks**: Connect to WiFi networks for file transfers and firmware updates.
|
||||
- **Wi-Fi Networks**: Connect to Wi-Fi networks for file transfers and firmware updates.
|
||||
|
||||
- **KOReader Sync**: Options for setting up KOReader for syncing book progress.
|
||||
|
||||
@@ -261,9 +261,9 @@ The Settings screen allows you to configure the device's behavior. There are a f
|
||||
|
||||
- **Clear Reading Cache**: Clear the internal SD card cache.
|
||||
|
||||
- **Check for updates**: Check for Crosspoint firmware updates over WiFi. Firmware can also be updated without a USB connection by placing a `firmware.bin` file on the SD card.
|
||||
- **Check for updates**: Check for Crosspoint firmware updates over Wi-Fi. Firmware can also be updated without a USB connection by placing a `firmware.bin` file on the SD card.
|
||||
|
||||
- **Language**: Set the UI language. CrossPoint supports 22 languages including English, Spanish, French, German, Czech, Portuguese, Russian, Swedish, Turkish, Danish, Finnish, Polish, Dutch, Belarusian, Italian, Ukrainian, Romanian, Catalan, Vietnamese, Kazakh, Slovenian, and more.
|
||||
- **Language**: Set the UI language. CrossPoint supports 24 languages: English, Spanish, French, German, Czech, Brazilian Portuguese, Russian, Swedish, Romanian, Catalan, Ukrainian, Belarusian, Italian, Polish, Finnish, Danish, Dutch, Turkish, Kazakh, Hungarian, Lithuanian, Slovenian, Valencian, and Hebrew.
|
||||
|
||||
- **Manage Fonts**: Browse, download, and manage custom font families installed from the SD card. See [Custom Fonts (SD Card)](#38-custom-fonts-sd-card) for more information.
|
||||
|
||||
@@ -296,22 +296,22 @@ You can also manage OPDS servers from the web interface while in File Transfer m
|
||||
2. Open `http://<device-ip>/settings`.
|
||||
3. Use the **OPDS Servers** card to add, edit, or delete entries.
|
||||
|
||||
For web-based WiFi network management, see [Web Settings (WiFi + OPDS)](#366-web-settings-wifi--opds).
|
||||
For web-based Wi-Fi network management, see [Web Settings (Wi-Fi + OPDS)](#366-web-settings-wi-fi--opds).
|
||||
|
||||
#### 3.6.6 Web Settings (WiFi + OPDS)
|
||||
#### 3.6.6 Web Settings (Wi-Fi + OPDS)
|
||||
|
||||
While in **File Transfer** mode, the web settings page includes management cards for both **WiFi Networks** and **OPDS Servers**.
|
||||
While in **File Transfer** mode, the web settings page includes management cards for both **Wi-Fi Networks** and **OPDS Servers**.
|
||||
|
||||
1. On device: open **File Transfer** and connect to WiFi.
|
||||
1. On device: open **File Transfer** and connect through **Join a Network** or **Create Hotspot**.
|
||||
2. In a browser, open `http://<device-ip>/settings` or `http://crosspoint.local`.
|
||||
3. In **WiFi Networks**, add, edit, or delete saved network entries (SSID + optional password).
|
||||
3. In **Wi-Fi Networks**, add, edit, or delete saved network entries (SSID + optional password).
|
||||
4. In **OPDS Servers**, add, edit, or delete OPDS catalogs.
|
||||
|
||||
Behavior notes:
|
||||
|
||||
- Passwords are never shown back in the web UI after saving.
|
||||
- Leaving Password blank while editing keeps the existing saved password unchanged.
|
||||
- The web UI can save hidden-network SSIDs, but connecting to hidden networks still depends on device-side WiFi connection flow.
|
||||
- The web UI can save hidden-network SSIDs, but connecting to hidden networks still depends on the device-side Wi-Fi connection flow.
|
||||
|
||||
#### 3.6.7 KOReader Sync Quick Setup
|
||||
|
||||
@@ -477,7 +477,7 @@ CrossPoint supports loading additional fonts from the SD card, extending beyond
|
||||
|
||||
There are three ways to install fonts:
|
||||
|
||||
1. **Download from device (recommended):** Go to **Settings → System → Manage Fonts**, browse the available font families, and select one to download over WiFi.
|
||||
1. **Download from device (recommended):** Go to **Settings -> System -> Manage Fonts**, browse the available font families, and select one to download over Wi-Fi.
|
||||
2. **Upload via web interface:** While in **File Transfer** mode, open the web UI in a browser and navigate to the **Fonts** tab to upload `.cpfont` files.
|
||||
3. **Manual SD card copy:** Download font files from the [crosspoint-fonts repository](https://github.com/crosspoint-reader/crosspoint-fonts) and copy them to `/.fonts/` (preferred) or `/fonts/` on your SD card.
|
||||
|
||||
@@ -533,9 +533,9 @@ CrossPoint renders text using the following Unicode character blocks, enabling s
|
||||
|
||||
* **Latin Script (Basic, Supplement, Extended-A/B):** Covers English, German, French, Spanish, Portuguese, Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Polish, Czech, Hungarian, Romanian, Slovak, Slovenian, Turkish, Catalan, and others.
|
||||
* **Cyrillic Script (Standard and Extended):** Covers Russian, Ukrainian, Belarusian, Bulgarian, Serbian, Macedonian, Kazakh, Kyrgyz, Mongolian, and others.
|
||||
* **Vietnamese:** Supported via extended Latin glyph coverage in the built-in fonts.
|
||||
* **Vietnamese:** Supported via extended Latin glyph coverage in the built-in reader fonts.
|
||||
|
||||
What is not supported with built-in fonts: Chinese, Japanese, Korean, Hebrew, Arabic, Greek, and Farsi. However, **CJK and other extended scripts can be enabled by installing custom SD card fonts** — see [Custom Fonts (SD Card)](#38-custom-fonts-sd-card).
|
||||
What is not supported with built-in reader fonts: Chinese, Japanese, Korean, Arabic, Greek, Hebrew, and Farsi. However, **CJK, Hebrew, Greek, and other extended scripts can be enabled by installing custom SD card fonts** — see [Custom Fonts (SD Card)](#38-custom-fonts-sd-card).
|
||||
|
||||
---
|
||||
|
||||
@@ -638,4 +638,4 @@ Press **Ctrl-C** or close the graph window to exit.
|
||||
|
||||
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).
|
||||
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.json`, `state.json`, or `epub_*` cache directories in the `.crosspoint/` folder).
|
||||
|
||||
@@ -8,17 +8,18 @@ At a high level, it is firmware that uses an activity-driven application archite
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Hardware: ESP32-C3 + SD + E-ink + Buttons] --> B[open-x4-sdk HAL]
|
||||
B --> C[src/main.cpp runtime loop]
|
||||
C --> D[Activities layer]
|
||||
C --> E[State and settings]
|
||||
D --> F[Reader flows]
|
||||
D --> G[Home/Library/Settings flows]
|
||||
D --> H[Network/Web server flows]
|
||||
F --> I[lib/Epub parsing + layout + hyphenation]
|
||||
I --> J[SD cache in .crosspoint]
|
||||
D --> K[GfxRenderer]
|
||||
K --> L[E-ink display buffer]
|
||||
A[Hardware: ESP32-C3 + SD + E-ink + Buttons] --> B[open-x4-sdk]
|
||||
B --> C[lib/hal wrappers]
|
||||
C --> D[src/main.cpp runtime loop]
|
||||
D --> E[Activities layer]
|
||||
D --> F[State and settings]
|
||||
E --> G[Reader flows]
|
||||
E --> H[Home/Library/Settings flows]
|
||||
E --> I[Network/Web server flows]
|
||||
G --> J[lib/Epub parsing + layout + hyphenation]
|
||||
J --> K[SD cache in .crosspoint]
|
||||
E --> L[GfxRenderer]
|
||||
L --> M[E-ink display buffer]
|
||||
```
|
||||
|
||||
## Runtime lifecycle
|
||||
@@ -58,7 +59,7 @@ Top-level activity groups:
|
||||
- `src/activities/home/`: home and library navigation
|
||||
- `src/activities/reader/`: EPUB/XTC/TXT reading flows
|
||||
- `src/activities/settings/`: settings menus and configuration
|
||||
- `src/activities/network/`: WiFi selection, AP/STA mode, file transfer server
|
||||
- `src/activities/network/`: Wi-Fi selection, AP/STA mode, file transfer server
|
||||
- `src/activities/boot_sleep/`: boot and sleep transitions
|
||||
|
||||
## Reader and content pipeline
|
||||
@@ -73,10 +74,11 @@ flowchart LR
|
||||
C -->|EPUB| D[lib/Epub/Epub]
|
||||
C -->|XTC| E[lib/Xtc reader]
|
||||
C -->|TXT| F[lib/Txt reader]
|
||||
D --> G[Parse OPF/TOC/CSS]
|
||||
G --> H[Layout pages/sections]
|
||||
H --> I[Write section and metadata caches]
|
||||
I --> J[Render current page via GfxRenderer]
|
||||
D --> G[Parse OPF/TOC and collect CSS refs]
|
||||
G --> H[Build/load book.bin and css_rules.cache]
|
||||
H --> I[Layout pages/sections]
|
||||
I --> J[Write section cache]
|
||||
J --> K[Render current page via GfxRenderer]
|
||||
```
|
||||
|
||||
Why caching matters:
|
||||
@@ -98,7 +100,7 @@ flowchart TD
|
||||
D --> E[Locate container and OPF]
|
||||
E --> F[Build or load BookMetadataCache]
|
||||
F --> G[Load TOC and spine]
|
||||
G --> H[Load or parse CSS rules]
|
||||
G --> H[Load CSS cache or parse manifest/base-dir CSS]
|
||||
|
||||
H --> I[EpubReaderActivity]
|
||||
I --> J{Section cache exists for current settings?}
|
||||
@@ -121,7 +123,12 @@ flowchart TD
|
||||
|
||||
Notes:
|
||||
|
||||
- "section cache exists" depends on cache-busting parameters such as font and layout-related settings
|
||||
- CSS files are collected from the OPF manifest and, when needed, discovered by
|
||||
streaming ZIP paths under the OPF content base directory; the firmware avoids
|
||||
preloading the full ZIP central directory for large books.
|
||||
- "section cache exists" depends on cache-busting parameters such as font,
|
||||
viewport size, paragraph alignment, hyphenation, embedded CSS, image rendering,
|
||||
and Focus Reading settings
|
||||
- rendering favors reusing precomputed layout data to keep page turns responsive on constrained hardware
|
||||
- progress/session state is persisted so the reader can reopen at the last position after reboot/sleep
|
||||
|
||||
@@ -138,14 +145,18 @@ Typical persisted areas on SD:
|
||||
/.crosspoint/
|
||||
epub_<hash>/
|
||||
book.bin
|
||||
css_rules.cache
|
||||
progress.bin
|
||||
cover.bmp
|
||||
sections/*.bin
|
||||
settings.bin
|
||||
state.bin
|
||||
img_* cache files
|
||||
settings.json
|
||||
state.json
|
||||
```
|
||||
|
||||
For binary cache formats, see `docs/file-formats.md`.
|
||||
`sections/*.bin` contains rendered pages plus anchor, paragraph, and list-item
|
||||
lookup tables used for TOC/footnote jumps and KOReader sync refinement. For
|
||||
binary cache formats, see `docs/file-formats.md`.
|
||||
|
||||
## Networking architecture
|
||||
|
||||
@@ -153,14 +164,18 @@ Network file transfer is controlled by `src/activities/network/CrossPointWebServ
|
||||
|
||||
Modes:
|
||||
|
||||
- STA: join existing WiFi network
|
||||
- STA: join existing Wi-Fi network
|
||||
- AP: create hotspot
|
||||
- Calibre Wireless: STA flow specialized for Calibre plugin uploads
|
||||
|
||||
Server behavior:
|
||||
|
||||
- HTTP server on port 80
|
||||
- WebSocket upload server on port 81
|
||||
- WebDAV handler on the HTTP server
|
||||
- UDP discovery listener for upload clients
|
||||
- file operations backed by SD storage
|
||||
- browser APIs for file management, settings, fonts, OPDS servers, and saved Wi-Fi networks
|
||||
- activity requests faster loop responsiveness while server is running
|
||||
|
||||
Endpoint reference: `docs/webserver-endpoints.md`.
|
||||
@@ -170,6 +185,7 @@ Endpoint reference: `docs/webserver-endpoints.md`.
|
||||
Some sources are generated and should not be edited manually.
|
||||
|
||||
- `scripts/build_html.py` generates `src/network/html/*.generated.h` from HTML files
|
||||
- `scripts/gen_i18n.py` generates `lib/I18n/I18nKeys.h`, `I18nStrings.h`, and `I18nStrings.cpp`
|
||||
- `scripts/generate_hyphenation_trie.py` generates hyphenation headers under `lib/Epub/Epub/hyphenation/generated/`
|
||||
|
||||
When editing related source assets, regenerate via normal build steps/scripts.
|
||||
@@ -179,6 +195,7 @@ When editing related source assets, regenerate via normal build steps/scripts.
|
||||
- `src/`: app orchestration, settings/state, and activity implementations
|
||||
- `src/network/`: web server and OTA/update networking
|
||||
- `src/components/`: theming and shared UI components
|
||||
- `lib/hal/`: hardware abstraction wrappers around open-x4-sdk
|
||||
- `lib/Epub/`: EPUB parser, layout, CSS handling, and hyphenation
|
||||
- `lib/`: supporting libraries (fonts, text, filesystem helpers, etc.)
|
||||
- `open-x4-sdk/`: hardware SDK submodule (display, input, storage, battery)
|
||||
|
||||
+150
-85
@@ -1,22 +1,26 @@
|
||||
# File Formats
|
||||
|
||||
These formats describe the SD-card cache files under `/.crosspoint/epub_<hash>/`.
|
||||
All POD fields are written in the ESP32 little-endian representation used by
|
||||
`Serialization.h`; strings are length-prefixed UTF-8.
|
||||
|
||||
## `book.bin`
|
||||
|
||||
### Version 5
|
||||
### Version 7
|
||||
|
||||
ImHex Pattern:
|
||||
`book.bin` stores EPUB metadata plus lookup tables for spine and TOC entries.
|
||||
The current firmware writes this version from `BookMetadataCache`.
|
||||
|
||||
ImHex pattern:
|
||||
|
||||
```c++
|
||||
import std.mem;
|
||||
import std.string;
|
||||
import std.core;
|
||||
|
||||
// === Configuration ===
|
||||
#define EXPECTED_VERSION 5
|
||||
#define EXPECTED_VERSION 7
|
||||
#define MAX_STRING_LENGTH 65535
|
||||
|
||||
// === String Structure ===
|
||||
|
||||
struct String {
|
||||
u32 length [[hidden, comment("String byte length")]];
|
||||
if (length > MAX_STRING_LENGTH) {
|
||||
@@ -29,75 +33,56 @@ fn format_string(String s) {
|
||||
return s.data;
|
||||
};
|
||||
|
||||
// === Metadata Structure ===
|
||||
|
||||
struct Metadata {
|
||||
String title [[comment("Book title")]];
|
||||
String author [[comment("Book author")]];
|
||||
String language [[comment("Book language code")]];
|
||||
String coverItemHref [[comment("Path to cover image")]];
|
||||
String textReferenceHref [[comment("Path to guided first text reference")]];
|
||||
} [[comment("Book metadata information")]];
|
||||
|
||||
// === Spine Entry Structure ===
|
||||
};
|
||||
|
||||
struct SpineEntry {
|
||||
String href [[comment("Resource path")]];
|
||||
u32 cumulativeSize [[comment("Cumulative size in bytes"), color("FF6B6B")]];
|
||||
s16 tocIndex [[comment("Index into TOC (-1 if none)"), color("4ECDC4")]];
|
||||
} [[comment("Spine entry defining reading order")]];
|
||||
|
||||
// === TOC Entry Structure ===
|
||||
u32 cumulativeSize [[comment("Cumulative uncompressed spine size through this entry")]];
|
||||
s16 tocIndex [[comment("Index into TOC, or inherited/previous TOC index when no direct entry exists")]];
|
||||
};
|
||||
|
||||
struct TocEntry {
|
||||
String title [[comment("Chapter/section title")]];
|
||||
String href [[comment("Resource path")]];
|
||||
String anchor [[comment("Fragment identifier")]];
|
||||
u8 level [[comment("Nesting level (0-255)"), color("95E1D3")]];
|
||||
s16 spineIndex [[comment("Index into spine (-1 if none)"), color("F38181")]];
|
||||
} [[comment("Table of contents entry")]];
|
||||
|
||||
// === Book Bin Structure ===
|
||||
u8 level [[comment("Nesting level")]];
|
||||
s16 spineIndex [[comment("Index into spine (-1 if none)")]];
|
||||
};
|
||||
|
||||
struct BookBin {
|
||||
// Header
|
||||
u8 version [[comment("Format version"), color("FFD93D")]];
|
||||
|
||||
// Version validation
|
||||
u8 version;
|
||||
if (version != EXPECTED_VERSION) {
|
||||
std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
|
||||
}
|
||||
|
||||
u32 lutOffset [[comment("Offset to lookup tables"), color("6BCB77")]];
|
||||
u16 spineCount [[comment("Number of spine entries"), color("4D96FF")]];
|
||||
u16 tocCount [[comment("Number of TOC entries"), color("FF6B9D")]];
|
||||
u32 lutOffset [[comment("Offset to lookup tables")]];
|
||||
u16 spineCount;
|
||||
u16 tocCount;
|
||||
|
||||
// Metadata section
|
||||
Metadata metadata [[comment("Book metadata")]];
|
||||
Metadata metadata;
|
||||
|
||||
// Validate LUT offset alignment
|
||||
u32 currentOffset = $;
|
||||
if (currentOffset != lutOffset) {
|
||||
std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
|
||||
}
|
||||
|
||||
// Lookup Tables
|
||||
u32 spineLut[spineCount] [[comment("Spine entry offsets"), color("4D96FF")]];
|
||||
u32 tocLut[tocCount] [[comment("TOC entry offsets"), color("FF6B9D")]];
|
||||
u32 spineLut[spineCount] [[comment("Spine entry offsets")]];
|
||||
u32 tocLut[tocCount] [[comment("TOC entry offsets")]];
|
||||
|
||||
// Data Entries
|
||||
SpineEntry spines[spineCount] [[comment("Spine entries (reading order)")]];
|
||||
TocEntry toc[tocCount] [[comment("Table of contents entries")]];
|
||||
SpineEntry spines[spineCount];
|
||||
TocEntry toc[tocCount];
|
||||
};
|
||||
|
||||
// === File Parsing ===
|
||||
|
||||
BookBin book @ 0x00;
|
||||
|
||||
// Validate we've consumed the entire file
|
||||
u32 fileSize = std::mem::size();
|
||||
u32 parsedSize = $;
|
||||
|
||||
if (parsedSize != fileSize) {
|
||||
std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
|
||||
}
|
||||
@@ -105,20 +90,33 @@ if (parsedSize != fileSize) {
|
||||
|
||||
## `section.bin`
|
||||
|
||||
### Version 24
|
||||
### Version 25
|
||||
|
||||
ImHex Pattern:
|
||||
Each file in `sections/*.bin` stores one laid-out spine section. The header is
|
||||
also the cache-busting key: if any layout-affecting setting differs from the
|
||||
current reader settings, the section is discarded and rebuilt.
|
||||
|
||||
Version 25 includes:
|
||||
|
||||
- cache-busting fields for paragraph alignment, hyphenation, embedded CSS,
|
||||
image rendering mode, and Focus Reading
|
||||
- page offset LUT
|
||||
- anchor-to-page map for fragment and footnote navigation
|
||||
- paragraph and list-item LUTs used by KOReader sync page refinement
|
||||
- optional per-word Focus Reading split metadata
|
||||
- per-page footnote entries
|
||||
|
||||
ImHex pattern:
|
||||
|
||||
```c++
|
||||
import std.mem;
|
||||
import std.string;
|
||||
import std.core;
|
||||
|
||||
// === Configuration ===
|
||||
#define EXPECTED_VERSION 24
|
||||
#define EXPECTED_VERSION 25
|
||||
#define MAX_STRING_LENGTH 65535
|
||||
|
||||
// === String Structure ===
|
||||
#define FOOTNOTE_NUMBER_LEN 32
|
||||
#define FOOTNOTE_HREF_LEN 96
|
||||
|
||||
struct String {
|
||||
u32 length [[hidden, comment("String byte length")]];
|
||||
@@ -132,44 +130,79 @@ fn format_string(String s) {
|
||||
return s.data;
|
||||
};
|
||||
|
||||
// === Page Structure ===
|
||||
|
||||
enum PageElementTag : u8 {
|
||||
PageLine = 1,
|
||||
PageImage = 2,
|
||||
PageHorizontalRule = 3
|
||||
TAG_PageLine = 1,
|
||||
TAG_PageImage = 2,
|
||||
TAG_PageHorizontalRule = 3
|
||||
};
|
||||
|
||||
enum WordStyle : u8 {
|
||||
REGULAR = 0,
|
||||
BOLD = 1,
|
||||
ITALIC = 2,
|
||||
BOLD_ITALIC = 3
|
||||
BOLD_ITALIC = 3,
|
||||
UNDERLINE = 4,
|
||||
STRIKETHROUGH = 8,
|
||||
SUP = 16,
|
||||
SUB = 32
|
||||
};
|
||||
|
||||
enum BlockStyle : u8 {
|
||||
enum TextAlign : u8 {
|
||||
JUSTIFIED = 0,
|
||||
LEFT_ALIGN = 1,
|
||||
CENTER_ALIGN = 2,
|
||||
RIGHT_ALIGN = 3,
|
||||
NONE = 4
|
||||
};
|
||||
|
||||
struct BlockStyle {
|
||||
TextAlign alignment;
|
||||
bool textAlignDefined;
|
||||
s16 marginTop;
|
||||
s16 marginBottom;
|
||||
s16 marginLeft;
|
||||
s16 marginRight;
|
||||
s16 paddingTop;
|
||||
s16 paddingBottom;
|
||||
s16 paddingLeft;
|
||||
s16 paddingRight;
|
||||
s16 textIndent;
|
||||
bool textIndentDefined;
|
||||
bool isRtl;
|
||||
bool directionDefined;
|
||||
};
|
||||
|
||||
struct TextBlock {
|
||||
u16 wordCount;
|
||||
String words[wordCount];
|
||||
s16 wordXPos[wordCount];
|
||||
WordStyle wordStyle[wordCount];
|
||||
|
||||
u8 hasFocus;
|
||||
if (hasFocus != 0) {
|
||||
u8 wordFocusBoundary[wordCount] [[comment("UTF-8 byte boundary between bold prefix and suffix")]];
|
||||
u16 wordFocusSuffixX[wordCount] [[comment("Suffix x offset from word start")]];
|
||||
}
|
||||
|
||||
BlockStyle blockStyle;
|
||||
};
|
||||
|
||||
struct ImageBlock {
|
||||
String imagePath;
|
||||
s16 width;
|
||||
s16 height;
|
||||
};
|
||||
|
||||
struct PageLine {
|
||||
s16 xPos;
|
||||
s16 yPos;
|
||||
u16 wordCount;
|
||||
String words[wordCount];
|
||||
u16 wordXPos[wordCount];
|
||||
WordStyle wordStyle[wordCount];
|
||||
BlockStyle blockStyle;
|
||||
TextBlock block;
|
||||
};
|
||||
|
||||
struct PageImage {
|
||||
s16 xPos;
|
||||
s16 yPos;
|
||||
String imagePath;
|
||||
s16 width;
|
||||
s16 height;
|
||||
ImageBlock image;
|
||||
};
|
||||
|
||||
struct PageHorizontalRule {
|
||||
@@ -180,63 +213,95 @@ struct PageHorizontalRule {
|
||||
};
|
||||
|
||||
struct PageElement {
|
||||
u8 pageElementType;
|
||||
if (pageElementType == 1) {
|
||||
PageElementTag pageElementType;
|
||||
if (pageElementType == TAG_PageLine) {
|
||||
PageLine pageLine [[inline]];
|
||||
} else if (pageElementType == 2) {
|
||||
} else if (pageElementType == TAG_PageImage) {
|
||||
PageImage pageImage [[inline]];
|
||||
} else if (pageElementType == 3) {
|
||||
} else if (pageElementType == TAG_PageHorizontalRule) {
|
||||
PageHorizontalRule horizontalRule [[inline]];
|
||||
} else {
|
||||
std::error(std::format("Unknown page element type: {}", pageElementType));
|
||||
}
|
||||
};
|
||||
|
||||
struct FootnoteEntry {
|
||||
char number[FOOTNOTE_NUMBER_LEN];
|
||||
char href[FOOTNOTE_HREF_LEN];
|
||||
};
|
||||
|
||||
struct Page {
|
||||
u16 elementCount;
|
||||
PageElement elements[elementCount] [[inline]];
|
||||
|
||||
u16 footnoteCount;
|
||||
FootnoteEntry footnotes[footnoteCount];
|
||||
};
|
||||
|
||||
// === Section Bin Structure ===
|
||||
struct AnchorEntry {
|
||||
String anchor;
|
||||
u16 page;
|
||||
};
|
||||
|
||||
struct AnchorMap {
|
||||
u16 count;
|
||||
AnchorEntry entries[count];
|
||||
};
|
||||
|
||||
struct ParagraphLut {
|
||||
u16 count;
|
||||
u16 paragraphIndex[count];
|
||||
};
|
||||
|
||||
struct SectionBin {
|
||||
// Header
|
||||
u8 version [[comment("Format version"), color("FFD93D")]];
|
||||
|
||||
// Version validation
|
||||
u8 version;
|
||||
if (version != EXPECTED_VERSION) {
|
||||
std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
|
||||
}
|
||||
|
||||
// Cache busting parameters
|
||||
s32 fontId;
|
||||
float lineCompression;
|
||||
bool extraParagraphSpacing;
|
||||
u8 paragraphAlignment;
|
||||
u16 viewportWidth;
|
||||
u16 vieportHeight;
|
||||
u16 viewportHeight;
|
||||
bool hyphenationEnabled;
|
||||
bool embeddedStyle;
|
||||
u8 imageRendering;
|
||||
bool focusReadingEnabled;
|
||||
|
||||
u16 pageCount;
|
||||
u32 lutOffset;
|
||||
u32 pageLutOffset;
|
||||
u32 anchorMapOffset;
|
||||
u32 paragraphLutOffset;
|
||||
u32 listItemLutOffset;
|
||||
|
||||
Page page[pageCount];
|
||||
Page pages[pageCount];
|
||||
|
||||
// Validate LUT offset alignment
|
||||
u32 currentOffset = $;
|
||||
if (currentOffset != lutOffset) {
|
||||
std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
|
||||
if (currentOffset != pageLutOffset) {
|
||||
std::warning(std::format("Page LUT offset mismatch: expected 0x{:X}, got 0x{:X}", pageLutOffset, currentOffset));
|
||||
}
|
||||
|
||||
// Lookup Tables
|
||||
u32 lut[pageCount];
|
||||
u32 pageLut[pageCount] [[comment("Page data offsets")]];
|
||||
|
||||
if (anchorMapOffset != 0) {
|
||||
AnchorMap anchorMap @ anchorMapOffset;
|
||||
}
|
||||
|
||||
if (paragraphLutOffset != 0) {
|
||||
ParagraphLut paragraphLut @ paragraphLutOffset;
|
||||
}
|
||||
|
||||
if (listItemLutOffset != 0 && paragraphLutOffset != 0) {
|
||||
u16 listItemIndex[paragraphLut.count] @ listItemLutOffset;
|
||||
}
|
||||
};
|
||||
|
||||
// === File Parsing ===
|
||||
SectionBin section @ 0x00;
|
||||
|
||||
SectionBin book @ 0x00;
|
||||
|
||||
// Validate we've consumed the entire file
|
||||
u32 fileSize = std::mem::size();
|
||||
u32 parsedSize = $;
|
||||
|
||||
if (parsedSize != fileSize) {
|
||||
std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
|
||||
}
|
||||
|
||||
@@ -11,7 +11,7 @@ Focus Reading is a reading aid that bolds the first portion of each word, guidin
|
||||
1. Open **Settings > Reader**
|
||||
2. Toggle **Focus Reading** on
|
||||
|
||||
Toggling the setting will trigger a re-index of your current book, the same as when changing font settings. Once indexing is complete, page turns proceed as normal. No changes are made to your EPUB files.
|
||||
Toggling the setting invalidates affected EPUB section caches for the current layout, the same as changing font settings. Sections are rebuilt on demand, then page turns proceed as normal. No changes are made to your EPUB files.
|
||||
|
||||
## Examples
|
||||
|
||||
|
||||
+42
-23
@@ -5,17 +5,29 @@ This guide explains the multi-language support system in CrossPoint Reader.
|
||||
## Supported Languages
|
||||
|
||||
- English
|
||||
- French
|
||||
- German
|
||||
- Portuguese
|
||||
- Spanish
|
||||
- Swedish
|
||||
- Czech
|
||||
- Russian
|
||||
- Ukrainian
|
||||
- Polish
|
||||
- Danish
|
||||
- Turkish
|
||||
- Español
|
||||
- Français
|
||||
- Deutsch
|
||||
- Čeština
|
||||
- Português (Brasil)
|
||||
- Русский
|
||||
- Svenska
|
||||
- Română
|
||||
- Català
|
||||
- Українська
|
||||
- Беларуская
|
||||
- Italiano
|
||||
- Polski
|
||||
- Suomi
|
||||
- Dansk
|
||||
- Nederlands
|
||||
- Türkçe
|
||||
- Қазақша
|
||||
- Magyar
|
||||
- Lietuvių
|
||||
- Slovenščina
|
||||
- Valencià
|
||||
- עברית
|
||||
|
||||
---
|
||||
|
||||
@@ -108,7 +120,9 @@ This automatically:
|
||||
#### 3. Use in code
|
||||
|
||||
```cpp
|
||||
#include <CrossPointSettings.h>
|
||||
#include <I18n.h>
|
||||
#include <Logging.h>
|
||||
|
||||
// Using the tr() macro (recommended)
|
||||
renderer.drawText(font, x, y, tr(STR_MY_NEW_STRING));
|
||||
@@ -175,7 +189,7 @@ The YAML files use UTF-8 encoding. Special characters are automatically converte
|
||||
// tr(id) - Get translated string without StrId:: prefix
|
||||
const char* text = tr(STR_SETTINGS_TITLE);
|
||||
renderer.drawText(font, x, y, tr(STR_BROWSE_FILES));
|
||||
Serial.printf("Status: %s\n", tr(STR_CONNECTED));
|
||||
LOG_INF("I18N", "Status: %s", tr(STR_CONNECTED));
|
||||
|
||||
// I18N - Shorthand for I18n::getInstance()
|
||||
I18N.setLanguage(Language::ES);
|
||||
@@ -191,34 +205,39 @@ const char* text = tr(STR_SETTINGS_TITLE); // Macro (recommended)
|
||||
const char* text = I18N.get(StrId::STR_SETTINGS_TITLE); // Direct call
|
||||
const char* text = I18N[StrId::STR_SETTINGS_TITLE]; // Operator overload
|
||||
|
||||
// Set language
|
||||
// Set runtime language
|
||||
I18N.setLanguage(Language::ES);
|
||||
|
||||
// Get current language
|
||||
Language lang = I18N.getLanguage();
|
||||
|
||||
// Save language setting to file
|
||||
I18N.saveSettings();
|
||||
|
||||
// Load language setting from file
|
||||
I18N.loadSettings();
|
||||
|
||||
// Get character set for font subsetting (static method)
|
||||
const char* chars = I18n::getCharacterSet(Language::FR);
|
||||
|
||||
// Persist a user language choice
|
||||
SETTINGS.language = static_cast<uint8_t>(Language::ES);
|
||||
SETTINGS.saveToFile();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Storage
|
||||
|
||||
Language settings are stored in:
|
||||
The selected language is stored with the rest of the device settings in:
|
||||
```text
|
||||
/.crosspoint/settings.json
|
||||
```
|
||||
|
||||
The JSON field is `language`, stored as a stable language code string such as
|
||||
`"EN"`, `"DE"`, or `"HE"` rather than a raw enum value.
|
||||
|
||||
Older firmware versions used:
|
||||
```text
|
||||
/.crosspoint/language.bin
|
||||
```
|
||||
|
||||
This file contains:
|
||||
- Version byte
|
||||
- Current language selection (1 byte)
|
||||
On load, current firmware migrates that legacy file into `settings.json` and
|
||||
renames it to `language.bin.bak`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -9,15 +9,15 @@ There are three ways to install fonts:
|
||||
|
||||
### Option 1: Download from device (recommended)
|
||||
|
||||
1. Connect your CrossPoint reader to WiFi
|
||||
1. Connect your CrossPoint reader to Wi-Fi
|
||||
2. Go to **Settings > System > Manage Fonts**
|
||||
3. Browse available font families and tap to download
|
||||
4. Downloaded fonts appear immediately in **Settings > Reader > Font Family**
|
||||
|
||||
### Option 2: Upload via web browser
|
||||
|
||||
1. Connect your CrossPoint reader to WiFi
|
||||
2. Open the web interface in your browser (shown on the WiFi screen)
|
||||
1. Start **File Transfer** and connect through **Join Network** or **Create Hotspot**
|
||||
2. Open the web interface URL shown on the reader
|
||||
3. Navigate to the **Fonts** tab
|
||||
4. Upload `.cpfont` files using the upload form
|
||||
|
||||
@@ -96,6 +96,7 @@ To convert your own TrueType/OpenType fonts:
|
||||
| `latin-ext` | European languages (Latin + Extended-A/B + punctuation + ligatures) |
|
||||
| `greek` | Greek + Extended Greek |
|
||||
| `cyrillic` | Cyrillic + Supplement |
|
||||
| `hebrew` | Hebrew + Alphabetic Presentation Forms |
|
||||
| `georgian` | Georgian + Georgian Supplement |
|
||||
| `armenian` | Armenian |
|
||||
| `ethiopic` | Ethiopic + Extended |
|
||||
@@ -107,7 +108,7 @@ To convert your own TrueType/OpenType fonts:
|
||||
| `tifinagh` | Tifinagh |
|
||||
| `symbols` | Math, currency, arrows, box-drawing, misc symbols, dingbats |
|
||||
| `reading` | Literary fiction coverage: Latin, Greek, Cyrillic, math/symbol blocks, supplemental punctuation, and CJK quote marks |
|
||||
| `builtin` | Matches built-in Bookerly coverage exactly |
|
||||
| `builtin` | Matches the firmware's built-in font conversion intervals |
|
||||
|
||||
Combine presets with commas: `--intervals latin-ext,greek,cyrillic`
|
||||
|
||||
@@ -122,4 +123,4 @@ To list all presets with codepoint counts:
|
||||
|
||||
`--force-autohint` — force FreeType's auto-hinter instead of the font's native hinting (useful when a font's built-in hints produce poor results at small sizes).
|
||||
|
||||
Install custom fonts via WiFi upload or manual SD card copy.
|
||||
Install custom fonts via the web interface or manual SD card copy.
|
||||
|
||||
+6
-2
@@ -1,7 +1,9 @@
|
||||
# Translators
|
||||
|
||||
Below is a list of users and languages CrossPoint may support in the future.
|
||||
Note because a language is below does not mean there is official support for the language at this time.
|
||||
Below is a list of translator credits for languages with known contributors.
|
||||
Official UI language support is determined by the YAML files in
|
||||
`lib/I18n/translations/`; see [i18n.md](./i18n.md) for the current supported
|
||||
language list.
|
||||
|
||||
## Contributing
|
||||
|
||||
@@ -37,6 +39,7 @@ If you'd like to add your name to this list, please open a PR adding yourself an
|
||||
- [Skrzakk](https://github.com/Skrzakk)
|
||||
- [pablohc](https://github.com/pablohc)
|
||||
- [DaniPhii](https://github.com/DaniPhii)
|
||||
- [lpla](https://github.com/lpla)
|
||||
|
||||
## Swedish
|
||||
- [dawiik](https://github.com/dawiik)
|
||||
@@ -47,6 +50,7 @@ If you'd like to add your name to this list, please open a PR adding yourself an
|
||||
|
||||
## Catalan
|
||||
- [angeldenom](https://github.com/angeldenom)
|
||||
- [lpla](https://github.com/lpla)
|
||||
|
||||
## Finnish
|
||||
- [plahteenlahti](https://github.com/plahteenlahti)
|
||||
|
||||
+13
-10
@@ -1,6 +1,6 @@
|
||||
# Troubleshooting
|
||||
|
||||
This document show most common issues and possible solutions while using the device features.
|
||||
This document shows 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)
|
||||
@@ -14,25 +14,27 @@ This document show most common issues and possible solutions while using the dev
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Verify both devices are on the **same WiFi network**
|
||||
- Check your computer/phone WiFi settings
|
||||
- Confirm the CrossPoint Reader shows "Connected" status
|
||||
1. Verify both devices are on the correct network
|
||||
- Check your computer/phone Wi-Fi settings
|
||||
- In **Join Network** mode, your computer/phone and CrossPoint Reader must be on the same Wi-Fi network
|
||||
- In **Create Hotspot** mode, your computer/phone must be connected to the `CrossPoint-Reader` hotspot
|
||||
2. Double-check the IP address
|
||||
- Make sure you typed it correctly
|
||||
- Include `http://` at the beginning
|
||||
- Try the displayed IP address if `http://crosspoint.local/` does not resolve
|
||||
3. Try disabling VPN if you're using one
|
||||
4. Some networks have "client isolation" enabled - check with your network administrator
|
||||
4. Some networks have "client isolation" enabled - use Create Hotspot mode or check with your network administrator
|
||||
|
||||
### Connection Drops or Times Out
|
||||
|
||||
**Problem:** WiFi connection is unstable
|
||||
**Problem:** Wi-Fi connection is unstable
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Move closer to the WiFi router
|
||||
1. Move closer to the Wi-Fi router, or use Create Hotspot mode for a direct connection
|
||||
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
|
||||
4. Try a different Wi-Fi network if available
|
||||
|
||||
### Upload Fails
|
||||
|
||||
@@ -40,10 +42,11 @@ This document show most common issues and possible solutions while using the dev
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Ensure the file is a valid `.epub` file
|
||||
2. Check that the SD card has enough free space
|
||||
1. Check that the SD card has enough free space
|
||||
2. Check that the filename is valid for the SD card filesystem
|
||||
3. Try uploading a smaller file first to test
|
||||
4. Refresh the browser page and try again
|
||||
5. If WebSocket upload fails repeatedly, refresh the page and retry with the HTTP fallback path
|
||||
|
||||
### Saved Password Not Working
|
||||
|
||||
|
||||
+392
-224
@@ -1,72 +1,36 @@
|
||||
# Webserver Endpoints
|
||||
|
||||
This document describes all HTTP and WebSocket endpoints available on the CrossPoint Reader webserver.
|
||||
This document describes the HTTP, WebSocket, WebDAV, and discovery endpoints
|
||||
available while CrossPoint Reader is in File Transfer or Calibre Wireless mode.
|
||||
|
||||
- [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)
|
||||
- HTTP server: port 80
|
||||
- WebSocket upload server: port 81
|
||||
- UDP discovery listener: port 8134
|
||||
- WebDAV: port 80, handled by the same HTTP server
|
||||
|
||||
Examples use `crosspoint.local`. If mDNS does not resolve on your network, use
|
||||
the IP address shown on the device screen.
|
||||
|
||||
## Overview
|
||||
## HTTP Pages
|
||||
|
||||
The CrossPoint Reader exposes a webserver for file management and device monitoring:
|
||||
| Method | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| `GET` | `/` | Home/status page |
|
||||
| `GET` | `/files` | File manager page |
|
||||
| `GET` | `/settings` | Web settings page |
|
||||
| `GET` | `/fonts` | SD-card font manager page |
|
||||
| `GET` | `/js/jszip.min.js` | JavaScript asset used by the file manager |
|
||||
|
||||
- **HTTP Server**: Port 80
|
||||
- **WebSocket Server**: Port 81 (for fast binary uploads)
|
||||
## Device Status
|
||||
|
||||
---
|
||||
### `GET /api/status`
|
||||
|
||||
## 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):**
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
@@ -74,259 +38,463 @@ curl http://crosspoint.local/api/status
|
||||
"mode": "STA",
|
||||
"rssi": -45,
|
||||
"freeHeap": 123456,
|
||||
"uptime": 3600
|
||||
"uptime": 3600,
|
||||
"device": "X4"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
| ---------- | ------ | --------------------------------------------------------- |
|
||||
| `version` | string | CrossPoint firmware version |
|
||||
|-------|------|-------------|
|
||||
| `version` | string | 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 |
|
||||
| `mode` | string | `"STA"` for joined Wi-Fi or `"AP"` for hotspot mode |
|
||||
| `rssi` | number | Wi-Fi RSSI in dBm; `0` in AP mode |
|
||||
| `freeHeap` | number | Free heap in bytes |
|
||||
| `uptime` | number | Seconds since boot |
|
||||
| `device` | string | `"X3"` or `"X4"` hardware detection |
|
||||
|
||||
---
|
||||
## File Management
|
||||
|
||||
### GET `/api/files` - List Files
|
||||
### `GET /api/files`
|
||||
|
||||
Returns a JSON array of files and folders in the specified directory.
|
||||
Lists files and folders under a 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:**
|
||||
Query parameters:
|
||||
|
||||
| Parameter | Required | Default | Description |
|
||||
| --------- | -------- | ------- | ---------------------- |
|
||||
| `path` | No | `/` | Directory path to list |
|
||||
|-----------|----------|---------|-------------|
|
||||
| `path` | No | `/` | Directory to list |
|
||||
|
||||
Response:
|
||||
|
||||
**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}
|
||||
{"name":"Notes","size":0,"isDirectory":true,"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 |
|
||||
Hidden dotfiles are omitted unless the device setting `showHiddenFiles` is
|
||||
enabled. `System Volume Information` and `XTCache` are always hidden/protected.
|
||||
|
||||
**Notes:**
|
||||
- Hidden files (starting with `.`) are automatically filtered out
|
||||
- System folders (`System Volume Information`, `XTCache`) are hidden
|
||||
### `GET /download`
|
||||
|
||||
---
|
||||
Downloads a file from the SD card.
|
||||
|
||||
### 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
|
||||
curl -OJ "http://crosspoint.local/download?path=/Books/MyBook.epub"
|
||||
```
|
||||
|
||||
# Upload to specific directory
|
||||
Query parameters:
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `path` | Yes | File path to download |
|
||||
|
||||
Protected dotfiles, `System Volume Information`, and `XTCache` cannot be
|
||||
downloaded. EPUB files are served as `application/epub+zip`; other files use
|
||||
`application/octet-stream`.
|
||||
|
||||
### `POST /upload`
|
||||
|
||||
Uploads a file with HTTP multipart form data.
|
||||
|
||||
```bash
|
||||
curl -X POST -F "file=@mybook.epub" "http://crosspoint.local/upload?path=/Books"
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
Query parameters:
|
||||
|
||||
| Parameter | Required | Default | Description |
|
||||
| --------- | -------- | ------- | ------------------------------- |
|
||||
| `path` | No | `/` | Target directory for the upload |
|
||||
|-----------|----------|---------|-------------|
|
||||
| `path` | No | `/` | Destination directory |
|
||||
|
||||
**Response (200 OK):**
|
||||
```
|
||||
Successful response:
|
||||
|
||||
```text
|
||||
File uploaded successfully: mybook.epub
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
Notes:
|
||||
|
||||
| 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 |
|
||||
- Existing files with the same name are overwritten.
|
||||
- EPUB cache data for the uploaded path is cleared after a successful upload.
|
||||
- HTTP upload uses a 4 KB write buffer before flushing to the SD card.
|
||||
|
||||
**Notes:**
|
||||
- Existing files with the same name will be overwritten
|
||||
- Uses a 4KB buffer for efficient SD card writes
|
||||
### `POST /mkdir`
|
||||
|
||||
---
|
||||
Creates a folder.
|
||||
|
||||
### 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:**
|
||||
Form parameters:
|
||||
|
||||
| Parameter | Required | Default | Description |
|
||||
| --------- | -------- | ------- | ---------------------------- |
|
||||
| `name` | Yes | - | Name of the folder to create |
|
||||
| `path` | No | `/` | Parent directory path |
|
||||
|-----------|----------|---------|-------------|
|
||||
| `name` | Yes | - | New folder name |
|
||||
| `path` | No | `/` | Parent folder |
|
||||
|
||||
**Response (200 OK):**
|
||||
```
|
||||
Folder created: NewFolder
|
||||
```
|
||||
### `POST /rename`
|
||||
|
||||
**Error Responses:**
|
||||
Renames a file.
|
||||
|
||||
```bash
|
||||
curl -X POST -d "path=/Books/old.epub&name=new.epub" http://crosspoint.local/rename
|
||||
```
|
||||
|
||||
Form parameters:
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `path` | Yes | Existing file path |
|
||||
| `name` | Yes | New file name, not a path |
|
||||
|
||||
Only files can be renamed through this endpoint. The old EPUB cache path is
|
||||
cleared before the rename.
|
||||
|
||||
### `POST /move`
|
||||
|
||||
Moves a file into an existing folder.
|
||||
|
||||
```bash
|
||||
curl -X POST -d "path=/Books/mybook.epub&dest=/Read" http://crosspoint.local/move
|
||||
```
|
||||
|
||||
Form parameters:
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `path` | Yes | Existing file path |
|
||||
| `dest` | Yes | Existing destination folder |
|
||||
|
||||
Only files can be moved through this endpoint. The old EPUB cache path is
|
||||
cleared before the move.
|
||||
|
||||
### `POST /delete`
|
||||
|
||||
Deletes one or more files or empty folders.
|
||||
|
||||
| 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 one or more files or empty folders from the SD card.
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
# Delete a file
|
||||
curl -X POST -d "path=/Books/mybook.epub" http://crosspoint.local/delete
|
||||
|
||||
# Delete an empty folder
|
||||
curl -X POST -d "path=/OldFolder" http://crosspoint.local/delete
|
||||
|
||||
# Delete multiple items
|
||||
curl -X POST -d 'paths=["/Books/old.epub","/OldFolder"]' http://crosspoint.local/delete
|
||||
```
|
||||
|
||||
**Form Parameters:**
|
||||
Form parameters:
|
||||
|
||||
| Parameter | Required | Default | Description |
|
||||
| --------- | -------- | ------- | ----------- |
|
||||
| `path` | Yes, unless `paths` is provided | - | Path to one item to delete |
|
||||
| `paths` | Yes, unless `path` is provided | - | JSON array of paths to delete |
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `path` | Yes, unless `paths` is provided | Single path to delete |
|
||||
| `paths` | Yes, unless `path` is provided | JSON array of paths to delete |
|
||||
|
||||
Protected items cannot be deleted. Non-empty folders are rejected. EPUB cache
|
||||
data for deleted files is cleared.
|
||||
|
||||
## Settings API
|
||||
|
||||
### `GET /api/settings`
|
||||
|
||||
Returns a streamed JSON array of editable settings. Each item contains common
|
||||
fields plus type-specific fields.
|
||||
|
||||
```bash
|
||||
curl http://crosspoint.local/api/settings
|
||||
```
|
||||
|
||||
Example item:
|
||||
|
||||
```json
|
||||
{
|
||||
"key": "fontSize",
|
||||
"name": "Font Size",
|
||||
"category": "Reader",
|
||||
"type": "enum",
|
||||
"value": 1,
|
||||
"options": ["Small", "Medium", "Large"]
|
||||
}
|
||||
```
|
||||
|
||||
Types:
|
||||
|
||||
| Type | Extra fields |
|
||||
|------|--------------|
|
||||
| `toggle` | `value` (`0` or `1`) |
|
||||
| `enum` | `value`, `options` |
|
||||
| `value` | `value`, `min`, `max`, `step` |
|
||||
| `string` | `value` |
|
||||
|
||||
The font-family setting includes SD-card font families when they are installed.
|
||||
|
||||
### `POST /api/settings`
|
||||
|
||||
Applies a partial settings update from a JSON object.
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"fontSize":2,"showHiddenFiles":1}' \
|
||||
http://crosspoint.local/api/settings
|
||||
```
|
||||
|
||||
Successful response:
|
||||
|
||||
**Response (200 OK):**
|
||||
```text
|
||||
All items deleted successfully
|
||||
Applied 2 setting(s)
|
||||
```
|
||||
|
||||
**Error Responses:**
|
||||
## Font Management API
|
||||
|
||||
| Status | Body | Cause |
|
||||
| ------ | ------------------------------------------- | ---------------------------------- |
|
||||
| 400 | `Missing "path" or "paths" argument` | Neither parameter was provided |
|
||||
| 400 | `Provide either 'path' or 'paths', not both` | Both delete parameters were sent |
|
||||
| 400 | `Invalid paths format` | `paths` was not valid JSON |
|
||||
| 400 | `No paths provided` | `paths` was an empty JSON array |
|
||||
| 500 | `Failed to delete some items: ...` | One or more paths could not be deleted |
|
||||
### `GET /api/fonts`
|
||||
|
||||
**Protected Items:**
|
||||
- Files/folders starting with `.`
|
||||
- `System Volume Information`
|
||||
- `XTCache`
|
||||
Lists installed SD-card font families.
|
||||
|
||||
---
|
||||
|
||||
## 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:**
|
||||
```bash
|
||||
curl http://crosspoint.local/api/fonts
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"maxFamilies": 128,
|
||||
"families": [
|
||||
{
|
||||
"name": "Literata",
|
||||
"sizes": [12, 14, 16, 18],
|
||||
"files": [
|
||||
{"name": "Literata_12.cpfont", "size": 123456}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/fonts/upload`
|
||||
|
||||
Uploads one `.cpfont` file into a family folder.
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-F "family=Literata" \
|
||||
-F "file=@Literata_12.cpfont" \
|
||||
http://crosspoint.local/api/fonts/upload
|
||||
```
|
||||
|
||||
The handler validates the family name, `.cpfont` filename, and `CPFONT` magic
|
||||
bytes before accepting the file.
|
||||
|
||||
Successful response:
|
||||
|
||||
```json
|
||||
{"ok":true}
|
||||
```
|
||||
|
||||
### `POST /api/fonts/delete`
|
||||
|
||||
Deletes an installed font family.
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"family":"Literata"}' \
|
||||
http://crosspoint.local/api/fonts/delete
|
||||
```
|
||||
|
||||
Successful response:
|
||||
|
||||
```json
|
||||
{"ok":true}
|
||||
```
|
||||
|
||||
## OPDS Server API
|
||||
|
||||
### `GET /api/opds`
|
||||
|
||||
Lists saved OPDS servers. Passwords are never returned.
|
||||
|
||||
```bash
|
||||
curl http://crosspoint.local/api/opds
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"index": 0,
|
||||
"name": "My Catalog",
|
||||
"url": "http://calibre.local:8080/opds",
|
||||
"username": "reader",
|
||||
"hasPassword": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### `POST /api/opds`
|
||||
|
||||
Adds or updates an OPDS server. Include `index` to update an existing entry.
|
||||
If `password` is omitted during an update, the existing password is preserved.
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"My Catalog","url":"http://calibre.local:8080/opds","username":"reader","password":"secret"}' \
|
||||
http://crosspoint.local/api/opds
|
||||
```
|
||||
|
||||
### `POST /api/opds/delete`
|
||||
|
||||
Deletes an OPDS server by index.
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"index":0}' \
|
||||
http://crosspoint.local/api/opds/delete
|
||||
```
|
||||
|
||||
## Wi-Fi Credential API
|
||||
|
||||
### `GET /api/wifi`
|
||||
|
||||
Lists saved Wi-Fi networks. Passwords are never returned.
|
||||
|
||||
```bash
|
||||
curl http://crosspoint.local/api/wifi
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"index": 0,
|
||||
"ssid": "HomeWiFi",
|
||||
"hasPassword": true,
|
||||
"isLastConnected": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### `POST /api/wifi`
|
||||
|
||||
Adds or updates a saved Wi-Fi network. Include `index` to update an existing
|
||||
entry. If `password` is omitted during an update, the existing password is
|
||||
preserved.
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"ssid":"HomeWiFi","password":"secret"}' \
|
||||
http://crosspoint.local/api/wifi
|
||||
```
|
||||
|
||||
### `POST /api/wifi/delete`
|
||||
|
||||
Deletes a saved Wi-Fi network by index.
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"index":0}' \
|
||||
http://crosspoint.local/api/wifi/delete
|
||||
```
|
||||
|
||||
## WebSocket Upload
|
||||
|
||||
### Port 81
|
||||
|
||||
The WebSocket path is used for fast binary uploads from the file manager and
|
||||
Calibre plugin workflows.
|
||||
|
||||
Connection:
|
||||
|
||||
```text
|
||||
ws://crosspoint.local:81/
|
||||
```
|
||||
|
||||
**Protocol:**
|
||||
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>`
|
||||
1. Client sends text: `START:<filename>:<size>:<path>`
|
||||
2. Server replies `READY`
|
||||
3. Client sends binary chunks
|
||||
4. Server sends `PROGRESS:<received>:<total>` every 64 KB or at completion
|
||||
5. Server sends `DONE` when complete or `ERROR:<message>` on failure
|
||||
|
||||
**Example Session:**
|
||||
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]
|
||||
```text
|
||||
Client -> START:mybook.epub:1234567:/Books
|
||||
Server -> READY
|
||||
Client -> [binary chunk]
|
||||
Server -> PROGRESS:65536:1234567
|
||||
...
|
||||
Server -> "PROGRESS:1234567:1234567"
|
||||
Server -> "DONE"
|
||||
Server -> DONE
|
||||
```
|
||||
|
||||
**Error Messages:**
|
||||
Error messages include:
|
||||
|
||||
| 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 |
|
||||
|---------|-------|
|
||||
| `ERROR:Upload already in progress` | A second upload was started before the first completed |
|
||||
| `ERROR:Invalid START format` | Malformed START message or invalid size token |
|
||||
| `ERROR:Failed to create file` | Destination file could not be opened |
|
||||
| `ERROR:No upload in progress` | Binary data arrived without a matching START |
|
||||
| `ERROR:Upload overflow` | Client sent more bytes than declared |
|
||||
| `ERROR:Write failed - disk full?` | SD write failed |
|
||||
|
||||
**Example with `websocat`:**
|
||||
```bash
|
||||
# Interactive session
|
||||
websocat ws://crosspoint.local:81
|
||||
Incomplete WebSocket uploads are deleted on disconnect or error.
|
||||
|
||||
# Then type:
|
||||
START:mybook.epub:1234567:/Books
|
||||
# Wait for READY, then send binary data
|
||||
## WebDAV
|
||||
|
||||
The same HTTP server registers a WebDAV-compatible handler for file manager clients.
|
||||
|
||||
Supported methods:
|
||||
|
||||
```text
|
||||
OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, MKCOL, MOVE, COPY, LOCK, UNLOCK
|
||||
```
|
||||
|
||||
**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
|
||||
Notes:
|
||||
|
||||
---
|
||||
- `PUT` writes to a temporary `.davtmp` file first, then renames it into place.
|
||||
- Protected paths are rejected.
|
||||
- `LOCK` and `UNLOCK` are accepted for client compatibility only. The server
|
||||
does not implement full WebDAV Class 2 locking semantics such as persistent
|
||||
locks or lock discovery.
|
||||
|
||||
## UDP Discovery
|
||||
|
||||
The server listens on UDP port `8134`. When it receives the text payload
|
||||
`hello`, it replies to the sender with:
|
||||
|
||||
```text
|
||||
crosspoint (on <hostname>);81
|
||||
```
|
||||
|
||||
The final field is the WebSocket upload port.
|
||||
|
||||
## 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
|
||||
|
||||
- Device joins an existing 2.4 GHz Wi-Fi network.
|
||||
- `crosspoint.local` is advertised with mDNS when available.
|
||||
- `/api/status` returns `"mode": "STA"` and RSSI in dBm.
|
||||
|
||||
### 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`
|
||||
|
||||
---
|
||||
- Device creates an open hotspot named `CrossPoint-Reader`.
|
||||
- The device shows a Wi-Fi QR code and URL QR code.
|
||||
- The fallback IP is typically `192.168.4.1`.
|
||||
- `/api/status` returns `"mode": "AP"` and `"rssi": 0`.
|
||||
|
||||
## Notes
|
||||
### Calibre Wireless
|
||||
|
||||
- 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
|
||||
Calibre Wireless starts the same web server in STA mode and displays setup
|
||||
instructions plus WebSocket upload progress on the device screen.
|
||||
|
||||
+98
-185
@@ -1,235 +1,148 @@
|
||||
# Web Server Guide
|
||||
|
||||
This guide explains how to connect your CrossPoint Reader to WiFi and use the built-in web server to upload files from your computer or phone.
|
||||
This guide explains how to use CrossPoint Reader's built-in web server for file
|
||||
transfer, device settings, Wi-Fi/OPDS management, and SD-card font management.
|
||||
|
||||
## Overview
|
||||
|
||||
CrossPoint Reader includes a built-in web server that allows you to:
|
||||
The web server is available while the device is in **File Transfer** or
|
||||
**Calibre Wireless** mode. It can:
|
||||
|
||||
- Upload files wirelessly from any device on the same WiFi network
|
||||
- Browse and manage files on your device's SD card
|
||||
- Create folders to organize your library
|
||||
- Delete files and folders
|
||||
- Upload, download, rename, move, and delete files on the SD card
|
||||
- Create folders
|
||||
- Edit many device settings from a browser
|
||||
- Manage saved Wi-Fi networks and OPDS servers
|
||||
- Upload and delete `.cpfont` SD-card font families
|
||||
- Accept WebDAV clients and Calibre wireless uploads
|
||||
|
||||
## Prerequisites
|
||||
The server does not require authentication. Use it only on trusted private
|
||||
networks or in hotspot mode when you control who is connected.
|
||||
|
||||
- Your CrossPoint Reader device
|
||||
- A WiFi network
|
||||
- A computer, phone, or tablet connected to the **same WiFi network**
|
||||
## Starting File Transfer
|
||||
|
||||
---
|
||||
1. From the Home screen, select **File Transfer**.
|
||||
2. Choose one of the available modes:
|
||||
|
||||
## Step 1: Accessing the WiFi Screen
|
||||
| Mode | Use when |
|
||||
|------|----------|
|
||||
| **Join Network** | You want the reader to join an existing Wi-Fi network. |
|
||||
| **Calibre Wireless** | You want to receive books from the CrossPoint Calibre plugin workflow. |
|
||||
| **Create Hotspot** | You want the reader to create its own open Wi-Fi network. |
|
||||
|
||||
1. From the main menu or file browser, navigate to the **Settings** screen
|
||||
2. Select the **WiFi** option
|
||||
3. The device will automatically start scanning for available networks
|
||||
## Join Network Mode
|
||||
|
||||
---
|
||||
1. Select **Join Network**.
|
||||
2. Pick a 2.4 GHz Wi-Fi network from the scan results.
|
||||
3. Enter the password if prompted.
|
||||
4. Save credentials if you want the reader to reconnect automatically next time.
|
||||
|
||||
## Step 2: Connecting to WiFi
|
||||
After connection, the reader shows:
|
||||
|
||||
### Viewing Available Networks
|
||||
- The connected SSID
|
||||
- A QR code for the web URL
|
||||
- The direct IP URL, for example `http://192.168.1.102/`
|
||||
- The mDNS fallback URL, usually `http://crosspoint.local/`
|
||||
|
||||
Once the scan completes, you'll see a list of available WiFi networks with the following indicators:
|
||||
Use either URL from a phone, tablet, or computer on the same network.
|
||||
|
||||
- **Signal strength bars** (`||||`, `|||`, `||`, `|`) - Shows connection quality
|
||||
- **`*` symbol** - Indicates the network is password-protected (encrypted)
|
||||
- **`+` symbol** - Indicates you have previously saved credentials for this network
|
||||
## Create Hotspot Mode
|
||||
|
||||
<img src="./images/wifi/wifi_networks.jpeg" height="500">
|
||||
1. Select **Create Hotspot**.
|
||||
2. Connect your phone or computer to the open Wi-Fi network:
|
||||
|
||||
### Selecting a Network
|
||||
```text
|
||||
CrossPoint-Reader
|
||||
```
|
||||
|
||||
1. Use the **Left/Right** (or **Volume Up/Down**) buttons to navigate through the network list
|
||||
2. Press **Confirm** to select the highlighted network
|
||||
3. Open the URL shown on the reader. `http://crosspoint.local/` is preferred
|
||||
when supported; the fallback IP is typically `http://192.168.4.1/`.
|
||||
|
||||
### Entering Password (for encrypted networks)
|
||||
The reader displays one QR code for joining the hotspot and another QR code for
|
||||
opening the web interface.
|
||||
|
||||
If the network requires a password:
|
||||
## Calibre Wireless Mode
|
||||
|
||||
1. An on-screen keyboard will appear
|
||||
2. Use the navigation buttons to select characters
|
||||
3. Press **Confirm** to enter each character
|
||||
4. When complete, select the **Done** option on the keyboard
|
||||
Calibre Wireless starts the same web server in station mode, then displays setup
|
||||
instructions and upload progress on the reader. Use this mode with the
|
||||
CrossPoint Calibre plugin or other clients that speak the documented WebSocket
|
||||
upload protocol.
|
||||
|
||||
<img src="./images/wifi/wifi_password.jpeg" height="500">
|
||||
For Calibre OPDS browsing, add `/opds` to the catalog URL when configuring an
|
||||
OPDS server.
|
||||
|
||||
**Note:** If you've previously connected to this network, the saved password will be used automatically.
|
||||
## Web Interface
|
||||
|
||||
### Connection Process
|
||||
The browser UI has four primary pages.
|
||||
|
||||
The device will display "Connecting..." while establishing the connection. This typically takes 5-10 seconds.
|
||||
### Home
|
||||
|
||||
### Saving Credentials
|
||||
|
||||
If this is a new network, you'll be prompted to save the password:
|
||||
|
||||
- Select **Yes** to save credentials for automatic connection next time (NOTE: These are stored in plaintext on the device's SD card. Do not use this for sensitive networks.)
|
||||
- Select **No** to connect without saving
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Connection Success
|
||||
|
||||
Once connected, the screen will display:
|
||||
|
||||
- **Network name** (SSID)
|
||||
- **IP Address** (e.g., `192.168.1.102`)
|
||||
- **Web server URL** (e.g., `http://192.168.1.102/`)
|
||||
|
||||
<img src="./images/wifi/wifi_connected.jpeg" height="500">
|
||||
|
||||
**Important:** Make note of the IP address - you'll need this to access the web interface from your computer or phone.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Accessing the Web Interface
|
||||
|
||||
### From a Computer
|
||||
|
||||
1. Ensure your computer is connected to the **same WiFi network** as your CrossPoint Reader
|
||||
2. Open any web browser (Chrome is recommended)
|
||||
3. Type the IP address shown on your device into the browser's address bar
|
||||
- Example: `http://192.168.1.102/`
|
||||
4. Press Enter
|
||||
|
||||
### From a Phone or Tablet
|
||||
|
||||
1. Ensure your phone/tablet is connected to the **same WiFi network** as your CrossPoint Reader
|
||||
2. Open your mobile browser (Safari, Chrome, etc.)
|
||||
3. Type the IP address into the address bar
|
||||
- Example: `http://192.168.1.102/`
|
||||
4. Tap Go
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Using the Web Interface
|
||||
|
||||
### Home Page
|
||||
|
||||
The home page displays:
|
||||
|
||||
- Device status and version information
|
||||
- WiFi connection status
|
||||
- Current IP address
|
||||
- Available memory
|
||||
|
||||
Navigation links:
|
||||
|
||||
- **Home** - Returns to the status page
|
||||
- **File Manager** - Access file management features
|
||||
|
||||
<img src="./images/wifi/webserver_homepage.png" width="600">
|
||||
The Home page shows firmware status, network mode, IP address, device type,
|
||||
uptime, and free heap.
|
||||
|
||||
### File Manager
|
||||
|
||||
Click **File Manager** to access file management features.
|
||||
The File Manager page can:
|
||||
|
||||
#### Browsing Files
|
||||
- Browse SD-card folders
|
||||
- Upload files, using WebSocket upload when available and HTTP upload as a fallback
|
||||
- Create folders
|
||||
- Download files
|
||||
- Rename files
|
||||
- Move files into existing folders
|
||||
- Delete one or more selected files or empty folders
|
||||
|
||||
- The file manager displays all files and folders on your SD card
|
||||
- **Folders** are highlighted in yellow and indicated with a 📁 icon
|
||||
- **EPUB Files** are highlighted in green and indicated with a 📗 icon
|
||||
- **All Other Files** are not highlighted and indicated with a 📄 icon
|
||||
- Click on a folder name to navigate into it
|
||||
- Use the breadcrumb navigation at the top to go back to parent folders
|
||||
Existing files with the same name are overwritten by uploads. When EPUB files
|
||||
are overwritten, moved, renamed, or deleted through the web server, the matching
|
||||
book cache is cleared so stale metadata is not reused.
|
||||
|
||||
<img src="./images/wifi/webserver_files.png" width="600">
|
||||
### Settings
|
||||
|
||||
#### Uploading Files
|
||||
The Settings page exposes many firmware settings in the browser. It also has
|
||||
cards for:
|
||||
|
||||
1. Click the **📤 Upload** button in the top-right corner
|
||||
2. Click **Choose File** and select a file from your device
|
||||
3. Click **Upload**
|
||||
4. A progress bar will show the upload status
|
||||
5. The page will automatically refresh when the upload is complete
|
||||
- Saved Wi-Fi networks
|
||||
- OPDS servers
|
||||
|
||||
<img src="./images/wifi/webserver_upload.png" width="600">
|
||||
Passwords are accepted when adding or editing entries, but saved passwords are
|
||||
not returned by the API.
|
||||
|
||||
#### Creating Folders
|
||||
### Fonts
|
||||
|
||||
1. Click the **📁 New Folder** button in the top-right corner
|
||||
2. Enter a folder name (must not contain characters \" * : < > ? / \\ | and must not be . or ..)
|
||||
3. Click **Create Folder**
|
||||
The Fonts page lists installed SD-card font families and lets you upload
|
||||
`.cpfont` files. Upload files from one font family at a time. The server validates
|
||||
the font family name, filename, and `.cpfont` magic bytes before accepting the
|
||||
upload.
|
||||
|
||||
This is useful for organizing your library by genre, author, series or file type.
|
||||
Installed fonts appear in **Settings > Reader > Font Family** after the font
|
||||
registry refreshes.
|
||||
|
||||
#### Deleting Files and Folders
|
||||
## Command Line Use
|
||||
|
||||
1. Click the **🗑️** (trash) icon next to any file or folder
|
||||
2. Confirm the deletion in the popup dialog
|
||||
3. Click **Delete** to permanently remove the item
|
||||
Power users can use `curl`, WebDAV clients, or WebSocket clients while the web
|
||||
server is running.
|
||||
|
||||
**Warning:** Deletion is permanent and cannot be undone!
|
||||
|
||||
**Note:** Folders must be empty before they can be deleted.
|
||||
|
||||
#### Moving Files
|
||||
|
||||
1. Click the **📂** (folder) icon next to any file
|
||||
2. Enter a folder name or select one from the dropdown
|
||||
3. Click **Move** to relocate the file
|
||||
|
||||
**Note:** Typing in a nonexistent folder name will result in the following error: "Failed to move: Destination not found"
|
||||
|
||||
#### Renaming Files
|
||||
|
||||
1. Click the **✏️** (pencil) icon next to any file
|
||||
2. Enter a file name (must not contain characters \" * : < > ? / \\ | and must not be . or ..)
|
||||
3. Click **Rename** to permanently rename the file
|
||||
|
||||
---
|
||||
|
||||
## 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. Detailed documentation can be found [here](./webserver-endpoints.md).
|
||||
Endpoint details are documented in [webserver-endpoints.md](./webserver-endpoints.md).
|
||||
|
||||
## Security Notes
|
||||
|
||||
- The web server runs on port 80 (standard HTTP)
|
||||
- **No authentication is required** - anyone on the same network can access the interface
|
||||
- The web server is only accessible while the WiFi screen shows "Connected"
|
||||
- The web server automatically stops when you exit the WiFi screen
|
||||
- For security, only use on trusted private networks
|
||||
- The HTTP server runs on port 80.
|
||||
- The WebSocket upload server runs on port 81.
|
||||
- There is no authentication.
|
||||
- Anyone on the same network can access the web interface while it is running.
|
||||
- The server stops when you exit File Transfer or Calibre Wireless mode.
|
||||
- Hotspot mode creates an open network for connectivity fallback; disconnect when done.
|
||||
|
||||
---
|
||||
## Tips
|
||||
|
||||
## Technical Details
|
||||
|
||||
- **Supported WiFi:** 2.4GHz networks (802.11 b/g/n)
|
||||
- **Web Server Port:** 80 (HTTP)
|
||||
- **Maximum Upload Size:** Limited by available SD card space
|
||||
- **Browser Compatibility:** All modern browsers (Chrome, Firefox, Safari, Edge)
|
||||
|
||||
---
|
||||
|
||||
## Tips and Best Practices
|
||||
|
||||
1. **Organize with folders** - Create folders before uploading to keep your library organized
|
||||
2. **Check signal strength** - Stronger signals (`|||` or `||||`) provide faster, more reliable uploads
|
||||
3. **Upload multiple files** - You can select and upload multiple files at once; the manager will queue them and refresh when the batch is finished
|
||||
4. **Use descriptive names** - Name your folders clearly (e.g., "SciFi", "Mystery", "Non-Fiction")
|
||||
5. **Keep credentials saved** - Save your WiFi password for quick reconnection in the future
|
||||
6. **Exit when done** - Press **Back** to exit the WiFi screen and save battery
|
||||
|
||||
---
|
||||
|
||||
## Exiting WiFi Mode
|
||||
|
||||
When you're finished uploading files:
|
||||
|
||||
1. Press the **Back** button on your CrossPoint Reader
|
||||
2. The web server will automatically stop
|
||||
3. WiFi will disconnect to conserve battery
|
||||
4. You'll return to the previous screen
|
||||
|
||||
Your uploaded files will be immediately available in the file browser!
|
||||
|
||||
---
|
||||
1. Use **Create Hotspot** when no trusted network is available.
|
||||
2. Prefer `crosspoint.local` when available, but keep the displayed IP address as a fallback.
|
||||
3. Move closer to the router if upload progress stalls in Join Network mode.
|
||||
4. Upload custom fonts through the Fonts page or copy them to `/.fonts/` or `/fonts/` on the SD card.
|
||||
5. Exit File Transfer mode when finished to conserve battery.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [User Guide](../USER_GUIDE.md) - General device operation
|
||||
- [Troubleshooting](./troubleshooting.md) - Troubleshooting
|
||||
- [README](../README.md) - Project overview and features
|
||||
- [User Guide](../USER_GUIDE.md)
|
||||
- [Webserver Endpoints](./webserver-endpoints.md)
|
||||
- [SD Card Fonts](./sd-card-fonts.md)
|
||||
- [Troubleshooting](./troubleshooting.md)
|
||||
|
||||
Reference in New Issue
Block a user