pi-dro/docs/README.md

Documentation

This directory contains comprehensive documentation for the DRO (Digital Read Out) application.

Quick Start

1. INSTALLATION.md - Setup guide for Raspberry Pi

   • System requirements
   • Dependency installation
   • Arduino firmware setup
   • Auto-start configuration
   • Troubleshooting

2. DRO.md - Application architecture and usage

   • Architecture overview (MVC pattern)
   • Class descriptions (Axis, Model, Controller, View)
   • Usage instructions and workflows
   • Configuration and calibration
   • GUI layout and keyboard shortcuts

3. ARDUINO_I2C_PROTOCOL.md - Hardware protocol details

   • I2C communication format
   • Data layout (4-byte packets)
   • Arduino firmware requirements
   • Encoder interface details
   • Debugging and troubleshooting

Documentation Structure

DRO.md
├── Overview - What is DRO?
├── Architecture - MVC pattern and data flow
├── Classes - Detailed class documentation
│   ├── Axis - Single axis representation
│   ├── Model - State management and observers
│   ├── Controller - User input and I2C
│   └── View - Tkinter GUI
├── Usage - How to run the application
├── Configuration - Scale factors and settings
├── Error Handling - Exception handling
├── Testing - Test mode documentation
└── Performance - Design considerations

INSTALLATION.md
├── Requirements - Hardware and software
├── Step 1-7 - Complete setup walkthrough
│   ├── Dependencies
│   ├── I2C configuration
│   ├── Arduino firmware
│   ├── I2C verification
│   ├── Auto-start
│   ├── Testing
│   └── Calibration
├── Troubleshooting - Common issues and fixes
└── Tips - Performance optimization

ARDUINO_I2C_PROTOCOL.md
├── Hardware Setup - Pinout and connections
├── Data Format - 4-byte packet structure
├── Communication Protocol - I2C timing diagrams
├── Arduino Requirements - Firmware template
├── Encoder Interface - Quadrature signals
├── Error Handling - Error cases
├── Debugging - Testing tools
└── Troubleshooting - Problem solving

Key Concepts

MVC Architecture

The application separates concerns:

• Model: Manages encoder positions, scale factors, and offsets
• View: Tkinter GUI displaying positions and buttons
• Controller: I2C communication, button handling, input processing

Position Calculation

Raw Position (steps from encoder)
    ↓ × scale factor
    ↓
Device Position (mm)
    ↓ + offset
    ↓
Displayed Position (mm, possibly × 2 for diameter)

I2C Communication

Arduino → 4 bytes (X lo, X hi, Z lo, Z hi) → DRO Application
                                      ↓
                            Convert to signed 16-bit integers
                                      ↓
                            Apply scale factors
                                      ↓
                            Update display (10 Hz)

Common Tasks

Change Scale Factors

File: dro.py → Search for model.set_scale()

model.set_scale('x', -2.5/200)  # X axis: mm per step
model.set_scale('z', 90/1000)   # Z axis: mm per step

Change GUI Update Rate

File: dro.py → Class View.__init__()

self._update_interval_ms = 100  # Change to 50 for 20 Hz

Enable Auto-Start

See: INSTALLATION.md → Step 5

Three options: Desktop file, Systemd service, or Cron job

Test Without Arduino

Command: python3 dro.py --test

Simulates encoders with keyboard (A/Z/S/X keys)

Debug I2C Issues

See: ARDUINO_I2C_PROTOCOL.md → Debugging section

Tools: i2cdetect, i2cget, Python test script

Troubleshooting Index

Issue	Documentation
Application won't start	INSTALLATION.md: Troubleshooting
I2C not detected	ARDUINO_I2C_PROTOCOL.md: Debugging
Positions are wrong	DRO.md: Configuration, INSTALLATION.md: Calibration
Arduino not communicating	ARDUINO_I2C_PROTOCOL.md: Troubleshooting
Missing dependencies	INSTALLATION.md: Step 1
Auto-start not working	INSTALLATION.md: Step 5

Contributing to Docs

When updating documentation:

1. Keep technical accuracy
2. Include code examples where relevant
3. Update the table of contents
4. Cross-reference related sections
5. Test all commands/instructions before documenting

See Also

• README.md - Project overview
• code-review-generic.instructions.md - Code review guidelines
• python.instructions.md - Python coding standards