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.

```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 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:**
```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 the Genesis laser connection
python tools/genesis_laser_control.py
```

> Before changing any Genesis code, read
> [docs/genesis_verification.md](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:**
```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

See the tree in [README.md](README.md#project-structure). 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](KNOWN_ISSUES.md).

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