dreader-hal/INSTALL.md

Installation Guide

Prerequisites

System Dependencies

Raspberry Pi

# Enable I2C and SPI
sudo raspi-config
# Navigate to: Interface Options > I2C > Enable
# Navigate to: Interface Options > SPI > Enable
sudo reboot

# Install development tools
sudo apt-get update
sudo apt-get install -y \
    python3-dev \
    python3-pip \
    i2c-tools \
    libjpeg-dev \
    zlib1g-dev \
    libfreetype6-dev \
    liblcms2-dev \
    libopenjp2-7 \
    libtiff5

Installation Steps

1. Install External Drivers

The HAL depends on external driver libraries in the external/ directory. These need to be installed first.

IT8951 (E-ink Display)

cd external/IT8951
pip install ./[rpi]  # On Raspberry Pi
# OR
pip install ./        # On desktop (virtual display only)
cd ../..

Note: IT8951 has Cython extensions that need to be compiled. Make sure you have python3-dev installed.

PyFTtxx6 (Touch Controller)

cd external/PyFTtxx6/pyft5xx6
pip install -e .
cd ../../..

PyBMA400 (Accelerometer)

cd external/PyBMA400
pip install -e .
cd ../..

PyPCF8523 (RTC)

cd external/PyPCF8523
pip install -e .
cd ../..

pi_ina219 (Power Monitor)

cd external/pi_ina219
pip install .
cd ../..

2. Install DReader HAL

# Install in development mode
pip install -e .

# Or install for Raspberry Pi with GPIO support
pip install -e .[rpi]

3. Verify Installation

# Run tests
pytest tests/

# Try example (virtual display, no hardware)
python examples/simple_display.py

Troubleshooting

IT8951 Build Errors

If you get Cython build errors:

# Install build dependencies
sudo apt-get install python3-dev gcc

# Try installing with verbose output
pip install -v ./external/IT8951/[rpi]

I2C Device Not Found

# Check I2C devices
i2cdetect -y 1

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

Permission Denied

# Add user to necessary groups
sudo usermod -a -G spi,gpio,i2c $USER

# Reboot
sudo reboot

Import Errors

If you get import errors, make sure all external drivers are installed:

# Check installations
pip list | grep -E "(IT8951|pyft5xx6|pybma400|pypcf8523|ina219)"

Development Setup

For development with testing and linting tools:

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests with coverage
pytest --cov=dreader_hal tests/

# Format code
black src/ tests/ examples/

# Type checking
mypy src/

Testing Without Hardware

To test the HAL without actual hardware:

from dreader_hal import EReaderDisplayHAL

# Create HAL with virtual components
hal = EReaderDisplayHAL(
    virtual_display=True,          # Tkinter window
    enable_orientation=False,       # No accelerometer
    enable_rtc=False,              # No RTC
    enable_power_monitor=False,    # No INA219
)

This will use a Tkinter window for the display and won't try to access I2C devices.

Quick Install Script

For convenience, here's a script to install everything:

#!/bin/bash
# install_all.sh

set -e

echo "Installing external drivers..."

# IT8951
cd external/IT8951
pip install ./[rpi]
cd ../..

# PyFTtxx6
cd external/PyFTtxx6/pyft5xx6
pip install -e .
cd ../../..

# PyBMA400
cd external/PyBMA400
pip install -e .
cd ../..

# PyPCF8523
cd external/PyPCF8523
pip install -e .
cd ../..

# pi_ina219
cd external/pi_ina219
pip install .
cd ../..

echo "Installing dreader-hal..."
pip install -e .[rpi]

echo "Installation complete!"
echo "Run 'pytest tests/' to verify."

Save this as install_all.sh, make it executable (chmod +x install_all.sh), and run it.