pi-dro/docs/INSTALLATION.md

DRO Installation & Setup Guide

This guide walks through setting up the Digital Read Out application on a Raspberry Pi.

System Requirements

• Hardware: Raspberry Pi 4 (or later)
• OS: Raspbian/Raspberry Pi OS (Bullseye or later)
• Python: 3.7+
• Arduino: Arduino Nano with I2C encoder firmware

Step 1: Install Dependencies

Enable I2C

sudo raspi-config
# Navigate to: Interfacing Options → I2C → Yes
# Reboot
sudo reboot

Install Python Libraries

# Update package manager
sudo apt-get update
sudo apt-get upgrade

# Install required packages
sudo apt-get install python3-tk python3-dev python3-pip

# Install Python dependencies
pip3 install smbus2
pip3 install adafruit-circuitpython-ads1x15  # Optional: for ADC

Optional: System Calculator

sudo apt-get install galculator

Step 2: Configure I2C for Shutdown

Allow the application to shutdown without a password:

sudo visudo

Add this line to the end of the file (replace pi with your username):

pi ALL=(ALL) NOPASSWD: /sbin/poweroff, /sbin/reboot, /sbin/shutdown

Save with Ctrl+X, then Y, then Enter.

Step 3: Upload Arduino Firmware

The Arduino must run firmware that:

1. Reads from two rotary encoders
2. Maintains position counters
3. Responds to I2C read requests at address 0x08

See ARDUINO_I2C_PROTOCOL.md for protocol details.

Example firmware structure:

#include <Wire.h>

volatile int16_t x_position = 0;
volatile int16_t z_position = 0;

void setup() {
  Wire.begin(0x08);
  Wire.onRequest(requestEvent);
  
  // Setup encoder interrupts
  pinMode(2, INPUT);
  pinMode(3, INPUT);
  attachInterrupt(0, x_encoder_isr, CHANGE);
  attachInterrupt(1, z_encoder_isr, CHANGE);
}

void requestEvent() {
  byte buffer[4];
  buffer[0] = (byte)x_position;
  buffer[1] = (byte)(x_position >> 8);
  buffer[2] = (byte)z_position;
  buffer[3] = (byte)(z_position >> 8);
  Wire.write(buffer, 4);
}

// Encoder ISR routines...
void loop() {}

Refer to the i2c_encoder/ directory for the complete Arduino sketch.

Step 4: Verify I2C Connection

Test I2C communication:

# Install I2C tools
sudo apt-get install i2c-tools

# Scan for I2C devices
i2cdetect -y 1

# Should show Arduino at address 0x08:
#      0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
# 00:          -- -- -- -- -- -- -- -- 08 -- -- -- --

Step 5: Auto-Start Configuration

Option A: Desktop File (GUI Autostart)

Create /home/pi/.config/autostart/dro.desktop:

[Desktop Entry]
Type=Application
Name=DRO
Exec=python3 /home/pi/dro/dro.py --zoomed
StartupNotify=false
X-GNOME-Autostart-always-run=true

Option B: Systemd Service

Create /etc/systemd/system/dro.service:

[Unit]
Description=Digital Read Out (DRO) Application
After=graphical.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/dro
ExecStart=/usr/bin/python3 /home/pi/dro/dro.py --zoomed
Restart=on-failure
RestartSec=5

[Install]
WantedBy=graphical.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable dro.service
sudo systemctl start dro.service

Option C: Shell Script Autostart

Create /home/pi/dro/autostart.sh:

#!/bin/bash
cd /home/pi/dro
python3 dro.py --zoomed

Make executable:

chmod +x /home/pi/dro/autostart.sh

Add to crontab (for user pi):

crontab -e
# Add line:
@reboot /home/pi/dro/autostart.sh

Step 6: Test the Installation

Test Mode (without Arduino)

cd ~/dro
python3 dro.py --test

# Use keyboard to test:
# A/Z = X encoder up/down
# S/X = Z encoder up/down

With Hardware

# Start the application
python3 dro.py --zoomed

# Check logs (if systemd service)
journalctl -u dro.service -f

Step 7: Calibration

Set Scale Factors

Edit dro.py and adjust these lines based on your encoder specifications:

# X axis: negative to flip direction
model.set_scale('x', -2.5/200)  # mm per step

# Z axis
model.set_scale('z', 90/1000)   # mm per step

How to determine:

1. Move the tool a known distance (e.g., 10 mm)
2. Record the encoder step count
3. Scale = Distance (mm) / Steps
4. Use negative for X if the direction is backwards

Set Zero Points

1. Position tool at starting location
2. Press X_0 button to zero X axis
3. Press Z_0 button to zero Z axis

Troubleshooting

No I2C Communication

# Check I2C is enabled
raspi-config

# Verify devices are connected
i2cdetect -y 1

# Check for USB connections (if Arduino is USB)
ls -la /dev/ttyUSB*

GUI Not Appearing

# Check display settings
export DISPLAY=:0
python3 dro.py

# Verify Tkinter is installed
python3 -c "import tkinter; print('Tkinter OK')"

I2C Errors

• Check pull-up resistors (4.7 kΩ is standard)
• Verify Arduino firmware is running
• Try slower I2C speed: edit smbus2 initialization

Position Drift

• Recalibrate scale factors
• Check encoder hardware connections
• Verify encoder isn't slipping

File Structure

/home/pi/dro/
├── dro.py                    # Main application
├── autostart.sh              # Auto-start script
├── power.png                 # Power button icon
├── test_model.py             # Unit tests
├── README.md                 # Project overview
├── docs/
│   ├── DRO.md               # Application documentation
│   └── ARDUINO_I2C_PROTOCOL.md  # I2C protocol
└── i2c_encoder/
    ├── i2c_encoder.ino      # Arduino firmware
    └── i2c_test.py          # Arduino test script

Performance Tips

1. Reduce Update Interval (for faster response):

   self._update_interval_ms = 50  # 20 Hz instead of 10 Hz
   

2. Increase I2C Speed:

   bus = smbus2.SMBus(1)
   bus.bus.set_clock(400000)  # 400 kHz fast mode
   

3. Use GPIO Directly (instead of I2C) for more performance:

   • Requires hardware changes
   • RPi.GPIO library for direct GPIO reading

Security Notes

• The DRO needs sudo access to shutdown (configured via sudoers)
• Store any sensitive config files outside the repo
• Use .env files for sensitive data (not committed to git)

Getting Help

• Check logs: journalctl -u dro.service -f
• Test I2C: i2cget -y 1 0x08 0 i 4
• Python console test:

  python3
  import smbus2
  bus = smbus2.SMBus(1)
  print(bus.read_i2c_block_data(0x08, 0, 4))