# 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`