Add Labcyte Echo Support

[alexjamesgodfrey]

Summary

Support for Labcyte (acq. Beckman) Echo acoustic liquid handlers under PyLabRobot's v1b1 architecture.

This started as Echo 650 only, but the branch now covers both the Echo 650 and the Echo 525 through a single Echo frontend, and has adopted the driver-architecture refactor @c-reiter and I discussed with @rickwierenga below. I've folded the two stacked follow-ups (#5 for the 525, and the driver refactor on top of it) directly into this branch so it's one coherent PR to review rather than a three-deep stack — credit to @c-reiter for the 525 work, the EchoMockServer, and the refactor commits (their authorship is preserved in the history).

What's here:

• One Echo frontend, model as a parameter — Echo(host, model="Echo 650" | "Echo 525"), backed by an ECHO_MODELS registry (the two differ only in droplet increment, 2.5 nL vs 25 nL, and the version strings the firmware advertises). Echo525 remains as a deprecation shim.
• EchoDriver is an ABC with MedmanEchoDriver (real Medman SOAP-over-HTTP) and EchoChatterboxDriver (logs, no I/O) as sibling implementations, injected via Echo(driver=...). This is the shape @rickwierenga signed off on, and keeps the door open for a vendor-SDK driver / the iDOT later.
• Lock/unlock, instrument info, DIO/access-state polling, and event-stream support.
• Source/destination plate access operations and safe close-door handling, exposed through the generic plate_access capability (PlateAccess + EchoPlateAccessBackend).
• Source plate-map upload, plate survey, saved-survey retrieval, dry-plate support, and focus calibration.
• PLR-native transfer generation: build_echo_transfer_plan() from PLR resources/wells, higher-level transfer() / transfer_wells(), EchoPlatePosition source/destination modeling, and liquid-tracker updates (apply_volumes_to_plate()).
• Raw DoWellTransfer execution for pre-built Echo protocol XML via do_well_transfer() + EchoTransferPrintOptions, still available underneath.
• Per-transfer destination offsets: optional dx / dy / tag on EchoPlannedTransfer, emitted into each <wp> element (firmware slots confirmed present from a hardware Medman capture — see the offset discussion in the thread; they're zero on a plate-to-plate reformat). The default path is byte-identical to before, so nothing changes for existing callers.
• Hardware-free testing: EchoMockServer replays captured Echo responses, so the full survey → dry → transfer path has regression coverage without an instrument.

v1b1 conformance notes

• P-01 (driver ≠ capability method names): the EchoDriver methods that used to share names with PlateAccess operations (lock, open_source_plate, close_door, …) are renamed to vendor-endpoint verbs (lock_instrument, present_source_gripper, close_instrument_door, …), so EchoPlateAccessBackend now does a real abstract-op → vendor-verb translation instead of pass-through-by-identical-name.
• Capability bypass: run_picklist routes its lock/unlock through self.plate_access rather than the driver. (close_door is deliberately kept on the driver inside run_picklist — the capability's close_door polls an access-state precondition the picklist context never establishes; there's a comment explaining it.)

Todo

• Add pylabrobot.labcyte namespace
• Add EchoDriver, EchoPlateAccessBackend, and Echo frontend
• Implement Echo Medman SOAP-over-HTTP transport
• Handle gzip-compressed responses and Echo request quirks
• Add instrument setup/teardown path
• Add GetInstrumentInfo
• Add lock/unlock/session control
• Add DIO/access-state polling
• Normalize source/destination access state
• Add source plate present/retract operations
• Add destination plate present/retract operations
• Add safe close_door() behavior
• Add generic PLR plate_access capability
• Wire Echo into PlateAccess
• Add event stream parsing/reading support
• Add source plate map upload
• Add PlateSurvey
• Add GetSurveyData
• Add DryPlate
• Add survey_source_plate() helper workflow
• Add SetSurveyData
• Add transfer-volume metadata helpers
• Add raw DoWellTransfer execution
• Add EchoTransferPrintOptions
• Parse Echo transfer report XML
• Add focused unit tests for access, survey, events, and raw transfer execution
• Add user docs for Echo access, survey, and transfer execution
• Run focused pytest validation
• Run focused ruff validation
• Add PLR-native Echo protocol generation from PLR resources/wells (build_echo_transfer_plan())
• Add a higher-level transfer(...) API instead of requiring raw Echo protocol XML (transfer() / transfer_wells())
• Model Echo source/destination load positions as PLR resources (EchoPlatePosition)
• Decide how Echo transfer results update PLR liquid trackers (apply_volumes_to_plate())
• Add Echo 525 support (single frontend, model=)
• Refactor to EchoDriver ABC + Medman/Chatterbox siblings (per @rickwierenga)
• Add EchoMockServer for hardware-free survey/transfer regression tests
• Expose optional per-transfer dx / dy / tag destination offsets
• Close v1b1 P-01 (driver ≠ capability names) + capability-bypass findings
• Run live 650 validation of the expanded survey/transfer path (currently mock-covered via EchoMockServer, not yet re-run on the instrument)
• Migrate the per-RPC TCP transport to plr.io
• Integrate physical plate movement with PLR arms/workcells, end to end
• Add an example: robot loads plate → Echo surveys/transfers → robot unloads plate
• Split echo.py into a package (driver.py / plate_access_backend.py / echo.py / chatterbox.py / models.py) — it's over the v1b1 file-size guidance
• Move the trigger+poll orchestration off the PlateAccess frontend into the backend (touches the shared capability — want to coordinate before changing it)
• Unify the two <wp> offset generators (picklist.py uses a µm convention; echo.py emits raw device units)
• Add broader docs explaining what is Echo-native vs PLR-native

Validation

• uv run --with pytest --with pytest-timeout --with pytest-asyncio python -m pytest pylabrobot/labcyte/echo_tests.py pylabrobot/labcyte/echo525_tests.py pylabrobot/labcyte/picklist_tests.py pylabrobot/capabilities/plate_access/plate_access_tests.py
• uv run --with ruff ruff check pylabrobot/labcyte pylabrobot/capabilities/plate_access

[xaviersvk]

Hey @alexjamesgodfrey — awesome work on this, thanks for sharing it!

Quick question: in _make_transfer_protocol_xml each <wp> only carries n / dn / v
(source, dest, volume). I'm wondering if <wp> might also take a per-transfer offset /
XY coordinate that just didn't show up in your capture.

The Echo can dispense to arbitrary positions on a destination (MALDI plates, slides,
membranes — feature-based stuff), so if your Wireshark session was a normal plate-to-plate
reformat, an optional offset attribute would never have hit the wire even if the firmware
supports it. Might just be hiding rather than missing.

Could be totally wrong (haven't tested on hardware), maybe offsets only live at the
plate-type level (A1OffsetX/Y etc.). But did you ever see anything on <wp> beyond n/dn/v,
or have a capture from a non-plate destination?

Happy to help test on hardware if useful — thanks again!

[c-reiter]

@xaviersvk - we can shed some light on this from hardware. We captured the Medman traffic of an Echo 525 running a plate-to-plate HiFi PCR reformat (~13.8k SOAP messages) while building 525 support on top of this PR (alexjamesgodfrey#5 against this branch), so we have the real <wp> elements the Echo software itself emits.

Your intuition is right: <wp> carries more than n/dn/v. Every <wp> the firmware emitted (9,360 of them) had these 11 attributes:

oid  v  n  r  c  dn  dr  dc  dx  dy  tag

So dx / dy — a per-transfer destination XY offset — are part of the protocol. In our capture they were 0 on every element, exactly as you guessed: a normal plate-to-plate reformat emits the offset slots but leaves them zero ("hiding rather than missing").

The transfer report (<w> in the DoWellTransfer response) backs up the geometry model. Each well echoes dx/dy (=0) next to the firmware's resolved absolute acoustic target gx/gy and transducer tz, e.g.:

<w n="A2" r="0" c="1" dn="A1" dr="0" dc="0" vt="150" avt="150"
   dx="0" dy="0" gx="107259" gy="56368.8" tz="18198.704"
   fld="CP-Buffer" sv="1488.689" tof="35.548" .../>

i.e. destination = dn/dr/dc + dx/dy, which the firmware resolves into absolute gx/gy. The offset clearly feeds into absolute positioning.

Caveats (where you'd still be the one to confirm on hardware): our run was plate-to-plate, so dx/dy were never non-zero anywhere in the capture. We can confirm the attributes exist and are accepted/echoed by the firmware, but not that a non-zero offset is honored, nor the exact units (likely the same device-unit space as gx/gy, ~10⁵, but that's inference). A capture from a MALDI/slide/feature-based destination would pin that down — happy to compare notes if you run one.

Practical takeaway for this PR: the minimal <wp n dn v> works because the firmware fills in r/c/dr/dc (derivable from n/dn) and defaults dx/dy/tag. So exposing per-transfer offsets later is a small change — add optional dx/dy (and tag) to _make_transfer_protocol_xml; the firmware already has the slots.

[c-reiter]

@alexjamesgodfrey — while building Echo 525 support on top of this (alexjamesgodfrey/pylabrobot#5 against this branch) we went through the Todo checklist, and a bunch of the unchecked boxes actually look already implemented in the current head — might be worth re-ticking so the PR reads as complete:

• Add PLR-native Echo protocol generation from PLR resources/wells → build_echo_transfer_plan() / _make_transfer_protocol_xml()
• Add a higher-level transfer(...) API instead of raw protocol XML → transfer() / transfer_wells()
• Model Echo source/destination load positions as PLR resources/PlateHolders → EchoPlatePosition + source_position / destination_position
• Decide how Echo transfer results should update PLR liquid trackers → update_volume_trackers + apply_volumes_to_plate() / _apply_transfer_volume_tracking()

Still genuinely open from what we can tell: the live 650 run, deeper arm/workcell plate-movement integration, and the "Echo-native vs PLR-native" explainer doc.

On "run or document live validation for the expanded survey/transfer path": we captured the Medman traffic of a physical Echo 525 running a full survey + transfer + dry-plate sequence and built an in-process mock (EchoMockServer) that replays those real responses. It now drives the whole expanded path hardware-free in a test — survey_source_plate (SetPlateMap → PlateSurvey → GetSurveyData → DryPlate) → DoWellTransfer — and asserts the real survey well + dry mode + RPC order. Since the 525 and 650 share the Medman protocol, that mock is reusable as 650 validation too. Happy to break it out of the 525 PR into a standalone contribution here if that's useful to you.

Thanks again for this — the 525 was a near-trivial add precisely because the driver was structured so well. 🙏