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 bbd202_test_app.py

# Set the serial port, click Connect (it now fails loudly if no bay
# responds), then Home 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 the Genesis laser connection
python tools/genesis_laser_control.py

Before changing any Genesis code, read docs/genesis_verification.md — the two implementations in the repo disagree on ADC scaling, LDD polarity, and shutter behaviour, and only the bench can settle it.

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

See the tree in README.md. In short: core/ is the headless scan engine and file format (no PyQt6, no vendor SDKs), hardware/ holds the Qt-free device drivers, gui/ the shared PyQt6 adapters and widgets, and the root *.py files are the runnable apps.

Vendored camera SDK (lib/)

lib/ is gitignored, so a fresh clone does not have it. The IDS uEye runtime (libueye_api64.so.3.82) must come from the IDS SDK installation matching the camera firmware on this rig.

lib/ueye_loader.{c,so} is an LD_PRELOAD shim that dlopens /usr/lib/libueye_api.so before Python starts. Nothing in the repo references it and no launcher sets LD_PRELOAD, so whether it is still needed is an open question — see KNOWN_ISSUES.md.

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