[BioCam]

Stacked on #1612: only the last two commits are this PR.

The Problem

On Windows, an FTDI device comes bound to FTDI's own driver, installed by Windows Update or with the device's software. PyLabRobot's FTDI transport talks through libftdi and libusb, which can't open a device bound to that driver. Today the only way in is to rebind the device with Zadig. After that, every other program that uses the device can't reach it until FTDI's driver is restored by hand.

FTDI's driver comes with its own library, D2XX (ftd2xx.dll). Through it, PyLabRobot can open the device with the driver Windows already has: no Zadig, and the device's own software keeps working whenever PyLabRobot isn't connected.

PR Content

• FTDI(..., ftdi_library=...):
  • "libftdi": the default, unchanged.
  • "d2xx": FTDI's own D2XX library (ftd2xx.dll, libftd2xx.dylib/.so), loaded with ctypes. There's nothing new to pip-install, and PyLabRobot doesn't bundle the library: it comes with FTDI's driver.
  • None: D2XX on Windows when the library loads, else libftdi.
• Finding a channel: D2XX names each channel by serial number plus interface letter, e.g. <serial>A and <serial>B on an FT2232H. device_id stays the base serial number and interface_select picks the letter. usb_address is refused under D2XX, which has no USB address, and the error lists the channels it found.
• A channel another program holds is refused before anything is sent. The error says what to do: close that program or stop its service, or use ftdi_library="libftdi" for a device rebound with Zadig. D2XXError carries D2XX's status code.
• Every FTDI call has its D2XX counterpart: baud rate, line properties, flow control, RTS/DTR, latency timer, purge, reset and modem status. Reads don't block, as with libftdi.
• Captures: the D2XX path records one setup entry naming the library. libftdi captures are unchanged, so existing captures still replay.
• Only the Mantis uses it: Mantis(..., ftdi_library=None) picks D2XX on Windows. Every other FTDI device keeps libftdi until it has been checked on D2XX itself.
• Tests: against a fake D2XX library: the automatic choice (Windows only), channel resolution and its refusals, every call, short writes, and the setup record replaying with and without it.

Usage

1. On Windows with FTDI's driver, the Mantis picks D2XX by itself: no Zadig, nothing to set

from pylabrobot.formulatrix import Mantis

mantis = Mantis(name="mantis", declared_configuration_json="my_mantis.json")
await mantis.setup()  # log: "Successfully opened FTDI device: … (d2xx)", once per interface

2. A Mantis already rebound with Zadig keeps libftdi

mantis = Mantis(name="mantis", declared_configuration_json="my_mantis.json", ftdi_library="libftdi")

3. Any FTDI device can choose D2XX explicitly

from pylabrobot.io.ftdi import FTDI

io = FTDI(human_readable_device_name="my device", device_id="FT12AB34", ftdi_library="d2xx")

4. While another program holds the Mantis, setup refuses before sending anything

RuntimeError: No FTDI channel found through D2XX for 'Formulatrix Mantis' (device_id None, interface B). … 2 held by another program list no serial number: close the vendor software or stop its service.

On the device

A Mantis v4 on a Windows PC with FTDI's driver and the vendor software installed, plus the same steps on macOS:

	result
automatic choice on Windows	d2xx, from C:\Windows\System32\ftd2xx.dll; both channels opened, no Zadig
every #1612 step (connect, reads, clamp at levels 1–3, release, declared file agreeing / claiming v3, RFID tags, no folder)	pass; the bytes written are identical to macOS over libftdi
setup while the vendor software holds the Mantis	refused; a USB capture shows nothing sent
the vendor software closed, then setup	connects
the vendor software after PyLabRobot	starts up, passes its pressure test, scans the chips
macOS, libftdi	every step's bytes unchanged

🤖 Generated with Claude Code

[BioCam]

when this helps, on a windows pc that keeps FTDI's own driver:

• sharing a pc with the vendor software: plr and the vendor software take turns on one instrument, no driver swap in between
• locked-down or validated pcs: no admin rights and no driver change needed, unlike zadig
• no silent breakage: windows update or a vendor update reinstalling FTDI's driver can't undo anything
• first run: install, plug in, run; no zadig step
• clearer errors: a channel held by another program is refused before anything is sent, saying what to close

not covered: running plr and the vendor software at the same time (one program per channel), and devices already rebound with zadig (keep ftdi_library="libftdi"). other FTDI devices can opt in with ftdi_library="d2xx" once checked on it; only the Mantis defaults to it here.

[rickwierenga]

this is awesome! please merge (mantis should be separated though)

[BioCam]

stacked on #1612 now, so this diff is just the ftdi change (3 io files) plus the small mantis switch that uses it (4 files, ~35 lines). #1612 merges first, then this one.