dreader-application/HARDWARE_PINOUT.md

# DReader Hardware Pinout Reference

Quick reference for the DReader e-ink device hardware configuration.

## Display Specifications

- **Resolution:** 1872 × 1404 pixels
- **Controller:** IT8951 (SPI)
- **Touch Panel:** FT5316 (I2C)

## GPIO Pin Assignments

### Buttons (BCM Numbering)

| GPIO | Function | Action | Notes |
|------|----------|--------|-------|
| 21 | Power Off | Long Press (500ms+) | Shutdown button |
| 22 | Previous Page | Swipe Right | Left button |
| 27 | Next Page | Swipe Left | Right button |

**Wiring:** All buttons connect between GPIO and GND (pull-up resistors enabled in software)

### SPI (IT8951 E-ink Display)

| GPIO | Function | Pin |
|------|----------|-----|
| 8 | SPI0 CE0 | 24 |
| 9 | SPI0 MISO | 21 |
| 10 | SPI0 MOSI | 19 |
| 11 | SPI0 SCLK | 23 |
| 17 | RST | 11 |
| 24 | HRDY | 18 |

### I2C (Touch, Sensors, RTC, Power Monitor)

| GPIO | Function | Pin | Devices |
|------|----------|-----|---------|
| 2 | I2C1 SDA | 3 | FT5316 (0x38), BMA400 (0x14), PCF8523 (0x68), INA219 (0x40) |
| 3 | I2C1 SCL | 5 | All I2C devices |

**Note:** I2C bus is shared by all I2C devices. Each device has a unique address.

## I2C Device Addresses

| Address | Device | Description |
|---------|--------|-------------|
| 0x38 | FT5316 | Capacitive touch panel |
| 0x14 | BMA400 | 3-axis accelerometer (optional) |
| 0x68 | PCF8523 | Real-time clock (optional) |
| 0x40 | INA219 | Power monitor (optional) |

## Physical Layout

```
Raspberry Pi GPIO Header (BCM Numbering)

     3V3  (1) (2)  5V
   GPIO2  (3) (4)  5V     ← I2C1 SDA (touch, sensors)
   GPIO3  (5) (6)  GND    ← I2C1 SCL
   GPIO4  (7) (8)  GPIO14
     GND  (9) (10) GPIO15
  GPIO17 (11) (12) GPIO18 ← Display RST
  GPIO27 (13) (14) GND
  GPIO22 (15) (16) GPIO23
     3V3 (17) (18) GPIO24 ← Display HRDY
  GPIO10 (19) (20) GND    ← SPI0 MOSI
   GPIO9 (21) (22) GPIO25
  GPIO11 (23) (24) GPIO8  ← SPI0 SCLK, CE0
     GND (25) (26) GPIO7
   GPIO0 (27) (28) GPIO1
   GPIO5 (29) (30) GND
   GPIO6 (31) (32) GPIO12
  GPIO13 (33) (34) GND
  GPIO19 (35) (36) GPIO16
  GPIO26 (37) (38) GPIO20
     GND (39) (40) GPIO21 ← Power off button


Button Connections:
  GPIO21 ──┤ ├── GND   (Power off)
  GPIO22 ──┤ ├── GND   (Previous page)
  GPIO27 ──┤ ├── GND   (Next page)
```

## Power Requirements

- **Input:** 5V via USB-C or GPIO header
- **Display:** ~3.3V, peak 500mA during refresh
- **Touch Panel:** 3.3V, ~20mA
- **Total (active):** ~1-2W
- **Total (sleep):** ~50-100mW

## Configuration Files

### hardware_config.json

```json
{
  "display": {
    "width": 1872,
    "height": 1404,
    "vcom": -2.0,
    "spi_hz": 24000000
  },
  "gpio_buttons": {
    "enabled": true,
    "buttons": [
      {"name": "prev_page", "gpio": 22, "gesture": "swipe_right"},
      {"name": "next_page", "gpio": 27, "gesture": "swipe_left"},
      {"name": "power_off", "gpio": 21, "gesture": "long_press"}
    ]
  }
}
```

## Testing Connections

### Check I2C Devices

```bash
# Scan I2C bus 1 (GPIO 2/3)
i2cdetect -y 1

# Expected output:
#      0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
# 00:          -- -- -- -- -- -- -- -- -- -- -- -- --
# 10: -- -- -- -- 14 -- -- -- -- -- -- -- -- -- -- --
# 20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# 30: -- -- -- -- -- -- -- -- 38 -- -- -- -- -- -- --
# 40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# 50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# 60: -- -- -- -- -- -- -- -- 68 -- -- -- -- -- -- --
# 70: -- -- -- -- -- -- -- --
```

### Check SPI

```bash
ls /dev/spi*
# Should show: /dev/spidev0.0  /dev/spidev0.1
```

### Test GPIO Buttons

```bash
# Install GPIO tools
sudo apt install gpiod

# Test previous page button (GPIO 22)
gpioget gpiochip0 22
# Press button: shows 0 (LOW)
# Release button: shows 1 (HIGH, pulled up)

# Test next page button (GPIO 27)
gpioget gpiochip0 27

# Test power button (GPIO 21)
gpioget gpiochip0 21
```

## Quick Start

```bash
# 1. Clone and install
git clone https://gitea.tourolle.paris/dtourolle/dreader-application.git
cd dreader-application
python3 -m venv venv
source venv/bin/activate
pip install -e .
./install_hardware_drivers.sh

# 2. Run interactive setup
sudo python3 setup_rpi.py

# 3. Run DReader
python examples/run_on_hardware_config.py
```

## Troubleshooting

### No I2C Devices Detected

```bash
# Enable I2C
sudo raspi-config
# Navigate to: Interface Options -> I2C -> Enable

# Check I2C is loaded
lsmod | grep i2c
# Should show: i2c_dev, i2c_bcm2835

# Add user to i2c group
sudo usermod -a -G i2c $USER
# Log out and back in
```

### SPI Not Working

```bash
# Enable SPI
sudo raspi-config
# Navigate to: Interface Options -> SPI -> Enable

# Check SPI devices
ls -l /dev/spi*

# Add user to spi group
sudo usermod -a -G spi $USER
```

### Buttons Not Responding

```bash
# Add user to gpio group
sudo usermod -a -G gpio $USER

# Test button with direct GPIO access
sudo gpioget gpiochip0 22  # Prev button
sudo gpioget gpiochip0 27  # Next button
sudo gpioget gpiochip0 21  # Power button

# Check for conflicts
# Make sure no other programs are using these GPIOs
```

## See Also

- [HARDWARE_SETUP.md](HARDWARE_SETUP.md) - Complete setup guide
- [GPIO_BUTTONS.md](GPIO_BUTTONS.md) - Button configuration reference
- [hardware_config.json](hardware_config.json) - Hardware configuration file