Unify HOPS driver: HOPSDevice with pluggable HOPS interfaces

Problem: The two device classes (VerdiGDevice over CohrHOPS.dll, and
NativeVerdiGDevice over pyftdi I2C) were the same laser split only by transport,
with duplicated capability logic.

Solution: a single HOPSDevice that delegates every capability hook to an
interchangeable HOPSInterface:
- HOPSInterface (hops.py): abstract transport contract; interlock/faults default
  to raising HOPSInterface.NotSupported.
- HOPSNativeInterface (hopsnative.py): pure-Python pyftdi I2C (no DLL). Native
  interlock/faults raise NotSupported until the ?FF decode is reverse-engineered.
- HOPSDLLInterface (hopsdll.py): Coherent's CohrHOPS.dll (ASCII), with the ctypes
  binding CohrHOPS.
HOPSDevice(interface="auto") tries native first, then the DLL; "native"/"dll"/an
instance force one. HOPSDevice keeps InterlockControl in its capability set;
interlock() simply raises NotSupported on the native transport (to be fixed).

Removes VerdiGDevice / NativeVerdiGDevice and their tests; adds testHOPSDevice.py
(debug + native-on-mock + read-modify-write always run; a hardware class skips
when no laser is present). Hardware-confirmed end to end on the lab Genesis
CX-Vis with interface="auto" (picks native): identity, on/off, shutter, remote,
power, temperature; interlock() raises NotSupported as designed. Docs/CHANGELOG
updated to HOPSDevice. 44 pass, 7 skip.

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

Author: dccote

CHANGELOG.md

@@ -7,34 +7,26 @@ 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`.
-- `NativeVerdiGDevice` (+ `DebugNativeVerdiGDevice`, `HOPSNativeI2C`, `MockHOPSBus`)
-  in `sources/hopsnative.py`: a **pure-Python** driver for the same HOPS laser
-  over `pyftdi` I2C, with no CohrHOPS.dll (works on macOS/Linux). Reverse-
-  engineered from the sniffed I2C protocol (see `manuals/Coherent-HOPS-I2C-*`):
-  identity/temperature from EEPROM 0x52 / ADC 0x48, on-off/shutter/remote from
-  I/O expander 0x25 (read-modify-write), power setpoint to DAC 0x29. Advertises
-  `OnOffControl` / `ShutterControl` / `PowerControl`; not `InterlockControl`,
-  because the full `?FF` fault decode, `PLIM`, and the ADC power-read scale were
-  not pinned down by the capture (documented gaps). Hardware-confirmed end to end
-  on the lab Genesis CX-Vis (identity, states, remote/shutter/enable writes,
-  power=0, temperature). Requires pyftdi + a reachable libusb; on Ventura it
-  claims the FT2232 without unloading Apple's VCP driver.
+- `HOPSDevice` (and `DebugHOPSDevice`): one laser-source driver for a Coherent
+  "HOPS" (High Output Power Supply) laser -- Genesis heads / Verdi G-C, e.g. the
+  lab Genesis CX-Vis (head `G532`). A HOPS supply is not a serial device: its
+  FTDI FT2232 (`0x0403:0x6010`) is driven as bit-banged I2C, with power DAC, ADC,
+  shutter/enable GPIO, and the head identity/calibration EEPROM all on one I2C
+  bus (see `manuals/Coherent-HOPS-*`). `HOPSDevice` combines `OnOffControl`,
+  `ShutterControl`, `PowerControl`, and `InterlockControl`, and drives the bus
+  through an interchangeable `HOPSInterface`:
+  - `HOPSNativeInterface` (`sources/hopsnative.py`): **pure-Python** pyftdi I2C,
+    no DLL (macOS/Linux). Hardware-confirmed end to end on the lab unit
+    (identity, on/off, shutter, remote, power setpoint, temperature). Its
+    `interlock()`/`faults()` raise `HOPSInterface.NotSupported` until the `?FF`
+    decode is reverse-engineered.
+  - `HOPSDLLInterface` (`sources/hopsdll.py`): Coherent's `CohrHOPS.dll` (ASCII
+    command set; Windows/Linux). Read + `REM`/`PCMD` write paths hardware-
+    confirmed; `KSWCMD`/`SHCMD` per the DLL spec, not yet exercised.
+  Selection: `HOPSDevice(interface="auto")` tries native first, then the DLL;
+  pass `"native"`/`"dll"`/an interface instance to force one. Protocol and I2C
+  decode in `manuals/Coherent-HOPS-USB-Protocol.md` and
+  `manuals/Coherent-HOPS-I2C-Decode.md`.
 
 ## [1.4.0] - 2026-07-08
 

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

@@ -83,22 +83,24 @@ x86-64).
 
 ## Using it from this library
 
-`hardwarelibrary/sources/hops.py` binds the DLL with ctypes:
+`HOPSDevice` drives the laser; the DLL is one of its interchangeable transports
+(`HOPSDLLInterface`), the native pyftdi I2C path (`HOPSNativeInterface`) the
+other. Normally you just let it pick:
 
 ```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])
+from hardwarelibrary.sources.hops import HOPSDevice
+
+laser = HOPSDevice(interface="auto")   # native first, then the DLL
+laser.initializeDevice()
+print(laser.laserModel, laser.headType, laser.headSerialNumber)
+laser.setPower(0.5); laser.turnOn(); laser.openShutter()
+laser.shutdownDevice()
 ```
 
-On macOS this raises `HOPSUnavailable` (no DLL exists for the platform).
+To force the DLL transport, use `HOPSDevice(interface="dll")`. The low-level
+ctypes binding to `CohrHOPS.dll` is `CohrHOPS` in `sources/hopsdll.py`; on macOS
+constructing the DLL interface raises `HOPSInterface.Unavailable` (no DLL for the
+platform), so `interface="auto"` falls through to native.
 
 ## Open question for the Verdi G specifically
 

hardwarelibrary/manuals/Coherent-HOPS-Verdi-G-Runbook.md

@@ -5,8 +5,8 @@ do it again. Written so a future session (human or AI) can reproduce it without
 rediscovering the dead ends.
 
 For the protocol details see `Coherent-HOPS-USB-Protocol.md`; for the driver see
-`hardwarelibrary/sources/verdig.py` and `hardwarelibrary/sources/hops.py`. This
-file is the *workflow*.
+`hardwarelibrary/sources/hops.py` (`HOPSDevice`) and its interfaces
+`hopsnative.py` / `hopsdll.py`. This file is the *workflow*.
 
 ---
 
@@ -229,20 +229,20 @@ cleared interlock + `REM=1` + `KSWCMD=1` + `PCMD>0`; the mechanical shutter
 
 ## The driver
 
-`hardwarelibrary/sources/hops.py` — `HOPSInterface`, a ctypes binding to
-`CohrHOPS.dll` (raises `HOPSUnavailable` where the DLL cannot load, e.g. macOS).
+`hardwarelibrary/sources/hops.py` — `HOPSDevice` (+ `DebugHOPSDevice`), one
+laser-source driver combining `OnOffControl` / `ShutterControl` / `PowerControl`
+/ `InterlockControl`. It drives the bus through an interchangeable
+`HOPSInterface`, chosen with `HOPSDevice(interface="auto")` (native first, then
+DLL), or forced with `"native"` / `"dll"` / an instance:
 
-`hardwarelibrary/sources/verdig.py` — `VerdiGDevice` (+ `DebugVerdiGDevice`),
-mapping the HOPS command set onto the library's capability mixins: `OnOffControl`
-(software switch `KSWCMD`), `PowerControl` (`PCMD`/`?P`), `ShutterControl`
-(`SHCMD`/`?SH`), `InterlockControl` (`?FF`). Bulk telemetry is exposed via a
-`diagnosticReads` table + `diagnostics()` / `diagnostic(name)`, with `query()` as
-the raw escape hatch. Tests: `hardwarelibrary/tests/testVerdiG.py`.
+- `hopsnative.py` — `HOPSNativeInterface`: pure-Python pyftdi I2C, no DLL
+  (macOS/Linux). Hardware-confirmed end to end on the lab unit; `interlock()` /
+  `faults()` raise `HOPSInterface.NotSupported` until the `?FF` decode is done.
+- `hopsdll.py` — `HOPSDLLInterface`: Coherent's `CohrHOPS.dll` (ASCII command
+  set; Windows/Linux), with the ctypes binding `CohrHOPS`.
 
-It runs only where `CohrHOPS.dll` loads (the Windows VM). On macOS, use
-`DebugVerdiGDevice`. A native-macOS path would require reimplementing the
-bit-banged-I2C framing over `pyftdi` MPSSE (the DLL's `.pdb` symbols map the
-`NXP`/`I2C` classes) — a separate project, not done here.
+Tests: `hardwarelibrary/tests/testHOPSDevice.py` (debug + native-on-mock always
+run; a hardware class skips when no laser is reachable).
 
 ---
 
@@ -251,7 +251,7 @@ bit-banged-I2C framing over `pyftdi` MPSSE (the DLL's `.pdb` symbols map the
 - Read path (identity, power, interlock/faults, all temperatures/hours): OK.
 - Write path `REM=1` and `PCMD=0.5` -> read back `?PCMD`=0.498 (head quantizes
   to ~2 mW, inside the driver's tolerance), `?P` stayed 0 (no emission, shutter
-  closed), then restored. So `VerdiGDevice`'s REM/PCMD/confirm logic is proven.
+  closed), then restored. So the DLL interface's REM/PCMD/confirm logic is proven.
 - **Not yet exercised on hardware (safety):** `KSWCMD` (emission enable) and
   `SHCMD` (shutter open). Verify with the beam blocked and interlock cleared.
 - Note: at probe time `?FF`=`0x0220` — an active **interlock fault** (+ glue-board
@@ -271,5 +271,5 @@ bit-banged-I2C framing over `pyftdi` MPSSE (the DLL's `.pdb` symbols map the
    `RUN_ME.bat` (read-only probe) — confirm `?LASERMODEL` / head type.
 5. Read `hops_probe_output.txt` back on the Mac.
 6. For control, either run PowerShell that calls the DLL (as above) in the guest,
-   or run `VerdiGDevice` (this library) inside the guest with a real Python +
+   or run `HOPSDevice(interface="dll")` (this library) inside the guest with a real Python +
    the DLLs. For emission, first clear the interlock and block the beam.

hardwarelibrary/sources/__init__.py

@@ -10,7 +10,8 @@
     MillenniaEv25Device, DebugMillenniaEv25Device,
     MillenniaDevice, DebugMillenniaDevice,
 )
-from .verdig import VerdiGDevice, DebugVerdiGDevice
-from .hopsnative import (
-    HOPSNativeI2C, NativeVerdiGDevice, DebugNativeVerdiGDevice, MockHOPSBus,
+from .hops import (
+    HOPSDevice, DebugHOPSDevice, HOPSInterface, DebugHOPSInterface,
 )
+from .hopsnative import HOPSNativeInterface, HOPSNativeI2C, MockHOPSBus
+from .hopsdll import HOPSDLLInterface