Raspberry Pi Setup Guide

Complete step-by-step guide to set up your Raspberry Pi-based Open Colorimeter with web interface.

Table of Contents

  1. Prerequisites
  2. Raspberry Pi OS Setup
  3. Ubuntu Server Setup
  4. Software Installation
  5. Hardware Connection
  6. First Run
  7. Configuration
  8. Auto-Start on Boot
  9. Troubleshooting

Prerequisites

Hardware Required

See Hardware Guide for complete parts list.

Skills Required

Choose Your Platform

This guide supports two operating systems:

Both work equally well. Choose based on your preference.

Raspberry Pi OS Setup

1. Prepare System

# Update system
sudo apt update
sudo apt upgrade -y

# Install required packages
sudo apt install -y python3-pip python3-dev i2c-tools git

2. Enable I2C

sudo raspi-config

Navigate to:

Reboot:

sudo reboot

3. Verify I2C

After reboot, check that I2C is working:

sudo i2cdetect -y 1

Expected output (with devices connected):

     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: 20 -- -- -- -- -- -- -- -- 29 -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: 60 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: 70 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

Addresses:

Ubuntu Server Setup

1. Prepare System

# Update system
sudo apt update
sudo apt upgrade -y

# Install required packages
sudo apt install -y python3 python3-pip python3-dev i2c-tools git build-essential

2. Enable I2C

# Load I2C kernel module
sudo modprobe i2c-dev

# Make I2C load on boot
echo "i2c-dev" | sudo tee -a /etc/modules

# Add user to i2c group
sudo usermod -aG i2c $USER

# Create i2c group if it doesn't exist
sudo groupadd -f i2c

# Set I2C device permissions
echo 'KERNEL=="i2c-[0-9]*", GROUP="i2c", MODE="0660"' | sudo tee /etc/udev/rules.d/99-i2c.rules

# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger

# Reboot
sudo reboot

3. Verify I2C

Check available I2C buses:

ls /dev/i2c-*

Scan for devices (usually bus 1):

sudo i2cdetect -y 1

If not on bus 1, try bus 0:

sudo i2cdetect -y 0

Software Installation

For Raspberry Pi OS:

# Install venv support
sudo apt install python3-venv

# Clone repository
cd ~
git clone https://github.com/thetemplateblog/openreef.git
cd openreef/firmware/open_colorimeter_pi

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

For Ubuntu Server (24.04+):

# Install venv support
sudo apt install python3-venv python3-full

# Clone repository
cd ~
git clone https://github.com/thetemplateblog/openreef.git
cd openreef/firmware/open_colorimeter_pi

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Upgrade pip and install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Option B: System-wide Installation

Raspberry Pi OS:

# Clone repository
cd ~
git clone https://github.com/thetemplateblog/openreef.git
cd openreef/firmware/open_colorimeter_pi

# Install dependencies
pip3 install -r requirements.txt

Ubuntu (may require –break-system-packages):

cd ~
git clone https://github.com/thetemplateblog/openreef.git
cd openreef/firmware/open_colorimeter_pi

pip3 install -r requirements.txt

Note: Ubuntu 24.04+ enforces PEP 668. Virtual environments are strongly recommended.

Hardware Connection

Before Powering On

  1. Power OFF Raspberry Pi
  2. Stack Motor HAT on GPIO pins
  3. Connect TSL2591 sensor:
    • VIN → Pi 3.3V or 5V
    • GND → Pi GND
    • SCL → GPIO 3
    • SDA → GPIO 2
  4. Connect Solenoid Driver:
    • VIN → Pi 3.3V or 5V
    • GND → Pi GND
    • SCL → GPIO 3
    • SDA → GPIO 2
  5. Connect Motors to M1, M2, M3, M4 terminals
  6. Connect 12V power to Motor HAT green terminal
  7. Power ON Raspberry Pi

Verify Connections

sudo i2cdetect -y 1

All devices should appear at their addresses.

First Run

Manual Test Run

If using virtual environment:

cd ~/openreef/firmware/open_colorimeter_pi
source venv/bin/activate
python app.py

If using system Python:

cd ~/openreef/firmware/open_colorimeter_pi
python3 app.py

Expected output:

Starting Open Colorimeter Web Interface
Access at: http://raspberrypi.local:5000
 * Running on http://0.0.0.0:5000

Access Web Interface

Open browser to:

Find IP address:

hostname -I

Test Hardware

  1. Sensor Tab:
    • Click “Measure” - should see raw values
    • Click “Blank Sensor” - should see blank value updated
  2. Motors Tab:
    • Move slider for Motor 1
    • Motor should spin (or pump should activate)
    • Test all motors
  3. Solenoids Tab:
    • Toggle solenoid switches
    • Should hear click (valves opening/closing)

If everything works, proceed to auto-start setup!

Configuration

Device Names

Edit device names in the web interface:

  1. Go to Config tab
  2. Edit mappings.json:
{
  "motors": {
    "1": {
      "name": "Sample",
      "description": "Sample pump"
    },
    "2": {
      "name": "Reagent",
      "description": "Reagent pump"
    }
  },
  "solenoids": {
    "1": {
      "name": "Inlet Valve",
      "description": "Sample inlet"
    }
  },
  "tests": {
    "Phosphate": {
      "sensor": 1,
      "calibration": "Phosphate"
    }
  }
}
  1. Click Save Mappings
  2. Reload page to see changes

Calibration Curves

Go to Calibrations tab:

  1. View existing calibrations
  2. Click Edit Calibrations section
  3. Modify calibrations.json:
{
  "Phosphate": {
    "units": "ppm",
    "led": "525",
    "fit_type": "polynomial",
    "fit_coef": [0.0, 2.709, 0.0],
    "range": {
      "min": 0.0,
      "max": 1.0
    }
  }
}
  1. Click Save Calibrations

Command Sequences

Go to Sequences tab:

  1. Create automated test protocols
  2. Example sequence:
Sample, 30
Solenoid 1, on
wait, 5
Solenoid 1, off
Reagent, -15
wait, 10
blank
wait, 2
measure Phosphate
  1. Click Save As… to save sequence
  2. Click Execute Sequence to run

Auto-Start on Boot

cd ~/openreef/firmware/open_colorimeter_pi
./install_service.sh

The script will:

That’s it! Service is now running.

Verify Service

# Check status
sudo systemctl status colorimeter

# View logs
sudo journalctl -u colorimeter -f

# Restart service
sudo systemctl restart colorimeter

# Stop service
sudo systemctl stop colorimeter

Uninstall Service

cd ~/openreef/firmware/open_colorimeter_pi
./uninstall_service.sh

Updating the Application

Automated Update

cd ~/openreef/firmware/open_colorimeter_pi
./update.sh

The update script:

Manual Update

cd ~/openreef/firmware/open_colorimeter_pi
git pull

# If using venv:
source venv/bin/activate
pip install -r requirements.txt

# If using system Python:
pip3 install -r requirements.txt

# Restart service
sudo systemctl restart colorimeter

Troubleshooting

Web Interface Not Accessible

Check Flask is running:

ps aux | grep python

Check port 5000:

sudo netstat -tulpn | grep 5000

Check firewall (Ubuntu):

sudo ufw status
sudo ufw allow 5000

Try IP address instead:

hostname -I
# Use: http://192.168.1.XXX:5000

Motor HAT Not Detected

Check physical connection:

Check I2C enabled:

# Raspberry Pi OS
sudo raspi-config
# Interface Options → I2C → Enable

# Ubuntu
lsmod | grep i2c

Scan I2C bus:

sudo i2cdetect -y 1

Should show 0x60 and 0x70.

Motors Not Running

Check power:

Check motor connections:

Test in web interface:

Sensor Not Found

Check wiring:

Check I2C scan:

sudo i2cdetect -y 1

Should show device at 0x29.

Try mock mode: If sensor not connected, app runs in mock mode with simulated values.

Python Package Errors

Ubuntu 24.04+ externally-managed-environment error:

# Use virtual environment
cd ~/openreef/firmware/open_colorimeter_pi
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Service Won’t Start

Check service status:

sudo systemctl status colorimeter

View error logs:

sudo journalctl -u colorimeter -n 50

Common issues:

Reinstall service:

./uninstall_service.sh
./install_service.sh

Next Steps

  1. Calibrate System:
  2. Create Sequences:
    • Design automated test protocols
    • Save frequently-used sequences
    • Share with team
  3. Run Tests:
    • Use web interface for measurements
    • Monitor from any device
    • Log data

Additional Resources

Quick Reference

Common Commands

# First-time setup
./install_service.sh

# Update application
./update.sh

# Service management
sudo systemctl status colorimeter
sudo systemctl restart colorimeter
sudo journalctl -u colorimeter -f

# Manual run (with venv)
source venv/bin/activate
python app.py

# Check I2C devices
sudo i2cdetect -y 1

# Find Pi IP address
hostname -I

Web Interface

Setup complete! Your Raspberry Pi colorimeter is ready to use. 🎉