adding files

2026-03-21 23:51:53 +01:00
commit 8cb0240ca2
19 changed files with 2162 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,158 @@
+# 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