scanengine-3/docs/hardware/HELIOS_DRIVER_README.md

# Helios Laser System Driver

## Overview

This directory contains a complete implementation of the Helios laser system driver. The driver implements the full RS-232 ASCII communications protocol as specified in the helios_comms_protocol.pdf document.

The Helios laser system is a pulsed solid-state laser with:
- Diode-pumped Nd:YAG/Nd:YLF laser head
- Q-switched operation
- Frequency control (16.7 kHz - 125 kHz)
- Current control (0-7000 mA)
- Power monitoring
- Temperature monitoring (4 sensors)
- External trigger capability

## Architecture

The Helios driver is split into three layers:

### 1. Protocol Layer (`helios_protocol.py`)

Low-level protocol implementation that handles:
- ASCII command construction
- Response parsing and validation
- Unit conversions (Hz ↔ ns, °C ↔ m°C)
- Parameter range validation
- Status register decoding

**Key Classes:**
- `HeliosCommand`: Command constants and builders
- `HeliosProtocol`: High-level protocol interface with validation

### 2. Driver Layer (`helios_driver.py`)

Complete driver implementation providing:
- RS-232 serial communication (9600 baud, 8N1)
- Thread-safe command/query operations
- Comprehensive status monitoring
- Temperature monitoring (pump, resonator, q-switch, power stage)
- Power monitoring
- Laser enable/disable control
- Pulse mode control (single, gating, continuous)
- Frequency and current control

**Key Classes:**
- `PulseMode`: Enumeration of pulse modes
- `HeliosStatus`: Status data structure
- `HeliosDriver`: Main driver class for laser communication

### 3. Integration Layer (`hardware/microscope.py`)

Application-specific integration that:
- Combines Helios with Genesis microscope systems
- Provides unified status monitoring
- Integrates with nueScan application
- Implements safety interlocks
- Provides emergency stop functionality

## Features

### Communication
- ASCII-based RS-232 protocol
- Baud rate: 9600, 8 data bits, no parity, 1 stop bit
- Commands terminated with carriage return (CR)
- Thread-safe operation with mutex locking
- Configurable timeout (default: 1 second)

### Laser Control
- Laser enable/disable
- Three pulse modes:
  - Single pulse (one pulse per trigger)
  - Continuous gating (pulse train while triggered)
  - Continuous pulsing (free-running)
- Frequency control (16.7 kHz to 125 kHz)
- Diode current control (0-7000 mA)

### Monitoring
- Real-time power measurement (mW)
- Four temperature sensors:
  - Pump diode temperature
  - Resonator temperature
  - Q-switch temperature
  - Power stage temperature
- Operation hours counter
- Comprehensive status register
- Error detection

### Safety
- Temperature monitoring with warnings
- Error status detection
- Laser enable/disable control
- Emergency stop capability
- Integration with system interlocks

## Usage

### Connection Methods

The driver supports connection to a specific COM port:

```python
from hardware.helios_driver import HeliosDriver

# Create driver instance
driver = HeliosDriver(timeout=1.0)

# List available COM ports
ports = HeliosDriver.list_available_ports()
for port in ports:
    print(f"Available port: {port}")

# Connect to specific port
driver.connect('COM5')  # or '/dev/ttyUSB0' on Linux

# Get device information
print(f"Controller S/N: {driver.get_controller_serial()}")
print(f"Head S/N: {driver.get_head_serial()}")
```

### Basic Laser Control

```python
# Set frequency (in Hz)
driver.set_frequency_hz(10000)  # 10 kHz

# Set diode current (in mA)
driver.set_current_ma(500)  # 500 mA

# Set pulse mode
from hardware.helios_driver import PulseMode
driver.set_pulse_mode(PulseMode.CONTINUOUS_PULSING)

# Enable laser
driver.set_laser_enable(True)

# Check if laser is enabled
if driver.is_laser_enabled():
    print("Laser is ON")

# Disable laser
driver.set_laser_enable(False)

# Disconnect
driver.disconnect()
```

### Monitoring

```python
# Get current power
power_mw = driver.get_power_mw()
print(f"Output power: {power_mw} mW")

# Get temperatures (in Celsius)
temps = driver.get_all_temperatures()
print(f"Pump: {temps['pump_temp_c']:.1f}°C")
print(f"Resonator: {temps['resonator_temp_c']:.1f}°C")
print(f"Q-switch: {temps['qswitch_temp_c']:.1f}°C")
print(f"Power stage: {temps['power_stage_temp_c']:.1f}°C")

# Get operation hours
hours = driver.get_operation_hours()
print(f"Operation time: {hours} hours")

# Get comprehensive status
status = driver.get_status()
print(f"Connected: {status['connected']}")
print(f"Laser enabled: {status['laser_enabled']}")
print(f"Frequency: {status['frequency_hz']} Hz")
print(f"Current: {status['current_ma']} mA")
print(f"Power: {status['power_mw']} mW")
print(f"Has errors: {status['has_errors']}")
```

### Status Updates

```python
# Manually update status from hardware
driver.update_status()

# Status is automatically updated on each get_status() call
status = driver.get_status()

# Access cached values without querying hardware
freq = driver.get_frequency_hz()  # Returns last read value
current = driver.get_current_ma()  # Returns last read value
```

### Using Through Microscope Controller

The Helios driver is integrated into the application through the `MicroscopeController`:

```python
from hardware.microscope import MicroscopeController

# Create controller
microscope = MicroscopeController()

# Connect Helios
microscope.connect_helios('COM5')

# Apply settings from dialog
settings = {
    'com_port': 'COM5',
    'frequency_hz': 10000,
    'current_ma': 500
}
microscope.apply_helios_settings(settings)

# Enable laser
microscope.helios_enable_laser(True)

# Get status
status = microscope.get_helios_status()
print(f"Helios ready: {status['ready']}")
print(f"Power: {status['power_mw']} mW")

# Disable laser
microscope.helios_enable_laser(False)

# Disconnect
microscope.disconnect_helios()
```

## Configuration

### Frequency Control

The Helios laser operates by setting the pulse period in nanoseconds. The driver automatically converts between frequency (Hz) and period (ns):

```python
# Set frequency in Hz (driver converts to period in ns)
driver.set_frequency_hz(10000)  # 10 kHz → 100,000 ns period

# Valid frequency range: 16.7 kHz to 125 kHz
# Valid period range: 8000 ns to 60000 ns
```

Conversion formulas:
```
Period (ns) = 1,000,000,000 / Frequency (Hz)
Frequency (Hz) = 1,000,000,000 / Period (ns)
```

### Current Control

The diode current controls the laser output power:

```python
# Set current in milliamps
driver.set_current_ma(500)  # 500 mA

# Valid range: 0 to 7000 mA
```

**Important:** Higher currents produce more power but also more heat. Monitor temperatures when operating at high current.

### Pulse Modes

Three pulse modes are available:

```python
from hardware.helios_driver import PulseMode

# Single pulse mode (one pulse per trigger)
driver.set_pulse_mode(PulseMode.SINGLE_PULSE)

# Continuous gating mode (pulse train while triggered)
driver.set_pulse_mode(PulseMode.CONTINUOUS_GATING)

# Continuous pulsing mode (free-running)
driver.set_pulse_mode(PulseMode.CONTINUOUS_PULSING)
```

**Mode Descriptions:**
- **Single Pulse (LDG=0)**: One pulse generated per external trigger
- **Continuous Gating (LDG=1)**: Pulse train while external trigger is high
- **Continuous Pulsing (LDG=2)**: Free-running at set frequency (default)

### Temperature Monitoring

The driver monitors four temperature sensors:

```python
# Individual temperatures
pump_temp = driver.query_pump_temp_c()
resonator_temp = driver.query_resonator_temp_c()
qswitch_temp = driver.query_qswitch_temp_c()
power_stage_temp = driver.query_power_stage_temp_c()

# All temperatures at once
temps = driver.get_all_temperatures()
```

**Temperature Ranges:**
- Normal operation: < 50°C
- Warning threshold: > 60°C
- Critical threshold: > 70°C

## Integration with nueScan

The Helios driver is integrated into nueScan through the settings dialog and microscope controller.

### Configuration in UI

1. **Open Helios Settings**
   - Click "Helios Device Settings" button in main window

2. **Configure Parameters**
   - **COM Port**: Select from dropdown (automatically populated)
   - **Frequency**: Enter in Hz (16,666 - 125,000 Hz)
   - **Current**: Enter in mA (0 - 7000 mA)

3. **Apply Settings**
   - Click OK to apply and connect
   - Settings are validated before sending to hardware

### Settings Dialog Integration

The `HeliosDialog` class provides:
- Automatic COM port enumeration
- Input validation with range checking
- User-friendly error messages
- Settings persistence

```python
# Dialog usage (called from main window)
from dialogs.helios_dialog import HeliosDialog

dialog = HeliosDialog(parent=self)
if dialog.exec() == QDialog.DialogCode.Accepted:
    settings = dialog.get_settings()  # Returns None if validation fails
    if settings:
        self.microscope.apply_helios_settings(settings)
```

### Validation Rules

The dialog validates all inputs before accepting:

**Frequency Validation:**
- Range: 16,666 Hz to 125,000 Hz
- Reason: Hardware period limit of 8000-60000 ns
- Error message shows entered value and valid range

**Current Validation:**
- Range: 0 to 7000 mA
- Reason: Maximum diode current rating
- Error message shows entered value and valid range

**COM Port Validation:**
- Must select valid port from list
- Cannot accept "No ports found" placeholder
- Error message prompts to check connections

## Protocol Details

### Command Format

All commands follow the format:
```
COMMAND [value]<CR>
```

Where:
- `COMMAND` is a 3-letter mnemonic (e.g., LDO, LDF, LDS)
- `[value]` is optional numeric parameter
- `<CR>` is carriage return (0x0D)

### Command Set

| Command | Parameter | Description |
|---------|-----------|-------------|
| LDO | 0/1 | Laser enable (0=off, 1=on) |
| LDG | 0/1/2 | Pulse mode (0=single, 1=gating, 2=continuous) |
| LDF | 8000-60000 | Pulse period in nanoseconds |
| LDS | 0-7000 | Diode current in milliamps |
| LDP | - | Query output power (mW) |
| LDPT | - | Query pump temperature (m°C) |
| LDRT | - | Query resonator temperature (m°C) |
| LDQT | - | Query q-switch temperature (m°C) |
| LDPST | - | Query power stage temperature (m°C) |
| LDSR | - | Query status register |
| LDOH | - | Query operation hours |
| LDCSN | - | Query controller serial number |
| LDHSN | - | Query head serial number |

### Response Format

Responses are numeric values terminated with `<CR>`:
```
12345<CR>
```

**Exception:** Serial numbers are returned as strings:
```
SN12345678<CR>
```

### Status Register

The status register (LDSR) returns a 16-bit value with error flags:

| Bit | Mask | Meaning |
|-----|------|---------|
| 0 | 0x0001 | Pump temperature error |
| 1 | 0x0002 | Resonator temperature error |
| 2 | 0x0004 | Q-switch temperature error |
| 3 | 0x0008 | Power stage temperature error |
| 4 | 0x0010 | Diode current error |
| 5 | 0x0020 | Interlock open |
| 6 | 0x0040 | Over-power condition |
| 7 | 0x0080 | Under-voltage condition |

A status of 0 indicates no errors.

### Set and Verify Pattern

For critical parameters, the driver uses a set-and-verify pattern:

```python
def _set_and_verify(self, set_cmd: bytes, query_cmd: bytes, expected: str) -> bool:
    # Send set command
    self._serial.write(set_cmd)
    time.sleep(0.05)  # Allow hardware to process

    # Query back the value
    self._serial.write(query_cmd)
    response = self._read_response()

    # Verify it matches
    return response.strip() == expected.strip()
```

This ensures commands are executed correctly and hardware state matches software state.

## Troubleshooting

### Connection Issues

**Problem:** Cannot connect to laser

**Solutions:**
- Verify COM port name is correct (`HeliosDriver.list_available_ports()`)
- Check RS-232 cable connection
- Verify laser controller is powered on
- Try different COM port
- Check device permissions on Linux (`sudo usermod -a -G dialout $USER`)

### Communication Errors

**Problem:** Commands fail or no response

**Solutions:**
- Verify baud rate is 9600 (default)
- Check cable for proper null-modem configuration if needed
- Increase timeout: `driver = HeliosDriver(timeout=2.0)`
- Check for CR line termination (0x0D)
- Verify no other software has port open

### Frequency/Current Not Updating

**Problem:** Settings don't change on hardware

**Solutions:**
- Check return value of `set_frequency_hz()` and `set_current_ma()`
- Verify parameters are in valid range
- Check status register for errors: `driver.query_status_register()`
- Ensure laser is not in error state
- Try power cycling the controller

### Temperature Warnings

**Problem:** High temperature readings

**Solutions:**
- Check ventilation around laser head and controller
- Reduce diode current if at maximum
- Allow longer cool-down between operations
- Clean air filters if present
- Check for blocked cooling fans

### Laser Won't Enable

**Problem:** `set_laser_enable(True)` fails or laser stays off

**Solutions:**
- Check interlock connections (bit 5 of status register)
- Verify all interlocks are closed
- Check for error flags in status register
- Ensure parameters (frequency, current) are set
- Check external enable switch if present
- Review safety interlock documentation

### Status Register Errors

**Problem:** Status register shows error bits set

**Solutions:**
- Decode status register: `HeliosProtocol.decode_status_register(value)`
- Address specific error conditions:
  - Temperature errors: Improve cooling
  - Current error: Reduce current setting
  - Interlock open: Check safety connections
  - Over-power: Reduce current
  - Under-voltage: Check power supply

## Debug Output

The driver provides extensive debug output:

```
INFO: Informational messages about operations
DEBUG: Detailed command/response information
WARNING: Potential issues (high temp, errors)
ERROR: Operation failures
```

Enable Python logging to capture all output:

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

Example debug output:
```
INFO: Connecting to Helios laser on COM5
DEBUG: Sending command: b'LDCSN\r'
DEBUG: Received response: SN12345678
INFO: Successfully connected to Helios on COM5
DEBUG: Sending command: b'LDF 100000\r'
DEBUG: Verifying frequency setting...
INFO: Frequency set to 10000.0 Hz (period: 100000 ns)
```

## Performance Notes

- Command response time: 50-100ms typical
- Temperature queries: ~100ms per sensor
- Status register query: ~50ms
- All queries are synchronous (blocking)
- Thread-safe for concurrent access (mutex protected)
- Set-and-verify adds ~50ms overhead for reliability

## Safety Considerations

### Laser Safety
- **Class 4 Laser**: Hazardous to eyes and skin
- Always verify laser is disabled before opening beam paths
- Use appropriate laser safety eyewear
- Follow all facility laser safety procedures
- Ensure proper interlock connections

### Thermal Management
- Monitor temperatures during operation
- Allow adequate cool-down between high-power operations
- Ensure proper ventilation
- Do not block cooling vents

### Electrical Safety
- Verify proper grounding
- Use shielded cables for trigger/status connections
- Follow proper ESD procedures when servicing

## Hardware Connections

### Utility Connector (9-pin D-Sub)

The utility connector provides external control:

| Pin | Signal | Description |
|-----|--------|-------------|
| 1 | GND | Ground |
| 2 | Laser Disable | Input: Pull low to disable laser |
| 3 | External Trigger | Input: Rising edge triggers pulse |
| 4 | Status Out | Output: High when ready |
| 5 | GND | Ground |
| 6-9 | NC | Not connected |

Trigger specifications:
- Input: TTL/CMOS compatible
- Minimum pulse width: 100ns
- Maximum frequency: Limited by pulse mode setting

## References

- **Protocol Documentation**: `helios_comms_protocol.pdf`
- **RS-232 Standard**: EIA/TIA-232
- **Integration Guide**: `SETUP.md`
- **Connection Guide**: See main window Helios settings dialog

## License

Copyright (C) 2025 Thomas Ales
Licensed under GNU General Public License v2.0