ForeheadPPG

Academic research project to determine midline shift in acute intracranial events using analysis of bilateral supraorbital PPG waveforms.

Overview

The project is in the data collection phase only

This project investigates the utility of bilateral supraorbital photoplethysmography (PPG) as a non-invasive biomarker for detecting midline shift in patients with acute intracranial pathologies, utilizing the less affected side as an internal control for comparative waveform analysis.

🔬 Physiologic Basis

The supraorbital and supratrochlear arteries are terminal branches of the Ophthalmic Artery, which originates from the Internal Carotid Artery (ICA). Unlike external facial vasculature, these vessels share a direct hemodynamic link with the intracranial circulation. The core hypothesis is that intracranial mass effects (e.g., midline shift) induce downstream hemodynamic alterations in the ipsilateral ICA, which manifest as subtle morphological changes in the supraorbital PPG waveform.

🎯 Research Objective

To develop a non-invasive, portable diagnostic tool that utilizes bilateral supraorbital PPG signals to predict midline shift. The project focuses on curating a high-fidelity dataset to train a lightweight machine learning model optimized for near real-time inference on the Raspberry Pi Zero 2W or a similar low powered hardware.

Hardware Requirements

The system is designed to run on compact, embedded hardware:

• Target Device: Raspberry Pi Zero 2W
• Sensors: 2x MAX30101 (Pulse Oximeter & Heart-Rate Sensor)
• Display: Nokia 5110 LCD
• Power: LiPo Battery (2000mAh)
• Storage: MicroSD Card
• Buttons: 3x push buttons

Software Prerequisites

• OS: Raspberry Pi OS Lite (64-bit)
• Language: Python 3.12

Hardware Setup

1. Connect the MAX30101 Sensors

   Sensor	Signal	Raspberry Pi GPIO (BCM)	Raspberry Pi Pin (Physical)
   Left (Bus 3)	SDA	GPIO 17	Pin 11
   	SCL	GPIO 27	Pin 13
   	VCC	-	Pin 1/17 (3.3V)
   	GND	-	Pin 9
   Right (Bus 4)	SDA	GPIO 23	Pin 16
   	SCL	GPIO 24	Pin 18
   	VCC	-	Pin 1/17 (3.3V)
   	GND	-	Pin 14

2. Connect the Nokia 5110 LCD

   Nokia 5110 Pin	Function	Raspberry Pi GPIO (BCM)	Raspberry Pi Pin (Physical)
   1. RST	Reset	GPIO 25	Pin 22
   2. CE (CS)	Chip Select	GPIO 8 (SPI0 CE0)	Pin 24
   3. DC	Data/Command	GPIO 13	Pin 33
   4. DIN	Data In (MOSI)	GPIO 10 (SPI0 MOSI)	Pin 19
   5. CLK	Clock (SCLK)	GPIO 11 (SPI0 SCLK)	Pin 23
   6. VCC	Power (3.3V)	-	Pin 1/17 (3.3V)
   7. BL	Backlight	GPIO 18 (PWM)	Pin 12
   8. GND	Ground	-	Pin 6

3. Button Placement & Configuration

   The two buttons are placed on the bottom left and right of the LCD screen. When operational, the default functios are navigate left and navigate right. The screen will display the long press function of each of these buttons as press/hold(eg: Back and Enter, where holding the respective button for 1 second is for Back and Enter). The third button is the dedicated power button.

   Button	Function	Raspberry Pi GPIO (BCM)	Raspberry Pi Pin (Physical)
   Power	Hardware Wake / Shutdown	GPIO 3	Pin 5
   Left Soft Key	Context Action Left	GPIO 5	Pin 29
   Right Soft Key	Context Action Right	GPIO 6	Pin 31

4. Connect the LiPo Battery and charging module

Installation

Quick Setup (Recommended)

1. Connect to your Raspberry Pi

   ssh pi@<pi-ip-address>

2. Clone the repository

   cd /home/pi/
   git clone https://github.com/spacey-poem/ForeheadPPGtoPredictMLS.git ForeheadPPG
   cd ForeheadPPG

3. Run the installation script

   sudo bash setup/install.sh

   The script will automatically:

   • Update system packages
   • Install all dependencies (Python, I2C tools, Git)
   • Enable SPI and I2C interfaces
   • Configure I2C overlays for the sensors (buses 3 & 4)
   • Install Python dependencies from requirements.txt
   • Set up the power button listener
   • Configure autostart for the NeuroScan application
   • Prompt for reboot

4. Reboot when prompted

   After reboot, the NeuroScan application will start automatically!

Manual Installation (Advanced)

Click to expand manual installation steps

If you prefer to configure everything manually:

1. Update the system

   sudo apt update && sudo apt upgrade
   sudo apt install python3-pip python3-venv i2c-tools git -y

2. Enable SPI and I2C

   sudo raspi-config

   Navigate to: Interfacing Options → Enable SPI and I2C

3. Configure I2C overlays

   sudo nano /boot/config.txt

   Add these lines at the end:

   dtoverlay=i2c-gpio,bus=3,i2c_gpio_sda=17,i2c_gpio_scl=27,i2c_gpio_delay_us=2
   dtoverlay=i2c-gpio,bus=4,i2c_gpio_sda=23,i2c_gpio_scl=24,i2c_gpio_delay_us=2
   

4. Clone repository and install dependencies

   cd /home/pi/
   git clone https://github.com/spacey-poem/ForeheadPPGtoPredictMLS.git ForeheadPPG
   cd ForeheadPPG
   pip install -r requirements.txt

5. Set up power button listener

   crontab -e

   Add this line:

   @reboot python3 /home/pi/ForeheadPPG/src/utils/power_listener.py &
   

6. Install autostart service

   sudo bash setup/install-autostart.sh

7. Reboot

   sudo reboot

Managing the Application

Note

If you used the quick setup method, autostart is already configured and the application will start automatically on boot.

Service Management

Control the NeuroScan application service:

# Check service status
sudo systemctl status neuroscan.service

# Start the service manually
sudo systemctl start neuroscan.service

# Stop the service
sudo systemctl stop neuroscan.service

# Restart the service
sudo systemctl restart neuroscan.service

# Disable autostart (won't start on boot)
sudo systemctl disable neuroscan.service

# Re-enable autostart
sudo systemctl enable neuroscan.service

Viewing Logs

# View systemd journal logs (live)
journalctl -u neuroscan.service -f

# View recent logs
journalctl -u neuroscan.service -n 50

# View application log file
tail -f ~/neuroscan.log

Usage

The default and only function at present is to ustilize the device as a high fidility waveform recorder with a continuous serial numbering for the saved files for further processing.

Various scripts for testing the hardware are available in the examples directory. Run them from the PC terminal as follows:

cd /home/pi/ForeheadPPGtoPredictMLS
python examples/test_sensor.py

Note: Ensure your PYTHONPATH includes the project root if you encounter import errors, or run the script as a module which the method I used.

Using the device

Project Structure

ForeheadPPG/ ├── boot_config/ # Boot configuration files (overlays, config.yaml) ├── data/ # Data storage directory (not tracked by git) ├── examples/ # Hardware test scripts ├── setup/ # Installation scripts │ └── install-autostart.sh # Autostart service installer ├── src/ # Application Source Code │ ├── core/ # Core logic (e.g., recording.py) │ ├── drivers/ # Hardware drivers (MAX30101, Nokia5110, Inputs) │ ├── models/ # ML models for inference │ ├── utils/ # Utilities (power management, startup script) │ └── main.py # Main entry point specific for the Pi ├── systemd/ # Systemd service configuration │ └── neuroscan.service # Service unit file ├── training/ # Model training resources (PC/Cloud only) ├── requirements.txt # Python dependencies └── README.md # Project documentation

License

Feel free to use this project as a reference for any academic or research purposes. For now I am not cleared by the hospital ethics committee to share any of my patient data.