# Documentation

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

## Quick Start

1. **[INSTALLATION.md](./INSTALLATION.md)** - Setup guide for Raspberry Pi
   - System requirements
   - Dependency installation
   - Arduino firmware setup
   - Auto-start configuration
   - Troubleshooting

2. **[DRO.md](./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](./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()`

```python
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__()`

```python
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