scanengine-3/pypewpewhops/LASER_I2C_PROTOCOL.md

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)

sudo apt install libftdi-dev libmpsse-dev

Basic Implementation Steps

1. Initialize FTDI Device

   // Find and open FT2232C device
   ftdi_init(&ftdi);
   ftdi_usb_open(&ftdi, 0x0403, 0x6010);  // FTDI VID/PID
   

2. Configure MPSSE for I2C

   // Enable MPSSE mode
   ftdi_set_bitmode(&ftdi, 0, BITMODE_MPSSE);
   
   // Set I2C clock speed
   // Clock = 60MHz / ((1 + divisor) * 2)
   

3. Send I2C Commands

   // Write command to laser
   i2c_write(slave_addr, "?HID", 4);
   
   // Read response
   i2c_read(slave_addr, buffer, sizeof(buffer));
   

Example: Query Laser Model

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