Add Agilent Bravo liquid handler backend

[kelsorj]

Summary

Adds support for the Agilent Bravo — a fixed-head liquid handler with an integrated plate gripper — covering four hardware generations plus a simulation controller that needs no instrument.

Generation	Connection	Gripper
Darwin	TCP 7613 (Gemini protocol)	yes
Agile 7612	TCP 7612 (V11/Agile protocol)	yes
Bravo SRT	TCP 7612	no
Agile (legacy)	serial, or TCP 10000	yes
Simulation	none	configurable

from pylabrobot.agilent import AgilentBravoBackend, Bravo, BravoDeck

The constraint that shapes the API

The Bravo's barrels move as one unit on a single plunger drive. Every operation it can perform is therefore a contiguous rectangular block of head barrels, anchored at one of four corners.

That one rule governs the whole backend. A single well selects one barrel; a full column selects a column; the *96 methods use the whole head and honour gaps in the requested tips. A selection that isn't rectangular is rejected with a message saying what was asked for and what shape would work:

The requested selection is not a contiguous rectangle of barrels: 3 wells
spanning a 2x2 region leaves 1 gap. The head can address a full row, a full
column, a rectangular block, or a single barrel.

Because the plunger drive is shared, a multi-channel aspirate or dispense requires a uniform volume and flow rate. Non-uniform values are rejected rather than silently averaged.

Head geometry varies by installed head — 8x12 at 9 mm pitch, 16x24 at 4.5 mm, 8x1, 16x1 — so num_channels reports 8, 16, 96, or 384.

Layout

The driver lives at pylabrobot/agilent/bravo/, alongside the existing BenchCel, BioTek, and VSpin drivers, with the LiquidHandlerBackend subclass importing its base from pylabrobot.legacy.

This is a deliberate deviation from the driver guide's flat-driver guidance. The guide asks for one file and one plain class, and promotion to a package only when it genuinely helps. The Bravo spans two unrelated wire protocols across four hardware generations; flattening would produce single files of several thousand lines covering protocols that share nothing. Each module is scoped to a hardware concern — Gemini framing, per-axis commutation state machines, the V11 packet format.

The LiquidHandlerBackend base is imported from pylabrobot.legacy, where every existing liquid handler lives. The driver itself sits in the vendor-first tree with the other Agilent devices, since that appears to be the direction the codebase is moving.

Design notes

Transport. Bravo controllers are synchronous; pylabrobot.io is asynchronous. Rather than convert several thousand lines of controller code, a shared bridge submits each coroutine to the event loop that owns the connection and blocks the calling worker thread. All device I/O goes through pylabrobot.io.Socket and Serial.

The measured cost is ~70 µs per call (20,000 samples, low-end order statistics, stable across Python 3.9 and 3.11). Darwin's axis state machines poll at 5 Hz with an explicit sleep, and a full multi-axis homing cannot exceed roughly 1,000 polls before its own timeouts fire — so the bridge accounts for well under half a percent of a sequence dominated by deliberate waiting.

Deck. BravoDeck exposes the instrument's nine locations as a PyLabRobot Deck whose site origins come from the machine's taught X/Y/Z, so the model reflects the real instrument rather than a nominal layout. That means an instrument already taught works without a separate calibration step.

Capability flags. num_arms and head96_installed derive from the installed model, so a gripperless SRT reports no arm and PyLabRobot rejects plate movement before the backend is reached.

Hardware verification — please read this before merging

This is stated precisely because the split matters:

• Exercised against real instruments: the wire protocols and the controller layers, on Darwin, Agile 7612, SRT, and legacy Agile hardware.
• Not yet exercised on hardware: the pylabrobot.io transport bridge, the deck mapping, and AgilentBravoBackend itself.

setup() logs a warning saying exactly that, per the driver guide's requirement for unverified drivers, and the registry entry is status: wip. The warning comes off per generation as each is bench-verified through PyLabRobot.

One specific unknown worth a reviewer's attention: BravoDeck translates a PyLabRobot Plate or TipRack into the instrument's well grid — pitch, offset, and the sign convention for where A1 sits. The convention chosen is pinned by a test and documented in deck/resource.py, but it cannot be confirmed without an instrument. Under default teachpoints some deck sites are unreachable for a 96-well plate, which may indicate the convention needs flipping. If it does, exactly one test fails and points at the fix.

Known limitations

• 384-channel heads work through the per-channel path. They cannot use the *96 path, which requires exactly 96 tips. Generalising LiquidHandler to N channels looks like separate work; happy to take it on.
• The SRT is gripperless. It reports num_arms = 0, so PyLabRobot's own error fires on plate movement.
• Returning tips to a still-full box is constrained by the instrument: a return is legal only when the block's edge aligns with the still-occupied band, so row, column, and all_barrels round-trip cleanly while a single-barrel return is rejected with an explanation. Dropping to a trash is unconstrained.

Protocol provenance and safety

Neither wire protocol is vendor documentation. Both were recovered by observing traffic between Agilent VWorks and an instrument, and the modules say so. Neither carries authentication or encryption, so anyone with network access to an instrument can command it.

The implementation derives from pyBravo, my open-source Bravo control project, where the protocols were reverse-engineered and exercised on real instruments. That project remains independently maintained; this contribution brings the hardware layer to PyLabRobot.

pyBravo is an independent project, not affiliated with or endorsed by Agilent Technologies; product names identify the hardware the software runs on. Agilent has confirmed in writing that they do not object to its release.

The Bravo can break labware, crush a pipette head, or injure a hand. The guide's safety section and the module docstrings say so, and the simulation controller exists so a protocol can be dry-run with no instrument attached.

Test plan

• make test — 813 tests for this driver, full suite green
• make lint, make format-check — clean
• make typecheck — clean across 791 files
• ruff check --select E501 --line-length 100 — clean
• Hello-world guide executes end to end against the simulation controller, 12 of 13 code cells (the omitted one connects to a real instrument)
• Device registry tests — 230 passed
• No reflective attribute access anywhere in the package
• Bench validation of the transport bridge, deck mapping, and backend on real hardware

Correctness is pinned by golden-frame tests: the full ordered controller-call sequence for every homing routine, move, jog, grip, and state-machine task is checked in as a fixture, so a change in packet content, field order, or phase ordering fails immediately. Behaviour that depends on the controller generation, or that never reaches a controller call, is pinned by direct tests instead — captured sequences structurally cannot see those.

make docs-check currently fails on main with pre-existing autosummary stub warnings in pylabrobot.resources.biorad and corning, unrelated to this change. These commits add no new warnings.

Size

53,000 lines across 112 files, all additive except one export line in pylabrobot/agilent/__init__.py and the documentation entries. I'm conscious that's a lot to review at once. If it would help, I'm glad to split it — the natural seam is by hardware generation, with Darwin and the Agile family as separate PRs on a shared base. Happy to reshape it however is most useful.

[rickwierenga]

do you have an account on the PLR forum? you should add yourself as the device manager here (assuming you are interested in maintaining this)

[kelsorj]

@rickwierenga I'm kelsorjsf on PLR forum.