scanengine-3/SETUP.md

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.

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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:

# 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:

{
  "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

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

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:

# 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:

designer nuescan_mainwindow.ui

2. UI files are loaded dynamically at runtime - no compilation needed

3. Access UI elements in code:

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
• Helios Communication Protocol
• ThorLabs MLS Protocol
• BBD202/203 Driver Documentation
• BBD202/203 Connection Guide
• Helios Driver Documentation
• Genesis Laser Documentation
• Laser Control Implementation Guide

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