scanengine-3/nuescan/SETUP.md

nueScan Setup Guide

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Install Dependencies

pip install -r requirements.txt

Running the Application

Method 1: Run as module

python -m nuescan

Method 2: Run __main__.py directly

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