Documentation
This directory contains comprehensive documentation for the DRO (Digital Read Out) application.
Quick Start
-
INSTALLATION.md - Setup guide for Raspberry Pi
- System requirements
- Dependency installation
- Arduino firmware setup
- Auto-start configuration
- Troubleshooting
-
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
-
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:
- Keep technical accuracy
- Include code examples where relevant
- Update the table of contents
- Cross-reference related sections
- 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