when'd i last commit this pos?

2026-02-09 14:40:34 -06:00
parent fc43fbe4b0
commit 23f6331ba2
94 changed files with 14427 additions and 12178 deletions
@@ -0,0 +1,428 @@
+# scanengine-3 Setup Guide
+
+Complete installation and configuration guide for the SRAS scanning platform.
+
+## System Requirements
+
+### Software Requirements
+- Python 3.8 or higher (3.10+ recommended)
+- pip package manager
+- Git (for version control)
+
+### Operating Systems
+- Linux (primary development platform)
+- Windows 10/11
+- macOS (limited testing)
+
+### Hardware Requirements
+Optional - application runs in simulation mode without hardware:
+- USB ports for ThorLabs BBD202/203 and FTDI devices
+- Serial (RS-232) port or USB-to-serial adapter for Helios laser
+- Network connection for Tektronix oscilloscope (Ethernet/LXI)
+
+## Installation
+
+### 1. Create Virtual Environment
+
+Using a virtual environment is strongly recommended to isolate dependencies.
+
+```bash
+# Navigate to project directory
+cd scanengine-3
+
+# Create virtual environment
+python -m venv venv
+
+# Activate virtual environment
+# On Linux/macOS:
+source venv/bin/activate
+
+# On Windows:
+venv\Scripts\activate
+```
+
+### 2. Install Python Dependencies
+
+```bash
+# Install all required packages
+pip install -r requirements.txt
+
+# Or install individually:
+pip install PyQt6>=6.4.0
+pip install pyserial>=3.5
+pip install pyvisa>=1.13.0
+pip install pyvisa-py>=0.7.0
+pip install pyftdi>=0.54.0
+```
+
+### 3. Verify Installation
+
+```bash
+# Test Python imports
+python -c "import PyQt6; import serial; import pyvisa; print('Dependencies OK')"
+
+# List connected serial devices (optional)
+python -c "import serial.tools.list_ports; print(list(serial.tools.list_ports.comports()))"
+```
+
+## Hardware Setup
+
+### ThorLabs BBD202/BBD203 Motor Controller
+
+**Connection:**
+1. Connect BBD202/203 controller to PC via USB
+2. Power on the controller
+3. Note the serial number printed on the device (8 digits)
+
+**Linux-specific:**
+```bash
+# Add user to dialout group for serial access
+sudo usermod -a -G dialout $USER
+# Log out and back in for changes to take effect
+
+# Verify USB connection
+lsusb | grep -i thorlabs
+```
+
+**Windows-specific:**
+- Install ThorLabs APT software to get USB drivers
+- Verify device appears in Device Manager under "Ports (COM & LPT)"
+
+**First-time setup:**
+```bash
+# Run the stage test application
+python stage_test_app.py
+
+# Enter your BBD203 serial number
+# Click "Connect" to test the connection
+# Use "Home All Axes" to verify operation
+```
+
+### Helios Laser System
+
+**Connection:**
+1. Connect Helios laser to RS-232 serial port
+2. Configure serial settings: 9600 baud, 8 data bits, no parity, 1 stop bit (8N1)
+3. Note the COM port name (e.g., COM3 on Windows, /dev/ttyUSB0 on Linux)
+
+**Linux-specific:**
+```bash
+# Identify serial port
+ls -l /dev/ttyUSB* /dev/ttyS*
+
+# Test connection (optional, if helios driver available)
+# python -c "from hardware.helios_driver import HeliosDriver; d = HeliosDriver('/dev/ttyUSB0'); print('Connected:', d.connect())"
+```
+
+### Coherent HOPS Laser
+
+**Connection:**
+1. Connect HOPS laser to PC via FTDI USB cable
+2. Laser communicates over I2C protocol through FTDI interface
+
+**Driver installation:**
+```bash
+# Linux: Install libftdi (if not already present)
+sudo apt install libftdi1-dev  # Debian/Ubuntu
+sudo dnf install libftdi-devel  # Fedora
+
+# Verify FTDI device
+python -c "from pyftdi.ftdi import Ftdi; Ftdi.show_devices()"
+```
+
+**First-time setup:**
+```bash
+# Test laser connection
+python -c "from hardware.coherent_hops_laser import CoherentHOPSLaser; laser = CoherentHOPSLaser(); print('Connected:', laser.connect())"
+```
+
+### Tektronix Oscilloscope
+
+**Connection:**
+1. Connect oscilloscope to network via Ethernet
+2. Configure oscilloscope IP address (static recommended)
+3. Enable LXI server on oscilloscope (Utility → I/O → Network → LXI)
+
+**Network configuration:**
+```bash
+# Verify connectivity
+ping <oscilloscope-ip>
+
+# Test connection
+python -c "from hardware.tektronix_base import TektronixOscilloscopeBase; scope = TektronixOscilloscopeBase(); scope.connect('<oscilloscope-ip>', 4000); print('Connected')"
+```
+
+## Running the Application
+
+### Main Application
+
+```bash
+# Run main application
+python -m scanengine.app
+```
+
+**On first launch:**
+1. Main window opens with scan launcher interface
+2. Configure system settings before starting scans
+3. Use "Options" to configure hardware connections
+
+### Genesis Laser Control Tools
+
+For standalone Genesis laser control:
+
+```bash
+# Full-featured Genesis laser control app
+python tools/genesis_laser_control.py
+
+# Alternative Genesis GUI
+python tools/genesis_laser_gui.py
+```
+
+Features:
+- Current and power control
+- Shutter and keyswitch control
+- Real-time monitoring
+- Interlock status
+- Temperature readings
+- Raw I2C packet interface
+
+## Configuration
+
+### Stage Settings
+
+Stage configuration is automatically saved to:
+```
+~/.nuescan/stage_settings.json  (Linux/macOS)
+%USERPROFILE%\.nuescan\stage_settings.json  (Windows)
+```
+
+Settings include:
+- Velocity profiles per axis
+- Acceleration profiles
+- Trigger output configuration
+- Last used serial number
+
+**Manual editing:**
+```json
+{
+  "x_axis": {
+    "velocity": 2.0,
+    "acceleration": 5.0,
+    "trigger": {
+      "mode": 1,
+      "polarity": 0,
+      "start_pos_fwd": 0.0,
+      "interval_fwd": 1.0
+    }
+  }
+}
+```
+
+### Application Settings
+
+Main window settings (geometry, last used values) are stored in Qt settings:
+```
+~/.config/SRAS/nueScan.conf  (Linux)
+%APPDATA%\SRAS\nueScan.ini  (Windows)
+```
+
+## Project Structure
+
+```
+scanengine-3/
+│
+├── scanengine/                    # Main application package
+│   ├── __init__.py
+│   ├── app.py                     # Main application entry point
+│   ├── main_launcher.ui           # Main launcher UI
+│   ├── new_scan_wizard.ui         # Scan wizard UI
+│   └── options.ui                 # Options dialog UI
+│
+├── hardware/                      # Hardware driver package
+│   ├── __init__.py
+│   ├── bbd202.py                  # ThorLabs stage controller
+│   ├── uc480_camera.py            # IDS/ThorLabs camera
+│   ├── tektronix_base.py          # Tektronix oscilloscope
+│   ├── coherent_hops_laser.py     # Coherent HOPS laser
+│   └── genesis_core.py            # Genesis laser core logic
+│
+├── scanning/                      # Scan planning package
+│   ├── __init__.py
+│   ├── sc3_scan_model.py          # Scan model
+│   └── stage_scan_plan_generator.py  # Scan path planning
+│
+├── tools/                         # Standalone executable tools
+│   ├── genesis_laser_control.py   # Standalone Genesis app
+│   └── genesis_laser_gui.py       # Alternative Genesis GUI
+│
+├── tests/                         # Test files
+│   ├── __init__.py
+│   ├── test_camera_integration.py
+│   ├── test_genesis_connection.py
+│   ├── test_genesis_protocol.py
+│   ├── test_rotated_aoi.py
+│   └── test_temperature_scaling.py
+│
+├── docs/                          # Documentation
+│   ├── hardware/                  # Hardware documentation
+│   │   ├── BBD203_CONNECTION_GUIDE.md
+│   │   ├── BBD203_Communications_Protocol.md
+│   │   ├── BBD203_DRIVER_README.md
+│   │   ├── HELIOS_DRIVER_README.md
+│   │   ├── GENESIS_LASER_README.md
+│   │   └── laser_control_implementation_guide.md
+│   └── protocols/                 # Protocol specifications
+│       ├── apt_communications_protocol.pdf
+│       ├── helios_comms_protocol.pdf
+│       └── thorlabs_mls_protocol.pdf
+│
+├── lib/                           # Binary libraries (not in git)
+│   ├── libueye_api64.so.3.82
+│   ├── ueye_loader.c
+│   └── ueye_loader.so
+│
+├── config.json                    # System configuration
+├── requirements.txt               # Python dependencies
+├── README.md                      # Project overview
+├── SETUP.md                       # This file
+└── LICENSE                        # License file
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Import Errors**
+```
+ModuleNotFoundError: No module named 'PyQt6'
+```
+**Solution:** Ensure virtual environment is activated and dependencies are installed
+```bash
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -r requirements.txt
+```
+
+**2. Serial Port Access Denied (Linux)**
+```
+PermissionError: [Errno 13] Permission denied: '/dev/ttyUSB0'
+```
+**Solution:** Add user to dialout group
+```bash
+sudo usermod -a -G dialout $USER
+# Log out and back in
+```
+
+**3. BBD202/203 Not Detected**
+- Verify USB cable is connected and device is powered on
+- Check serial number is correct (8 digits, case-sensitive)
+- On Windows, verify ThorLabs APT drivers are installed
+- Try different USB port
+
+**4. Oscilloscope Connection Failed**
+- Verify network connectivity with `ping`
+- Ensure oscilloscope LXI server is enabled
+- Check firewall settings (port 4000 must be open)
+- Verify IP address is correct
+
+**5. PyQt6 UI Loading Errors**
+```
+uic.loadUi() failed to load .ui file
+```
+**Solution:** Ensure .ui files are in same directory as main script, or check file paths
+
+### Debug Mode
+
+Enable verbose logging:
+
+```python
+# Add to __main__.py before creating QApplication
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+All hardware modules print status messages:
+- `DEBUG:` - Detailed operation information
+- `INFO:` - Normal operations
+- `WARNING:` - Potential issues
+- `ERROR:` - Operation failures
+
+## Development Workflow
+
+### UI Modifications
+
+1. Edit `.ui` files using Qt Designer:
+```bash
+designer nuescan_mainwindow.ui
+```
+
+2. UI files are loaded dynamically at runtime - no compilation needed
+
+3. Access UI elements in code:
+```python
+self.ui.buttonName.clicked.connect(self.handler_method)
+```
+
+### Adding New Hardware
+
+1. Create driver module in `hardware/` directory
+2. Implement required methods:
+   - `connect()` / `disconnect()`
+   - `is_connected()`
+   - `get_status()`
+3. Add to main window or create dedicated dialog
+4. Update UI to include new hardware section
+
+### Testing Without Hardware
+
+All hardware drivers support operation without physical devices:
+- Stage: Simulated position and status
+- Lasers: Accept commands without hardware validation
+- Oscilloscope: Can be tested with scope simulator
+
+Run application normally - missing hardware will log warnings but won't prevent startup.
+
+## Performance Optimization
+
+### Fast Data Acquisition
+
+For high-speed scanning with oscilloscope:
+1. Use wired Ethernet (not Wi-Fi)
+2. Set oscilloscope to 1 Gb Ethernet if available
+3. Enable binary data transfer format
+4. Use fast-frame mode for multi-point scans
+
+### Stage Movement Optimization
+
+For optimal scan performance:
+1. Home all axes before starting scan
+2. Set appropriate velocity limits (2-5 mm/s typical)
+3. Configure trigger output for synchronized acquisition
+4. Use continuous motion scans when possible
+
+## Additional Resources
+
+- [ThorLabs APT Protocol Manual](docs/protocols/apt_communications_protocol.pdf)
+- [Helios Communication Protocol](docs/protocols/helios_comms_protocol.pdf)
+- [ThorLabs MLS Protocol](docs/protocols/thorlabs_mls_protocol.pdf)
+- [BBD202/203 Driver Documentation](docs/hardware/BBD203_DRIVER_README.md)
+- [BBD202/203 Connection Guide](docs/hardware/BBD203_CONNECTION_GUIDE.md)
+- [Helios Driver Documentation](docs/hardware/HELIOS_DRIVER_README.md)
+- [Genesis Laser Documentation](docs/hardware/GENESIS_LASER_README.md)
+- [Laser Control Implementation Guide](docs/hardware/laser_control_implementation_guide.md)
+
+## License
+
+Copyright (C) 2025 Thomas Ales
+Licensed under GNU General Public License v2.0
+
+## Support
+
+For issues or questions:
+1. Check troubleshooting section above
+2. Review hardware-specific documentation
+3. Examine console output for error messages
+4. Contact development team
+
+---
+
+scanengine-3 v0.1.0