Skip to content

Implement ODTC with the direct device API - #1026

Merged
rickwierenga merged 73 commits into
PyLabRobot:mainfrom
cmoscy:odtc-v1b1
Nov 11, 2026
Merged

rickwierenga merged 73 commits into
PyLabRobot:mainfrom
cmoscy:odtc-v1b1

Conversation

@cmoscy

@cmoscy cmoscy commented May 5, 2026 •

Copy link
Copy Markdown
Contributor

Add a plain ODTC device API for 96- and 384-well thermocyclers, with door control, temperature reads, protocol preparation and execution, stored methods, progress, and explicit stopping. Protocols compile locally to the firmware’s MethodSet format with native loops, explicit ramp rates, PID settings, and overshoot values. Execution waits for matching block/lid preparation and method completion; canceling or timing out a completion wait leaves the device running until explicitly stopped.

Place the SOAP codec under pylabrobot.inheco, share the SiLA session with SCILA, and route outgoing HTTP and incoming callbacks through pylabrobot.io. Correlate callbacks by request ID, retain completed errors for later waiters, and allow temperature reads and stopping during execution. Update the ODTC notebook, API documentation, and device registry.

Validation: 88 affected tests and 28 subtests pass, including SCILA regression coverage and a loopback HTTP/callback integration test. Ruff, targeted mypy, notebook and registry validation, and the full documentation build pass.

Both variants remain marked as needing hardware verification. Automatic empirical overshoot is opt-in pending validation; explicit overshoot settings are preserved. The plate-holder location must be calibrated before robotic transfers.

rickwierenga and others added 30 commits March 23, 2026 12:42
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
…obot#954)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…#956)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
y: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Notebook autoreload creates new class objects, breaking isinstance
checks on backend params (silently falling back to defaults). BackendParams
uses a metaclass with __instancecheck__ that falls back to qualname+module
comparison, which stays stable across reloads.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- DeviceBackend -> Driver (with backward-compat alias)
- Device._backend -> Device._driver, param backend -> driver
- New CapabilityBackend ABC for capability-specific backend interfaces
- All 15 abstract capability backends now extend CapabilityBackend
- Concrete backends extend both their capability backend and Driver
- Serialization key "backend" -> "driver" (deserialize accepts both)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Every monolithic backend that extended both a CapabilityBackend and Driver
is now split into:
- Driver: owns I/O, connection lifecycle, device-level ops
- CapabilityBackend: protocol translation, encodes capability calls into
  driver commands

Devices split: HepaFan, BioShake, Pico, Opentrons TempModule, Hamilton
HeaterShaker, Hamilton TiltModule, Keyence BarcodeScanner, XPeel, SCILA,
MettlerToledo, A4S, VSpin/Access2, CLARIOstar, SpectraMax 384+/M5.

Also: CapabilityBackend gains _on_setup/_on_stop hooks, Capability._on_setup
calls backend._on_setup, updated creating-capabilities.md, updated all
legacy wrappers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Recording backends and chatterbox backends are now pure CapabilityBackends.
Test devices use a _NullDriver for the Device lifecycle.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Test capabilities directly via cap._on_setup() instead of wrapping
in a fake Device.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix import sorting across 10+ files (ruff format --fix)
- Fix MolecularDevices legacy backend: reference renamed class, update test mocks to patch at correct level (Driver/Protocol instead of legacy wrapper)
- Fix Pico legacy tests: split Driver/MicroscopyBackend usage to match new architecture
- Fix Opentrons temp module: add base-type annotations for if/else branches
- Fix Liconic: use _on_setup/_on_stop (CapabilityBackend API)
- Fix Azenta A4S: type: ignore[safe-super] for abstract Driver methods
- Fix Pico backend: self._snap_images() instead of self._driver._snap_images()

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move shaker/tc capabilities into base class with has_shaking,
has_temperature, supports_active_cooling flags. Add resource
definitions for BioShake3000, BioShake3000Elm, BioShake3000ElmDWP,
and BioShakeQ1 from spec sheets.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…nds (PyLabRobot#957)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Extract autoload firmware protocol into a standalone class that takes a
driver reference and operates on track numbers instead of Carrier objects.
The legacy STARBackend and new STAR device can both wire into this class.
Includes 36 tests covering all command types.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
PlateReader now delegates reads through AbsorbanceCapability,
LuminescenceCapability, and FluorescenceCapability via adapter backends
that wrap the legacy PlateReaderBackend. Extracted _DictBackendParams
into pylabrobot/legacy/_backend_params.py for reuse across legacy
adapters.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move autoload, cover, x-arm, wash station, and ~44 generic driver
infrastructure methods (firmware queries, EEPROM, area reservation,
configuration) into the new STARDriver architecture. Legacy backend
methods now delegate to new classes or have deprecation docstrings.

- STARAutoload: autoload module control (carrier loading, barcode, LEDs)
- STARCover: front cover lock/unlock/enable/disable
- STARXArm: left/right X-arm positioning (parameterized by side)
- STARWashStation: dual-chamber wash station drain/fill/init
- STARDriver: generic instrument operations directly on driver
- STARChatterboxDriver: updated with all subsystems
- STAR device only exposes capabilities (PIP, Head96, iSWAP)
- Subsystems live on the driver, accessed via star._driver
- 114 tests across all subsystems
- Right X-arm and wash station are conditional on hardware config
- X-arm methods use mm (PLR standard), not 0.1mm firmware units
- Fixed pre-existing assertion bugs in release_occupied_area and
  set_instrument_configuration

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
These methods send a command to hardware and wait for a response,
so request_ better reflects the I/O semantics. Covers PreciseFlex,
capability interfaces (temperature, humidity), and all vendor backends
(Azenta, Agilent, BMG, Byonoy, Hamilton, INHECO, Liconic, Molecular
Devices, Opentrons, Qinstruments, Thermo Fisher). Legacy public APIs
keep get_ names unchanged; only internal delegations are updated.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move 14 multi-channel PIP operations to STARPIPBackend: channel
positioning (Y/Z), initialization, spread, z-safety, foil piercing.
Parameters use mm (PLR standard) with internal 0.1mm conversion.

Key changes:
- pierce_foil and step_off_foil on STARPIPBackend with explicit deck param
- iSWAP-parked checks on Y-movement methods
- Channel min Y spacing queried from firmware in driver setup()
- Right X-arm conditional on right_x_drive_large
- Wash station conditional on wash_station_*_installed
- Legacy backend aliases (left_x_arm, iswap) for PIPBackend compat
- Fixed pierce_foil one_by_one bug (z vs z+distance_from_bottom)
- Fixed _ensure_can_reach_position dead fallback (is None vs not)
- Architecture doc updated

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ot#885)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
…ot#980)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…Robot#964)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two new dispensing capabilities under bulk_dispensers/:
- SyringeDispensing: dispense(plate, volumes={col: vol}), prime(plate, volume)
- PeristalticDispensing: dispense(plate, volumes={col: vol}), prime(), purge()

Both use BackendParams for device-specific parameters.
Also adds BackendParams to PlateWashingCapability.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- EL406Driver: FTDI I/O, batch management, device-level ops, queries
- EL406PlateWashingBackend: manifold ops (wash, aspirate, dispense, prime)
- EL406ShakingBackend: shake/soak
- EL406SyringeDispensingBackend: syringe dispense/prime
- EL406PeristalticDispensingBackend: peristaltic dispense/prime/purge

Legacy code is thin wrappers delegating to new backends. All 385 tests pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…tecture

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move plate washer docs from 00_liquid-handling/plate-washing/ to
agilent/biotek/el406/ and heater-shaker docs from
01_material-handling/heating_shaking/ to qinstruments/bioshake/.
Add Manufacturers toctree section with manufacturer-level indexes.
Include migration guide at repo root for future device migrations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move device docs from legacy category dirs (00_liquid-handling/,
01_material-handling/, 02_analytical/) to manufacturer-based layout
mirroring the codebase. Add Manufacturers toctree section and API
reference RST files for all manufacturers with autosummary directives
and autoclass for nested BackendParams. Add Sphinx cross-references
for BackendParams in notebook markdown cells.

Devices migrated: EL406, BioShake, Mettler Toledo WXS205SDU,
Azenta a4S, Azenta XPeel, Liconic STX, Inheco ThermoShake,
Inheco CPAC, Inheco SCILA, Inheco Incubator Shaker, Inheco ODTC,
Thermo Fisher Multidrop Combi.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
rickwierenga and others added 19 commits April 8, 2026 19:56
… in backends

- Add HasLoadingTray mixin for devices with a loading tray
- Add MolecularDevicesLoadingTrayBackend (sends !OPEN/!CLOSE directly)
- SpectraMaxM5/384Plus: replace PlateHolder with LoadingTray capability
- BioTekLoadingTrayBackend: send J/A commands directly, not via driver.open/close
- Cytation5/Cytation1: add HasLoadingTray mixin

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Rick Wierenga <rick_wierenga@icloud.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Rick Wierenga <rick_wierenga@icloud.com>
Each of the 4 drawers is now a LoadingTray keyed by drawer_id in
`scila.drawers`. Command sequences (PrepareForInput/OpenDoor,
PrepareForOutput/CloseDoor) and drawer_id validation move from the
driver into SCILADrawerLoadingTrayBackend. Re-add CO2-flow warning
suppression (log + continue) that had been lost in the rewrite.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…re (PyLabRobot#989)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Hazlam Shamin <69739427+hazlamshamin@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…imbus

Deck is now passed into the driver at __init__ time (not through setup), so
the driver can construct backends with deck as a required arg. PIP/Head96
capabilities also take deck required on __init__. Legacy STARBackend still
receives deck via set_deck (legacy flow) and forwards it to the already-built
STARDriver.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Makes gripper_length and gripper_z_offset required on PreciseFlexArmBackend
(no sensible backend-level defaults — they depend on the mounted gripper)
and moves the per-model defaults (162 mm length, 0 mm z offset) to the
PreciseFlex400 Device wrapper so users can override them when installing
a non-stock gripper.

Also renames PF400Params.z_tool_offset to gripper_z_offset for naming
consistency with the user-facing parameter.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Rick Wierenga <rick_wierenga@icloud.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PIPChannel.request_firmware_version and STARDriver.request_firmware_version
now parse the RF response through parse_star_firmware_version_date and
return a datetime.date, matching what STARHead96Backend already did.
ztouch_probe_z_height uses version.year < 2022 directly instead of
regex re-parsing the raw string.

Drop the chatterbox-None fallback from STARHead96Backend.request_firmware_version:
chatterbox paths should explicitly override the method (or accept the
ValueError) rather than silently advertising a fabricated date.

Legacy STARBackend.request_pip_channel_version keeps its str return type
by inlining the raw RF query — the new PIPChannel method now returns
datetime so direct delegation would have broken the legacy contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@cmoscy

cmoscy commented May 5, 2026 •

Copy link
Copy Markdown
Contributor Author

More thorough physical testing this week, but wanted to get on here so I don't forget.

Improved ODTC backend in v1b1 API. Implementation of the Thermocycling capability with Protocol standard. Includes improvements from #894 discussion.

@rickwierenga rickwierenga changed the title Improved ODTC Backend in v1b1 Implement ODTC with the direct device API Nov 11, 2026
@rickwierenga
rickwierenga changed the base branch from v1b1 to main November 11, 2026 20:11
@rickwierenga
rickwierenga requested a review from a team as a code owner November 11, 2026 20:11
@rickwierenga
rickwierenga merged commit 6e1e6d6 into PyLabRobot:main Nov 11, 2026
24 of 26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants