Initial commit: merge nuescan, pymso, pybbd202, and pypewpewhops into scanengine-3
- Merged four separate hardware control projects into unified platform - Created unified requirements.txt with all dependencies - Added comprehensive .gitignore - Added project overview README Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Thomas Ales [M S E]
@@ -0,0 +1,315 @@
|
||||
# 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/
|
||||
Reference in New Issue
Block a user