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
This commit is contained in:
cottongin
174
mod/docs/hardware.md
Normal file
174
mod/docs/hardware.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# 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
Block a user