# Coherent HOPS Laser I2C Protocol Documentation

This document describes the I2C communication protocol used to control Coherent HOPS laser systems, extracted from the CohrHopsDemo v2.0.7 codebase.

## Hardware Overview

### FTDI Interface
- **Chip**: FT2232C (dual-channel USB)
- **Protocol**: I2C via MPSSE (Multi-Protocol Synchronous Serial Engine)
- **Library**: CohrFTCI2C.dll (Windows), use libftdi/libmpsse on Linux

### I2C Configuration
| Parameter | Value/Range |
|-----------|-------------|
| Clock Divisor | 0 - 65535 |
| Modes | STANDARD, FAST |
| Control Bytes | 1 - 255 |
| Data Bytes | 1 - 65535 |

### I2C Slave
- **Device**: NXP microcontroller
- **Role**: Intermediary between FTDI and laser hardware

---

## I2C Library Functions

These are the low-level FTDI I2C functions (from CohrFTCI2C.dll):

| Function | Purpose |
|----------|---------|
| `I2C_GetNumDevices` | Enumerate connected I2C devices |
| `I2C_GetDeviceNameLocID` | Get device location identifier |
| `I2C_GetDeviceNameSerialNumber` | Get device serial number |
| `I2C_Open` | Open I2C device |
| `I2C_OpenEx` | Extended open with options |
| `I2C_OpenSerialNumber` | Open device by serial number |
| `I2C_InitDevice` | Initialize MPSSE interface |
| `I2C_SetMode` | Set STANDARD or FAST mode |
| `I2C_GetClock` | Get current clock divisor |
| `I2C_SetClock` | Set clock divisor |
| `I2C_SetLoopback` | Enable/disable loopback testing |
| `I2C_Write` | Write control + data bytes |
| `I2C_Read` | Read data bytes |
| `I2C_ReadAlt` | Alternative read function |
| `I2C_Close` | Close I2C device |
| `I2C_GetErrorCodeString` | Get error descriptions |

---

## NXP Slave Operations

The NXP microcontroller provides these I2C operations:

| Method | Purpose |
|--------|---------|
| `NXP::Write` | Write data to I2C slave |
| `NXP::Read` | Read data from I2C slave |
| `NXP::WriteRegister` | Write to internal registers |
| `NXP::ReadRegister` | Read from internal registers |
| `NXP::WriteGPIO` | Control GPIO outputs |
| `NXP::ReadGPIO` | Read GPIO inputs |

---

## I2C Transaction Format

### Write Operation
```
1. WriteControlBuffer: I2C slave address + W bit (0)
2. WriteDataBuffer: Register address + data
   - BYTE mode: Single byte writes
   - PAGE mode: Multi-byte writes
```

### Read Operation
```
1. WriteControlBuffer: I2C slave address + R bit (1)
2. ReadDataBuffer: Receive response
   - BYTE mode: Single byte reads
   - BLOCK mode: Multi-byte reads
```

---

## High-Level Command Interface

Commands are sent via `CohrHOPS_SendCommand()` using the format `?COMMAND` for queries.

### System Information Commands

| Command | Purpose | Example Response |
|---------|---------|------------------|
| `?HID` | Query Hardware ID | Device identifier |
| `?HTYPE` | Query Head Type | Head variant |
| `?HBDREV` | Query Head Board Revision | PCB revision |
| `?HEADDIO` | Query Head Digital I/O | DIO configuration |
| `?LASERMODEL` | Query Laser Model | G532, Tina, Mini00, MiniX |
| `?POWERUNITS` | Query Power Units | mW, W, etc. |
| `?WAVELENGTH` | Query Wavelength | 532nm, etc. |

### Temperature Monitoring

| Command | Purpose |
|---------|---------|
| `?TMAIN` | Main Heatsink Temperature |
| `?TBRF` | BRF (Birefringent Filter) Temperature |
| `?TSHG` | SHG (Second Harmonic Generator) Temperature |
| `?TTHG` | THG (Third Harmonic Generator) Temperature |
| `?TETA` | ETA Temperature |

### Temperature Control (Setpoints)

| Command | Purpose |
|---------|---------|
| `?TMAINCMD` | Get/Set Main Temperature Setpoint |
| `?TBRFCMD` | Get/Set BRF Temperature Setpoint |
| `?TSHGCMD` | Get/Set SHG Temperature Setpoint |
| `?TTHGCMD` | Get/Set THG Temperature Setpoint |
| `?TETACMD` | Get/Set ETA Temperature Setpoint |

### Temperature Data

| Command | Purpose |
|---------|---------|
| `?MAIND` | Main Temperature Data |
| `?BRFD` | BRF Temperature Data |
| `?SHGD` | SHG Temperature Data |
| `?THGD` | THG Temperature Data |
| `?ETAD` | ETA Temperature Data |

### Power Control

| Command | Purpose |
|---------|---------|
| `?PCMD` | Get/Set Power Command |
| `?PMEM` | Query Power Memory (stored settings) |
| `?PLIM` | Query Power Limits |

### Current Control

| Command | Purpose |
|---------|---------|
| `?CCMD` | Get/Set Current Command |
| `?CLIM` | Query Current Limits |
| `?CMODE` | Get/Set Control Mode |
| `?CMODECMD` | Get/Set Control Mode Command |

### Digital I/O

| Command | Purpose |
|---------|---------|
| `?PSDIO` | Power Supply Digital I/O |
| `?PSGLUEIN` | Power Supply Glue Logic Input |
| `?PSGLUEOUT` | Power Supply Glue Logic Output |

### Monitoring & Status

| Command | Purpose |
|---------|---------|
| `?ANA` | Query Analog Values |
| `?ANACMD` | Get/Set Analog Command |
| `?KSW` | Key Switch Status |
| `?KSWCMD` | Get/Set Key Switch Command |
| `?FAN` | Fan Status/Control |
| `?INT` | Interlock Status |
| `?REM` | Remote Control Status |
| `?EEH` | EEPROM Header |

### Configuration Registers

| Command | Purpose |
|---------|---------|
| `?CFG0` | Configuration Register 0 |
| `?CFG1` | Configuration Register 1 |
| `?CFG2` | Configuration Register 2 |
| `?CFG3` | Configuration Register 3 |

---

## Supported Laser Models

| Model | Description |
|-------|-------------|
| G532 | 532nm Green Laser |
| Tina | Proprietary Model |
| Mini00 | Compact Variant |
| MiniX | Extended Mini Variant |
| CommonLaser | Base Implementation |
| DummyLaser | Test/Simulation |

---

## Linux Implementation Guide

### Required Libraries

For Linux implementation, use one of:
- **libftdi** + **libmpsse** - Direct FTDI MPSSE control
- **pylibftdi** - Python bindings for libftdi
- Standard Linux I2C (`/dev/i2c-*`) if FTDI exposes as I2C adapter

### Installation (Debian/Ubuntu)

```bash
sudo apt install libftdi-dev libmpsse-dev
```

### Basic Implementation Steps

1. **Initialize FTDI Device**
   ```c
   // Find and open FT2232C device
   ftdi_init(&ftdi);
   ftdi_usb_open(&ftdi, 0x0403, 0x6010);  // FTDI VID/PID
   ```

2. **Configure MPSSE for I2C**
   ```c
   // Enable MPSSE mode
   ftdi_set_bitmode(&ftdi, 0, BITMODE_MPSSE);

   // Set I2C clock speed
   // Clock = 60MHz / ((1 + divisor) * 2)
   ```

3. **Send I2C Commands**
   ```c
   // Write command to laser
   i2c_write(slave_addr, "?HID", 4);

   // Read response
   i2c_read(slave_addr, buffer, sizeof(buffer));
   ```

### Example: Query Laser Model

```c
#include <ftdi.h>
#include <mpsse.h>

int main() {
    struct mpsse_context *i2c;
    char response[256];

    // Open I2C at 100kHz
    i2c = MPSSE(I2C, ONE_HUNDRED_KHZ, MSB);

    if (i2c && i2c->open) {
        // Send query command
        Start(i2c);
        Write(i2c, "?LASERMODEL", 11);
        Stop(i2c);

        // Read response
        Start(i2c);
        char *data = Read(i2c, 256);
        Stop(i2c);

        printf("Laser Model: %s\n", data);
        free(data);
    }

    Close(i2c);
    return 0;
}
```

---

## Error Handling

### Common Errors

| Error | Description |
|-------|-------------|
| Timeout after control byte | No ACK received after sending slave address |
| Timeout after data byte | No ACK received after sending data |
| MPSSE sync failure | Failed to synchronize FTDI MPSSE interface |

### Recovery

1. Reset MPSSE interface
2. Re-initialize I2C
3. Check physical connections
4. Verify I2C slave address

---

## Protocol Notes

- Commands use ASCII text format
- Query commands start with `?`
- Set commands likely use `=` followed by value
- Responses are ASCII strings
- Temperature values likely in degrees Celsius
- Power values use units from `?POWERUNITS` response

---

## Source Files Reference

| File | Purpose |
|------|---------|
| `CohrHOPS.dll` | Main laser control library |
| `CohrFTCI2C.dll` | FTDI I2C bridge library |
| `main.c` | Demo application |

---

## Additional Resources

- FTDI MPSSE Documentation: https://ftdichip.com/software-examples/mpsse-projects/
- libmpsse: https://github.com/devttys0/libmpsse
- Linux I2C: https://www.kernel.org/doc/html/latest/i2c/