cottongin/crosspoint-reader-mod
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bd2cea8b8d7f8dea197bd5dfa8576f13f021d2fa
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

6.7 KiB
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