Initial commit: merge nuescan, pymso, pybbd202, and pypewpewhops into scanengine-3

- Merged four separate hardware control projects into unified platform - Created unified requirements.txt with all dependencies - Added comprehensive .gitignore - Added project overview README Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-16 20:11:31 -06:00
commit fc43fbe4b0
65 changed files with 19127 additions and 0 deletions
@@ -0,0 +1,161 @@
+# nueScan Setup Guide
+
+## Installation
+
+### Prerequisites
+- Python 3.8 or higher
+- pip package manager
+
+### Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+## Running the Application
+
+### Method 1: Run as module
+```bash
+python -m nuescan
+```
+
+### Method 2: Run __main__.py directly
+```bash
+python __main__.py
+```
+
+## Project Structure
+
+```
+nuescan/
+├── __main__.py                    # Application entry point
+├── main_window.py                 # Main window controller
+├── requirements.txt               # Python dependencies
+├── SETUP.md                       # This file
+│
+├── dialogs/                       # Dialog controllers
+│   ├── __init__.py
+│   ├── genesis_dialog.py          # Genesis settings dialog
+│   ├── helios_dialog.py           # Helios settings dialog
+│   └── scan_active_dialog.py      # Scan progress dialog
+│
+├── hardware/                      # Hardware interface stubs
+│   ├── __init__.py
+│   ├── thorlabs_stage.py          # ThorLabs MLS stage controller
+│   ├── t3r_device.py              # T3R-SL device controller
+│   └── microscope.py              # Genesis/Helios controller
+│
+└── *.ui                           # Qt Designer UI files
+```
+
+## Hardware Interfaces
+
+### Current Implementation Status
+
+Hardware module implementation status:
+- **ThorLabs BBD203 Stage**: ✅ **FULLY IMPLEMENTED** - Production ready
+- **Helios Laser System**: ✅ **FULLY IMPLEMENTED** - Production ready
+- **Genesis Microscope**: Stub implementation for development
+- **T3R-SL Device**: Stub implementation for development
+
+#### ThorLabs MLS Stage (BBD203 Motor Controller)
+- **File**: `hardware/thorlabs_stage.py`
+- **Purpose**: 3-axis positioning control via BBD203 controller
+- **Connection**: USB with serial number auto-detection
+- **Status**: Full implementation - ready for real hardware
+- **Protocol**: APT binary protocol v42.1
+- **Usage**: Enter BBD203 serial number in UI, driver auto-finds USB port
+
+#### Helios Laser System
+- **Files**: `hardware/helios_driver.py`, `hardware/helios_protocol.py`
+- **Purpose**: Laser control with frequency, current, and pulse mode settings
+- **Connection**: RS-232 serial (9600 baud, 8N1)
+- **Status**: Full implementation - ready for real hardware
+- **Protocol**: ASCII-based RS-232 protocol
+- **Features**:
+  - Frequency control (16.7-125 kHz)
+  - Current control (0-7000 mA)
+  - Pulse mode control (single, gating, continuous)
+  - Temperature monitoring (4 sensors)
+  - Power monitoring
+  - Status register with error detection
+- **Usage**: Configure via Helios Settings dialog, COM port selected from dropdown
+
+#### Genesis Microscope
+- **File**: `hardware/microscope.py` (Genesis methods)
+- **Purpose**: Laser scanning microscope system
+- **Connection**: USB/Serial (not implemented)
+- **Status**: Stub - simulates microscope connection and status
+
+#### T3R-SL Device
+- **File**: `hardware/t3r_device.py`
+- **Purpose**: Timing and trigger control
+- **Connection**: USB/Serial (COM port)
+- **Status**: Stub - simulates device connection and status
+
+### Implementing Real Hardware Support
+
+To add actual hardware support, modify the stub methods in the respective hardware files:
+
+1. Add real serial communication using `pyserial`
+2. Implement manufacturer-specific protocols
+3. Add error handling and timeout logic
+4. Implement actual status polling from devices
+
+## UI Event Connections
+
+All UI elements are connected to handler methods:
+
+### Buttons
+- ThorLabs stage connect/disconnect
+- COM port refresh and connect
+- Genesis/Helios settings dialogs
+- Begin scanning
+- Advanced oscilloscope settings
+
+### ComboBoxes
+- COM port selection
+- Number of scans
+- Row spacing
+- Oscilloscope channel selections
+
+### Text Inputs
+- Stage serial number
+- Scan coordinates (X/Y start, delta)
+- Trigger voltage
+- VISA address
+
+## Development Notes
+
+### Adding New Hardware
+1. Create new controller class in `hardware/` directory
+2. Import and instantiate in `main_window.py`
+3. Add status update methods
+4. Connect to UI elements as needed
+
+### Modifying UI
+1. Edit `.ui` files with Qt Designer
+2. UI elements are accessed by their object names
+3. Connections are made in `_connect_signals()` method
+
+### Debug Output
+All stub methods print debug information to console. Look for:
+- `DEBUG:` - Function calls and state changes
+- `INFO:` - Successful operations
+- `WARNING:` - Potential issues
+- `ERROR:` - Operation failures
+
+## Testing
+
+The application can be run without any hardware connected. All hardware interfaces will simulate proper responses.
+
+### Test Progress Dialog
+To test the scan progress dialog with simulated progress:
+1. Configure scan parameters
+2. Click "Begin Scan"
+3. The dialog will show with demo progress animation
+
+## License
+
+Copyright (C) 2025 Thomas Ales
+Licensed under GNU General Public License v2.0