159 lines
4.6 KiB
Markdown
159 lines
4.6 KiB
Markdown
# 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
|