Add Coherent Verdi (V-series) and HOPS/Verdi-G (Genesis) laser drivers

Problem: The lab needed computer control of a Coherent green laser. Two distinct
devices turned out to be involved, neither previously supported: a classic Verdi
V-series (RS-232 ASCII) and, on the bench, a "Verdi-G" that is actually a Genesis
CX-Vis on a HOPS power supply whose USB is not a serial port at all.

Solution:
- VerdiDevice (+ VerdiV2/V5/V6Device, DebugVerdiDevice) in sources/verdi.py: the
  V-2/V-5/V-6 RS-232 ASCII driver (OnOff/Shutter/Power/Interlock). Built from the
  operator's manual; the PROMPT-polarity and CRLF-terminator details were
  corrected against two working third-party drivers. Verified against the mock
  only (no V-series hardware on hand).
- hops.py (HOPSInterface): a ctypes binding to Coherent's CohrHOPS.dll, the only
  supported way to talk to a HOPS supply (the FT2232 is driven as bit-banged I2C,
  not a UART, so no serial framing ever answers).
- VerdiGDevice (+ DebugVerdiGDevice) in sources/verdig.py: OnOff/Power/Shutter/
  Interlock plus a diagnostics() table, over hops.py. Hardware-confirmed on the
  lab Genesis CX-Vis (G532) for the read path and the REM/PCMD write path; the
  emission-enable and shutter writes are per the DLL spec, not yet exercised.
- manuals/: the V-series operator's manual (PDF) and serial-command reference;
  a HOPS USB-protocol reference; a reproducible runbook for the macOS-writes /
  Windows-runs / Parallels workflow used to reach the laser; and a decode of the
  HOPS I2C protocol sniffed via a logging CohrFTCI2C.dll proxy (identity/cal
  EEPROM 0x52, ADC 0x48, GPIO 0x25, power DAC 0x29, TMAIN calibration).

VerdiGDevice runs only where CohrHOPS.dll loads (Windows/Linux); on macOS it
raises UnableToInitialize and DebugVerdiGDevice is used. A native pyftdi path on
macOS is proven for reads (identity/power/temperature) in local prototypes kept
in the gitignored scratch-hops/ (with the vendor DLLs). Tests: 44 pass, 11 skip
(hardware absent) across testVerdi.py and testVerdiG.py.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01841beMNdCw3zYf6fdBUoy7

Author: dccote

.gitignore

@@ -141,3 +141,6 @@ cython_debug/
 .DS_Store
 stellarnet.py
 stellarnet.hex
+
+# Coherent HOPS vendor DLLs, capture logs, and local reversing prototypes (not for VCS)
+scratch-hops/

CHANGELOG.md

@@ -6,6 +6,45 @@ API changes can land even when the minor version is unchanged.
 
 ## [Unreleased]
 
+### Added
+- `VerdiGDevice` (and `DebugVerdiGDevice`), plus `hops.py` (`HOPSInterface`): a
+  driver for Coherent OPSL lasers on a "HOPS" power supply, controlled over USB
+  through Coherent's `CohrHOPS.dll` rather than a serial protocol. The supply
+  enumerates as an FTDI FT2232 (`0x0403:0x6010`) but is driven as bit-banged I2C
+  to an NXP micro-controller, so the DLL (ASCII command API over that binary
+  transport) is the only supported path; `hops.py` binds it with ctypes.
+  `VerdiGDevice` combines `OnOffControl` (software switch `KSWCMD`),
+  `PowerControl` (`PCMD`/`?P`), `ShutterControl` (`SHCMD`/`?SH`), and
+  `InterlockControl` (`?FF` fault bitmask). Verified on the lab unit (which
+  reports as a Genesis CX-Vis, head `G532`): the read path and the remote/power
+  setpoint write path (`REM=`, `PCMD=`) are hardware-confirmed; the emission
+  enable (`KSWCMD`) and shutter (`SHCMD`) are per the DLL spec but not yet
+  exercised on hardware. The DLL is Windows/Linux-only,
+  so on macOS `doInitializeDevice` raises `UnableToInitialize`; use
+  `DebugVerdiGDevice`. Protocol reference in
+  `manuals/Coherent-HOPS-USB-Protocol.md`.
+- `VerdiDevice` (and per-model `VerdiV2Device` / `VerdiV5Device` / `VerdiV6Device`,
+  plus `DebugVerdiDevice`): Coherent Verdi V-2/V-5/V-6 diode-pumped CW DPSS laser
+  (532 nm) over RS-232 (through a USB-serial adapter). Combines `OnOffControl`
+  (`L=1`/`L=0`/`?L`, gated by the front keyswitch), `ShutterControl`
+  (`S=1`/`S=0`/`?S`), `PowerControl` (`P=`/`?P` actual, `?SP` setpoint), and
+  `InterlockControl` (derived from the `?F` fault query, since the Verdi has no
+  dedicated interlock query). Instantiated by `portPath` like `CoboltDevice`
+  (the laser has no USB identity of its own); 19200 8-N-1 by default;
+  `doInitializeDevice` forces echo/prompt terminal modes to a known state and
+  reads the power-supply software version. Unlike the Millennia eV, the Verdi
+  answers every instruction, so each write consumes its reply and a `RANGE ERROR`
+  / `Command Error` / `Query Error` reply raises `VerdiDevice.CommandRejected`.
+  Serial-command reference in `manuals/Coherent-Verdi-Serial-Commands.md`.
+
+  **Scope and verification status:** this driver covers the **V-series only**. The
+  Verdi **G-series and C-series are not supported**: their "HOPS" power supply has
+  no DB-9 and exposes only USB via an FTDI FT2232 (`0x0403:0x6010`, manufacturer
+  `Coherent`) running a proprietary protocol -- a G-series unit ignored the entire
+  ASCII command set at every baud, framing, and terminator while lasing. The driver
+  is verified only against `DebugVerdiDevice`; **no command has been confirmed
+  against real V-series hardware.**
+
 ## [1.4.0] - 2026-07-08
 
 ### Added

hardwarelibrary/manuals/Coherent-HOPS-I2C-Decode.md

@@ -0,0 +1,139 @@
+# HOPS I2C protocol — decoded from a live capture
+
+Decoded from `ftci2c_capture_readonly.log` (captured 2026-07-09 via the logging
+`CohrFTCI2C.dll` proxy, read-only queries only) on the lab Genesis CX-Vis (G532).
+This is the wire protocol underneath `CohrHOPS.dll` — what a native `pyftdi`
+driver would replay. See `Coherent-HOPS-Verdi-G-Runbook.md` for how the capture
+was made.
+
+## Transport
+
+FTCI2C setup once at open: `I2C_InitDevice(divisor=599)`, `I2C_SetMode(mode=1)`
+(STANDARD_MODE). Every access is a standard I2C "write register pointer, then
+read N bytes" (`I2C_Read`, rType=2 = BLOCK_READ). In the FTCI2C control buffer,
+byte 0 is the device address with the write bit; the remaining control bytes are
+the register pointer written before the repeated-start read.
+
+The HOPS supply is **not one chip** — it's several I2C devices on one bus:
+
+| 7-bit addr | Ctrl byte 0 (W) | Role | Register addressing |
+|---|---|---|---|
+| 0x52 | 0xA4 | **Config/calibration + identity EEPROM** | 2-byte pointer `0x01 0xXX`, 1 byte per read |
+| 0x48 | 0x90 | **ADC** (power, temperatures — raw counts) | 1-byte register, reads 2 bytes |
+| 0x20 | 0x40 | status/GPIO port | 1-byte register (0x00/0x01), 1 byte |
+| 0x22 | 0x44 | status/GPIO port | 1-byte register (0x00/0x01), 1 byte |
+| 0x24 | 0x48 | status/GPIO port (keyswitch) | 1-byte register, 1 byte |
+| 0x25 | 0x4A | status/GPIO port (shutter) | 1-byte register, 1 byte |
+
+## EEPROM 0x52 (identity + calibration), page 0x01
+
+Strings are read byte-by-byte until a NUL:
+
+| Reg | Field | Bytes | Value |
+|---|---|---|---|
+| 0x0100.. | head type (`?HTYPE`) | `47 35 33 32 00` | "G532" |
+| 0x0110.. | head ID (`?HID`) | `56 48 35 33 35 39 00` | "VH5359" |
+| 0x0160.. | board rev (`?HBDREV`) | `44 45 00` | "DE" |
+
+Calibration constants are 4-byte **IEEE-754 big-endian** floats:
+
+| Reg | Bytes | Float |
+|---|---|---|
+| 0x0120 | `44 95 40 00` | 1194 |
+| 0x0124 | `45 CA D0 00` | 6490 |
+| 0x0128 | `43 73 00 00` | 243 |
+| 0x012C | `46 29 E8 00` | 10874 |
+| 0x0180 | `C0 8B 4F 35` | -4.35342 |
+| 0x0184 | `3F E7 EF A0` | 1.812 |
+| 0x0188 | `C2 30 C3 89` | -44.191 |
+
+(Blocks repeat at 0x0130/0x0140/0x0150 and 0x0184/0x0188/0x018C — per-channel
+gain/offset sets.) **These are the head calibration values.** A stray I2C write
+to 0x52 corrupts them — this is the concrete reason not to poke the bus blind.
+
+## Live signals — ADC 0x48 (raw counts, converted with the cal constants)
+
+| `?` command | I2C read | raw | note |
+|---|---|---|---|
+| `?P` (power) | dev 0x48, reg 0xE4, 2 bytes | `00 00` | 0 (laser off); scaled to W via cal |
+| `?TMAIN` | dev 0x48, reg 0x94, 2 bytes | `06 A0` | raw ADC; scaled to °C (see below) |
+
+**TMAIN calibration** (two DLL-correlated points, captured 2026-07-09):
+raw 1696 ↔ 32.222 °C and raw 1432 ↔ 39.773 °C — an **inverse** (NTC-like)
+relationship. Two-point linear fit: **`T(°C) = -0.028602 · raw + 80.7315`**,
+good over ~32–40 °C. (A one-point-through-origin guess is wrong — the slope is
+negative. Widen with more points, or use the EEPROM cal floats, for a larger
+range.) The **power** ADC read only has the (0 counts → 0 W) point so far; its
+non-zero scale needs actual emission to calibrate.
+
+So `CohrHOPS` reads all EEPROM cal floats at init, then converts ADC counts to
+watts/°C. A native driver must reproduce that scaling (or read the cal block and
+apply the same gain/offset).
+
+## Status / faults — GPIO ports 0x20/0x22/0x24/0x25
+
+Single-byte port reads whose bits the DLL combines:
+
+| `?` command | reads | raw |
+|---|---|---|
+| `?SH` (shutter) | dev 0x25 reg 0x00 | `EC` |
+| `?KSW` (keyswitch) | dev 0x24 reg 0x00 | `94` |
+| `?FF` (fault) | dev 0x20 reg 0x01/0x00, 0x24 reg 0x01/0x00, 0x22 reg 0x01/0x00 | `DC D5 FA 94 0F 15` |
+
+The DLL masks specific bits out of these port bytes (e.g. `?SH`->0, `?KSW`->1 on
+this run). The exact bit map needs a few more captures with the shutter/keyswitch
+toggled to pin down which bit is which.
+
+## Write protocol (captured 2026-07-09, beam blocked)
+
+Writes go to two devices that were not touched by reads:
+
+### Power setpoint — DAC at 0x29 (ctrl byte 0x52), register 0xA0
+
+`PCMD=<w>` writes a 16-bit big-endian code to device 0x29, register 0xA0
+(`I2C_Write` wType=2 / PAGE_WRITE, 2 data bytes):
+
+| `PCMD` | wdata |
+|---|---|
+| 0.5 W | `00 33` (=51) |
+| 0.0 W | `00 00` |
+
+~102 counts/W through the origin from these two points (single non-zero point,
+so the offset/exact scale should be confirmed with a couple more setpoints, or
+computed from the EEPROM cal floats). This is **not** the cal EEPROM (0x52) — so
+setting power never risks the calibration.
+
+### Discrete controls — GPIO expander at 0x25 (ctrl byte 0x4A)
+
+A PCA9555-style 16-bit I/O expander: register **0x02 = output port**, **0x06 =
+configuration/direction**. Each command writes 0x06 (make the pin an output) then
+0x02 (drive it). The DLL uses a read-modify-write shadow, so a native driver
+should read 0x02/0x06, flip only the target bit, and write back (never blast a
+whole byte).
+
+Output-port 0x02 bit map (derived from the deltas):
+
+| Bit | Mask | Control | Meaning |
+|---|---|---|---|
+| 0 | 0x01 | shutter (`SHCMD`) | 1 = open, 0 = closed (only `SHCMD=0` captured; `=1` inferred) |
+| 3 | 0x08 | remote (`REM`) | **active-low**: 0 = remote on, 1 = off |
+| 5 | 0x20 | software switch (`KSWCMD`, emission enable) | 1 = on, 0 = off |
+
+Captured output-port values: `REM=1`->E4, `KSWCMD=0`->C4, `KSWCMD=1`->E4,
+`SHCMD=0`->E4 (bit0 already 0), `REM=0`->EC.
+
+All writes returned status 0, and the run restored REM/PCMD/KSWCMD and left the
+shutter closed (verified in the final-state read).
+
+## Status of the reverse-engineering
+
+- **Reads: mapped.** Identity/EEPROM reads are trivially replayable; ADC and GPIO
+  reads are captured, pending the count->unit scaling and the status bit map.
+- **Writes: captured** (see "Write protocol" above). Power = DAC 0x29 reg 0xA0;
+  shutter/remote/enable = GPIO expander 0x25 bits 0/3/5. Remaining refinement:
+  a few more `PCMD` points to nail the DAC scale/offset, and confirming `SHCMD=1`
+  (shutter open) — deliberately not captured to keep the beam blocked.
+- A native `pyftdi` driver is therefore feasible: pyftdi's `I2cController` does
+  exactly "write pointer, read N bytes" on these addresses. The remaining work is
+  the ADC scaling, the status bit map, and a write capture — not more transport
+  reverse-engineering.

hardwarelibrary/manuals/Coherent-HOPS-USB-Protocol.md

@@ -0,0 +1,112 @@
+# Coherent HOPS USB Protocol (Genesis / Verdi G-C)
+
+How to talk to a Coherent "HOPS" power supply over USB. This is the transport
+used by the Genesis OPSL heads and the **Verdi G- and C-series** -- *not* the
+DB-9 ASCII RS-232 protocol of the classic Verdi V-series (that is
+`Coherent-Verdi-Serial-Commands.md`, and it does not apply here).
+
+## Why a HOPS supply looks dead over serial
+
+A HOPS supply enumerates as an **FTDI FT2232** (`0x0403:0x6010`, USB manufacturer
+`Coherent`, product `HOPS Power Supply`), so the OS attaches an FTDI VCP driver
+and creates two `/dev/cu.usbserial-*` (or `COMn`) ports. **They answer nothing.**
+The FT2232 is not run as a UART: Coherent drives it in **bit-banged / MPSSE I2C**
+mode. The supply's **NXP microcontroller** sits on that I2C bus, and the laser
+command set is exchanged as **binary frames** on the bus. So no baud rate, parity,
+or terminator will ever elicit a reply on the COM port -- verified on the bench: a
+powered, lasing Verdi G returned zero bytes across every baud 9600-921600, all
+databit/parity/stopbit combinations, and every terminator, with the FTDI never
+even flagging a framing error (the RX line never toggles).
+
+This was established from Coherent's own `CohrHOPS.dll` and its debug symbols
+(`.pdb`), which are public in Coherent's OPLS software package (the `CohrHopsDemo`
+folder) and mirrored in the AllenNeuralDynamics `coherent-lasers` GitHub release.
+
+## The stack
+
+```
+your code
+  -> CohrHOPS.dll         ASCII command API; parses ASCII, builds binary frames
+     -> CohrFTCI2C.dll    hardware-I2C path  --.
+     -> (NXP bit-bang)    software-I2C path  --+--> FTD2XX.dll -> FT2232 -> I2C bus -> NXP uC -> laser head
+```
+
+The DLL's `.pdb` reveals an `NXP` class implementing I2C by hand over FTDI GPIO
+(`SetClockLineHigh/Low`, `SetDataLineHigh/Low`, `GetDataLine`, `Start`, `Stop`,
+`SendByte`, `GetByte`, `MasterAck`, `GetSlaveAck`, `ReadRegister`,
+`WriteRegister`), and an `I2C` class for the hardware-assisted FTCI2C path. **Do
+not reimplement this blindly**: stray writes on that bus can land on the head's
+EEPROM/registers and damage the laser. Use the DLL.
+
+## The DLL API
+
+`extern "C"`, `__stdcall`, exported without name mangling -- ctypes-friendly. All
+functions return `0` (OK) or a negative status; string buffers are 100 bytes.
+
+| Function | Purpose |
+|---|---|
+| `CohrHOPS_GetDLLVersion(char* version)` | DLL version string |
+| `CohrHOPS_CheckForDevices(conn,&nConn, added,&nAdd, removed,&nRem)` | USB discovery; returns handle arrays |
+| `CohrHOPS_OpenSerialPort(const char* port, HANDLE* handle)` | for RS-232 HOPS supplies |
+| `CohrHOPS_InitializeHandle(HANDLE, char* headTypeOut)` | detect head; returns head-type string, or `INVALID_HEAD` |
+| `CohrHOPS_SendCommand(HANDLE, char* cmd, char* resp)` | one ASCII command/query -> ASCII response |
+| `CohrHOPS_Close(HANDLE)` | release the handle |
+
+Status codes: `0 OK`, `-1 INVALID_HANDLE`, `-2 INVALID_HEAD`, `-3 INVALID_COMMAND`,
+`-4 INVALID_DATA`, `-5 I2C_ERROR`, `-6 USB_ERROR`, `-100..-102 FTCI2C_DLL_*`,
+`-200 NXP_ERROR`, `-300 RS232_ERROR`, `-400 THREAD_ERROR`, `-999 OTHER_ERROR`.
+
+Call order (from Coherent's `CohrHopsDemo/main.c`):
+`CheckForDevices` -> `InitializeHandle` -> `SendCommand("?HID")` -> `Close`.
+
+## Command vocabulary (HOPS/Genesis)
+
+Queries: `?HTYPE`, `?LASERMODEL`, `?HID`, `?HBDREV`, `?P` (power), `?SH` (shutter),
+`?KSW` (keyswitch), `?CMODE`, `?PLIM`, `?CLIM`, `?POWERUNITS`, `?FAN`, `?INT`,
+`?ETAD`, `?MAIND`, `?TBRF`, ... Writable settings take a `CMD` suffix: `?PCMD`
+(set power), `?SHCMD` (shutter), `?KSWCMD`, `?CMODECMD`, `?TMAINCMD`, etc. This is
+distinct from the V-series `?P`/`?L`/`?S`/`P:`/`L:`/`S:` set.
+
+## Getting the DLLs
+
+Not committed here (vendor binaries, Windows-only, bitness-specific). Obtain from:
+
+- the **install media that shipped with the laser** (the Verdi-G-capable build), or
+- Coherent's public **OPLS software** package (`CohrHopsDemo` folder has
+  `CohrHOPS.dll`, `CohrFTCI2C.dll`, `main.c`, and `.pdb` symbols), or
+- the AllenNeuralDynamics **`coherent-lasers`** GitHub release assets.
+
+Place `CohrHOPS.dll` and `CohrFTCI2C.dll` next to
+`hardwarelibrary/sources/hops.py`, matching your Python's bitness (the OPLS
+`CohrHopsDemo/Release` DLL is 32-bit x86; the standalone release-asset build is
+x86-64).
+
+## Using it from this library
+
+`hardwarelibrary/sources/hops.py` binds the DLL with ctypes:
+
+```python
+from hardwarelibrary.sources.hops import HOPSInterface
+
+hops = HOPSInterface()                     # loads CohrHOPS.dll (Windows/Linux)
+print("DLL", hops.version())
+handles = hops.checkForDevices()           # USB discovery
+head = hops.initializeHandle(handles[0])   # -> head-type string, or HOPSError(INVALID_HEAD)
+print("head:", head)
+print(hops.sendCommand(handles[0], "?HTYPE"))
+print(hops.sendCommand(handles[0], "?LASERMODEL"))
+hops.close(handles[0])
+```
+
+On macOS this raises `HOPSUnavailable` (no DLL exists for the platform).
+
+## Open question for the Verdi G specifically
+
+The public `CohrHOPS.dll` builds inspected so far list only **Genesis** head types
+(`Genesis CX-UV/CX-Vis`, `Genesis MX-MTM/STM`, `Invalid head`) and contain **no
+"Verdi" strings**. So `InitializeHandle` may return `INVALID_HEAD` for a Verdi G,
+meaning the Verdi-capable CohrHOPS build is the one on the laser's own CD. One run
+of the snippet above on a Windows host with the laser attached settles it: if
+`initializeHandle` succeeds and `?LASERMODEL` names the Verdi, this DLL works; if
+it raises `INVALID_HEAD`, use the laser's shipped DLL instead. Either way the API
+and this wrapper are unchanged -- only the DLL file differs.