Add Agilent BenchCel 4R storage backend

CHANGELOG.md

@@ -8,10 +8,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- Agilent BenchCel 4R storage backend (`pylabrobot.storage.agilent.BenchCel4RBackend`) speaking the reverse-engineered binary TCP/7612 protocol, plus a `BenchCel4R(...)` factory. The BenchCel is modelled with the sequential `Stacker` capability (its four stackers are LIFO `ResourceStack`s) and the backend implements `downstack`/`upstack`. Includes calculation-based BenchCel labware helpers (preferring a plate's `stacking_z_height` for the device `StackingThickness`), a `set_labware(...)` command that pushes labware geometry to the device via the decoded `0x7d`/`0x9f` settings protocol, an in-process mock server, and a user guide. Opening the stacker clamps (which can drop a plate stack) is exposed as `dangerously_open_stacker_grippers`.
 - HighRes Biosolutions MicroSpin centrifuge backend (`pylabrobot.centrifuge.highres.MicroSpinBackend`) speaking the device's ASCII command/response protocol over TCP/1000, plus a `MicroSpin(...)` factory.
 - In-process `MicroSpinMockServer` (`pylabrobot.centrifuge.highres.mock_server`) that faithfully emulates the MicroSpin's wire protocol -- including the firmware's "`status` blocks until the spindle has stopped" semantics and the low-G spin-down-detection hang -- usable as a Python async context manager or runnable as a script (`python -m pylabrobot.centrifuge.highres.mock_server`) for `nc`/`telnet` debugging.
 - `MicroSpinBackend.reset()` recovery helper that issues `abort` -> `clearbuttonabort` -> `status`, using the last as the gate that genuinely confirms the rotor has stopped.
 - User guide notebook for the MicroSpin (`docs/user_guide/01_material-handling/centrifuge/highres_microspin.ipynb`).
+- `Stacker` capability (`pylabrobot.storage.Stacker`) for sequential ("stacking access") plate storage: one or more single-ended LIFO `ResourceStack` stacks plus a transfer position ("loading tray"), with `downstack`/`upstack` operations and a `StackerBackend` interface (plus `StackerChatterboxBackend`). Intended for devices like the Agilent BenchCel and HighRes MicroServe (#1113).
 
 ### Fixed
 

docs/api/pylabrobot.rst

@@ -19,6 +19,7 @@ Subpackages
     pylabrobot.only_fans
     pylabrobot.resources
     pylabrobot.scales
+    pylabrobot.storage
     pylabrobot.io.sila
     pylabrobot.shaking
     pylabrobot.temperature_controlling

docs/api/pylabrobot.storage.rst

@@ -0,0 +1,71 @@
+.. currentmodule:: pylabrobot.storage
+
+pylabrobot.storage package
+==========================
+
+This package contains APIs for automated storage devices and incubators.
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    incubator.Incubator
+    stacker.Stacker
+    agilent.benchcel.BenchCel4R
+
+
+Backends
+--------
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    backend.IncubatorBackend
+    stacker_backend.StackerBackend
+    stacker_chatterbox.StackerChatterboxBackend
+    agilent.benchcel_backend.BenchCel4RBackend
+    cytomat.cytomat.CytomatBackend
+    liconic.liconic_backend.ExperimentalLiconicBackend
+
+
+Agilent BenchCel support classes
+--------------------------------
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    agilent.benchcel_backend.Frame
+    agilent.benchcel_backend.SensorStatus
+    agilent.benchcel_backend.ArmStatus
+    agilent.benchcel_backend.GeneralStatus
+    agilent.benchcel_backend.Teachpoint
+    agilent.benchcel_backend.AxisBoundsResponse
+    agilent.benchcel_backend.CurrentPositionResponse
+    agilent.benchcel_labware.BenchCelLabwareSettings
+    agilent.benchcel_labware.PlateNotchSettings
+    agilent.benchcel_labware.apply_benchcel_labware_settings
+    agilent.benchcel_labware.calculate_benchcel_labware_settings
+    agilent.benchcel_labware.calculate_robot_gripper_offset
+    agilent.benchcel_labware.calculate_sensor_offset
+    agilent.benchcel_labware.calculate_stacker_gripper_offset
+    agilent.benchcel_labware.calculate_stacking_thickness
+    agilent.benchcel_mock_server.BenchCelMockServer
+    agilent.stacks.benchcel_4r_stacks
+
+
+Errors
+------
+
+.. autosummary::
+  :toctree: _autosummary
+  :nosignatures:
+  :recursive:
+
+    agilent.benchcel_backend.BenchCelDeviceError
+    agilent.benchcel_backend.BenchCelProtocolError
+    agilent.benchcel_backend.BenchCelTimeoutError