cottongin/crosspoint-reader-mod
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
66a754dabd20867578ad47a4e5d009adda4157eb
crosspoint-reader-mod/mod/docs/hardware.md
cottongin dfbc931c14 mod: Phase 1 - bring forward mod-exclusive files with ActivityManager migration 
Brings ~55 mod-exclusive files to the upstream-based mod/master-resync branch:

Activities (migrated to new ActivityManager pattern):
- Clock/Time: SetTimeActivity, SetTimezoneOffsetActivity, NtpSyncActivity
- Dictionary: DictionaryDefinitionActivity, DictionarySuggestionsActivity,
  DictionaryWordSelectActivity, LookedUpWordsActivity
- Bookmark: EpubReaderBookmarkSelectionActivity
- Book management: BookManageMenuActivity, EndOfBookMenuActivity
- OPDS: OpdsServerListActivity, OpdsSettingsActivity
- Utility: DirectoryPickerActivity, NumericStepperActivity

Utilities (unchanged):
- BookManager, BookSettings, BookmarkStore, BootNtpSync
- Dictionary, LookupHistory, TimeSync, OpdsServerStore

Libraries: PlaceholderCover, TableData, ChapterXPathIndexer
Scripts: inject_mod_version, generate_book_icon, preview_placeholder_cover
Docs: KOReader sync XPath mapping

Migration changes:
- ActivityWithSubactivity -> Activity base class
- Callback constructors -> finish()/setResult() pattern
- enterNewActivity() -> startActivityForResult()
- Activity::RenderLock&& -> RenderLock&&

These files won't compile yet - they reference mod settings and I18n
strings that will be added in subsequent phases.

Made-with: Cursor
2026-03-07 15:10:00 -05:00

175 lines
6.7 KiB
Markdown
Raw Blame History

# Xteink X4 Hardware Capabilities
This document describes the hardware present on the Xteink X4 e-ink device and what the CrossPoint Reader firmware can leverage.
## CPU / Microcontroller
- **MCU:** ESP32-C3 (RISC-V, single-core)
- **Usable RAM:** ~380 KB
- **Architecture:** Single-core -- background tasks (WiFi, etc.) compete with the main application loop for CPU time.
> Source: `platformio.ini` (`board = esp32-c3-devkitm-1`), `README.md`
## Flash Memory
| Region | Offset | Size | Purpose |
|---|---|---|---|
| NVS | `0x9000` | 20 KB | Non-volatile key/value storage (settings, credentials) |
| OTA Data | `0xE000` | 8 KB | OTA boot-selection metadata |
| App Partition 0 (ota_0) | `0x10000` | 6.25 MB | Primary firmware slot |
| App Partition 1 (ota_1) | `0x650000` | 6.25 MB | Secondary firmware slot (OTA target) |
| SPIFFS | `0xC90000` | 3.375 MB | On-flash file system |
| Core Dump | `0xFF0000` | 64 KB | Crash dump storage |
- **Total Flash:** 16 MB
- **Flash Mode:** DIO (Dual I/O)
- **Dual OTA partitions** enable over-the-air firmware updates: one slot runs the active firmware while the other receives the new image.
> Source: `partitions.csv`, `platformio.ini`
## Display
- **Type:** E-ink (E-paper)
- **Resolution:** 480 x 800 pixels (portrait orientation)
- **Color Depth:** 2-bit grayscale (4 levels: white, light gray, dark gray, black)
- **Frame Buffer Size:** 48,000 bytes (480/8 x 800), single-buffer mode
### Refresh Modes
| Mode | Description |
|---|---|
| `FULL_REFRESH` | Complete waveform -- best quality, slowest |
| `HALF_REFRESH` | Balanced quality/speed (~1720 ms) |
| `FAST_REFRESH` | Custom LUT -- fastest, used as the default |
### Grayscale Support
The display driver exposes separate LSB and MSB grayscale buffers (`copyGrayscaleBuffers`, `copyGrayscaleLsbBuffers`, `copyGrayscaleMsbBuffers`) for 2-bit (4-level) grayscale rendering.
### SPI Pin Mapping
| Signal | GPIO | Description |
|---|---|---|
| `EPD_SCLK` | 8 | SPI Clock |
| `EPD_MOSI` | 10 | SPI MOSI (Master Out Slave In) |
| `EPD_CS` | 21 | Chip Select |
| `EPD_DC` | 4 | Data/Command |
| `EPD_RST` | 5 | Reset |
| `EPD_BUSY` | 6 | Busy signal |
| `SPI_MISO` | 7 | SPI MISO (shared with SD card) |
> Source: `lib/hal/HalDisplay.h`, `lib/hal/HalGPIO.h`
## Buttons / Input
The device has **7 physical buttons**:
| Index | Constant | Location | Notes |
|---|---|---|---|
| 0 | `BTN_BACK` | Front | Remappable |
| 1 | `BTN_CONFIRM` | Front | Remappable |
| 2 | `BTN_LEFT` | Front | Page navigation, Remappable |
| 3 | `BTN_RIGHT` | Front | Page navigation, Remappable |
| 4 | `BTN_UP` | Side | Page navigation, Remappable |
| 5 | `BTN_DOWN` | Side | Page navigation, Remappable |
| 6 | `BTN_POWER` | Side | Wakes from deep sleep |
### Input Features
- Press, release, and hold-time detection via `InputManager` (SDK) and `HalGPIO`.
- The 4 front buttons and 2 side buttons are user-remappable through `MappedInputManager`.
- `MappedInputManager` adds logical button aliases (`PageBack`, `PageForward`) and a label-mapping system for UI hints.
- Side button layout can be swapped for left-handed use.
- Configurable power button hold duration for sleep/wake.
> Source: `lib/hal/HalGPIO.h`, `src/MappedInputManager.h`
## Storage (SD Card)
- **Interface:** SPI (shares the SPI bus with the display; `SPI_MISO` on GPIO 7 is common)
- **File System Library:** SdFat with UTF-8 long filename support (`USE_UTF8_LONG_NAMES=1`)
- **Driver:** `SDCardManager` from `open-x4-sdk`
- **Abstraction:** `HalStorage` provides a singleton (`Storage`) for all file operations -- listing, reading, writing, streaming, and directory management.
- **Usage:** EPUB storage, metadata caching to SD, settings persistence, book progress, and file transfer via web server.
> Source: `lib/hal/HalStorage.h`, `platformio.ini` build flags
## Battery
- **Monitoring Pin:** GPIO 0 (`BAT_GPIO0`)
- **Library:** `BatteryMonitor` from `open-x4-sdk`
- **Output:** Battery percentage (0-100%)
- **Access:** Via `HalGPIO::getBatteryPercentage()` or the global `battery` instance in `Battery.h`.
> Source: `src/Battery.h`, `lib/hal/HalGPIO.h`
## WiFi / Networking
- **Radio:** Built-in ESP32-C3 WiFi (802.11 b/g/n, 2.4 GHz)
- **Supported Modes:**
- **Station (STA):** Connect to an existing wireless network.
- **Access Point (AP):** Create a local hotspot for direct device connection.
### Network Features
| Feature | Description |
|---|---|
| Web Server | File management UI, book upload/download (`CrossPointWebServer`) |
| OTA Updates | HTTPS firmware download and flash (`OtaUpdater`) |
| WebSocket | Real-time communication with the web UI (`WebSockets @ 2.7.3`) |
| Calibre Connect | Direct wireless connection to Calibre library software |
| KOReader Sync | Reading progress sync with KOReader-compatible servers |
| OPDS Browser | Browse and download books from OPDS catalog feeds |
### Power Considerations
WiFi is power-hungry on the single-core ESP32-C3. The firmware disables WiFi sleep during active transfers and yields CPU time to the network stack when a web server activity is running (`skipLoopDelay()`).
> Source: `src/network/`, `src/activities/network/`, `platformio.ini` lib_deps
## USB
- **Connector:** USB-C
- **Connection Detection:** `UART0_RXD` (GPIO 20) reads HIGH when USB is connected.
- **Firmware Upload Speed:** 921,600 baud
- **Serial Monitor:** 115,200 baud (only initialized when USB is detected)
- **CDC on Boot:** Enabled (`ARDUINO_USB_CDC_ON_BOOT=1`)
> Source: `lib/hal/HalGPIO.h`, `platformio.ini`
## Power Management
### Deep Sleep
- Entered via `HalGPIO::startDeepSleep()` after a configurable inactivity timeout or power button hold.
- Wakeup is triggered by the power button GPIO.
- Before sleeping, application state (open book, reader position) is persisted to SD card.
### Wakeup Reasons
The firmware distinguishes between wakeup causes to decide boot behavior:
| Reason | Behavior |
|---|---|
| `PowerButton` | Normal boot -- verifies hold duration before proceeding |
| `AfterFlash` | Post-flash boot -- proceeds directly |
| `AfterUSBPower` | USB plug caused cold boot -- returns to sleep immediately |
| `Other` | Fallback -- proceeds to boot |
> Source: `lib/hal/HalGPIO.h`, `src/main.cpp`
## SDK Hardware Libraries
The `open-x4-sdk` git submodule (community SDK) provides the low-level drivers that the HAL wraps:
| Library | Path in SDK | Purpose |
|---|---|---|
| `BatteryMonitor` | `libs/hardware/BatteryMonitor` | Battery voltage reading |
| `InputManager` | `libs/hardware/InputManager` | Physical button input |
| `EInkDisplay` | `libs/display/EInkDisplay` | E-ink display driver |
| `SDCardManager` | `libs/hardware/SDCardManager` | SD card SPI management |
These are linked into the build as symlinks via `platformio.ini` `lib_deps`.
> Source: `.gitmodules`, `platformio.ini`
Reference in New Issue View Git Blame Copy Permalink