From 5a08885ad7a555a6c9da9376a2bb5a034463dc8a Mon Sep 17 00:00:00 2001 From: cmoscy <46687103+cmoscy@users.noreply.github.com> Date: Tue, 10 Nov 2026 23:28:54 -0800 Subject: [PATCH 01/11] `io.USB`: a serial number is read through the descriptor, not PyUSB's empty cache Choosing a device by `serial_number` compared it with `dev._serial_number`, which PyUSB fills only once something has read `dev.serial_number`. Straight after enumeration it is None, so every device was refused as having no serial number. The serial number is now read through the descriptor (`dev.serial_number`), and a device without one (`iSerialNumber == 0`) is still refused. --- pylabrobot/io/usb.py | 4 +++- pylabrobot/io/usb_tests.py | 25 +++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/pylabrobot/io/usb.py b/pylabrobot/io/usb.py index d8028dbf8ee..8f8b98b524a 100644 --- a/pylabrobot/io/usb.py +++ b/pylabrobot/io/usb.py @@ -351,7 +351,9 @@ def get_available_devices(self) -> List["usb.core.Device"]: continue if self._serial_number is not None: - if dev._serial_number is None: + # PyUSB reads the serial number descriptor on first access; `_serial_number` is only its + # cache, empty until then. + if dev.iSerialNumber == 0 or dev.serial_number is None: raise RuntimeError( f"A serial number was specified for '{self.human_readable_device_name}', but the device does not have a serial number." ) diff --git a/pylabrobot/io/usb_tests.py b/pylabrobot/io/usb_tests.py index 358d1f12ad5..c8ab3787f12 100644 --- a/pylabrobot/io/usb_tests.py +++ b/pylabrobot/io/usb_tests.py @@ -189,3 +189,28 @@ def test_validator_replays_a_write(self) -> None: ] validator = USBValidator(capture, "mock USB", 1, 2) self.assertEqual(validator.ctrl_transfer(0x40, 1, 0, 0, b"\x01"), bytearray()) + + +class USBDeviceSelectionTests(unittest.TestCase): + """Pick a device by serial number, reading the descriptor rather than PyUSB's empty cache.""" + + def _devices(self, *serials): + devices = [] + for serial in serials: + dev = Mock(iSerialNumber=3 if serial else 0, _serial_number=None, serial_number=serial) + devices.append(dev) + return devices + + def test_serial_number_is_read_through_the_descriptor(self) -> None: + devices = self._devices("A", "B") + with patch.object(usb_module, "libusb_package", create=True) as lib: + lib.find.return_value = devices + self.assertEqual( + USB(1, 2, "mock USB", serial_number="B").get_available_devices(), [devices[1]] + ) + + def test_device_without_serial_number_is_refused(self) -> None: + with patch.object(usb_module, "libusb_package", create=True) as lib: + lib.find.return_value = self._devices(None) + with self.assertRaisesRegex(RuntimeError, "does not have a serial number"): + USB(1, 2, "mock USB", serial_number="B").get_available_devices() From 94910a72220a2065b8ac604523dfb0f0208c92d8 Mon Sep 17 00:00:00 2001 From: cmoscy <46687103+cmoscy@users.noreply.github.com> Date: Tue, 10 Nov 2026 23:30:37 -0800 Subject: [PATCH 02/11] `resources`: Beckman Coulter Biomek labware The Biomek tips (T50F, T190F, T230, T1025F, T1070), their 96-tip boxes (BC50F, BC190F, BC230, BC1025F, BC1070), plates (Thermo96VB_PP, BCFlat96, BCDeep96Square, Thomson_24w_Square_RB, with the lids Biomek seats on them) and reservoirs (ThermoNUNC_350CB, Reservoir, ModularReservoir), transcribed from Biomek 5's tip and labware classes. A tip is a `BiomekTip`, a `Tip` that also carries its cone (the radius at its end and the length over which it widens); a well is a `BiomekWell`, a `Well` that also carries Biomek's outline of it by height (`WellSegment`s), from which its height <-> volume table and its wall come. Biomek uses both to place a tip near a well's wall, as `HamiltonTip` and `TecanTip` carry their instruments' data. A tip box is a `StandingTipRack` whose tip spots sit on its top face, where the head's mandrels meet the tips. Each resource carries Biomek's grip point (`preferred_pickup_location`). A resource library page lists them with their part numbers. --- docs/resources/index.md | 1 + docs/resources/library/beckman_coulter.md | 45 +++ pylabrobot/resources/__init__.py | 1 + .../resources/beckman_coulter/__init__.py | 24 ++ .../beckman_coulter/beckman_coulter_tests.py | 204 ++++++++++ .../beckman_coulter/biomek_resource.py | 219 +++++++++++ .../resources/beckman_coulter/plates.py | 348 ++++++++++++++++++ .../resources/beckman_coulter/tip_racks.py | 179 +++++++++ pylabrobot/resources/beckman_coulter/tips.py | 96 +++++ 9 files changed, 1117 insertions(+) create mode 100644 docs/resources/library/beckman_coulter.md create mode 100644 pylabrobot/resources/beckman_coulter/__init__.py create mode 100644 pylabrobot/resources/beckman_coulter/beckman_coulter_tests.py create mode 100644 pylabrobot/resources/beckman_coulter/biomek_resource.py create mode 100644 pylabrobot/resources/beckman_coulter/plates.py create mode 100644 pylabrobot/resources/beckman_coulter/tip_racks.py create mode 100644 pylabrobot/resources/beckman_coulter/tips.py diff --git a/docs/resources/index.md b/docs/resources/index.md index 86aa4006dbc..d101fca9d08 100644 --- a/docs/resources/index.md +++ b/docs/resources/index.md @@ -175,6 +175,7 @@ library/agenbio library/agilent library/alpaqua library/azenta +library/beckman_coulter library/bioer library/biorad library/boekel diff --git a/docs/resources/library/beckman_coulter.md b/docs/resources/library/beckman_coulter.md new file mode 100644 index 00000000000..af2e392ebd7 --- /dev/null +++ b/docs/resources/library/beckman_coulter.md @@ -0,0 +1,45 @@ +# Beckman Coulter + +Company page: [Beckman Coulter Life Sciences](https://www.beckman.com) + +Transcribed from the tip and labware classes of Biomek 5, Beckman Coulter's software for its Biomek +liquid handlers. The labware is defined as Biomek defines it, under Biomek's class names (in +quotes), whoever makes it. Tips are `BiomekTip`s, which also carry the tip's cone; wells are +`BiomekWell`s, which also carry Biomek's outline of the well by height. + +## Tips + +| Description | Image | PLR definition | +|-|-|-| +| 'T50F'
Biomek tip, 50 uL, filter | | `beckman_coulter_biomek_tip_50uL_filter` | +| 'T190F'
Biomek tip, 190 uL, filter | | `beckman_coulter_biomek_tip_190uL_filter` | +| 'T230'
Biomek tip, 230 uL, no filter | | `beckman_coulter_biomek_tip_230uL` | +| 'T1025F'
Biomek tip, 1025 uL, filter | | `beckman_coulter_biomek_tip_1025uL_filter` | +| 'T1070'
Biomek tip, 1070 uL, no filter | | `beckman_coulter_biomek_tip_1070uL` | + +## Tip racks + +| Description | Image | PLR definition | +|-|-|-| +| 'BC50F'
Part no.: B85888
Biomek tip box: 96 T50F tips | | `beckman_coulter_biomek_96_tiprack_50uL_filter` | +| 'BC190F'
Part no.: B85911
Biomek tip box: 96 T190F tips | | `beckman_coulter_biomek_96_tiprack_190uL_filter` | +| 'BC230'
Part no.: B85906 (sterile), B85903 (non-sterile)
Biomek tip box: 96 T230 tips | | `beckman_coulter_biomek_96_tiprack_230uL` | +| 'BC1025F'
Part no.: B85955
Biomek tip box: 96 T1025F tips | | `beckman_coulter_biomek_96_tiprack_1025uL_filter` | +| 'BC1070'
Part no.: B85945 (sterile), B85940 (non-sterile)
Biomek tip box: 96 T1070 tips | | `beckman_coulter_biomek_96_tiprack_1070uL` | + +## Plates + +| Description | Image | PLR definition | +|-|-|-| +| 'Thermo96VB_PP'
96 round, V-bottomed wells; with its 'TiterplateLid' | | `beckman_coulter_biomek_96_wellplate_vb` | +| 'BCFlat96'
Part no.: 609844
96 round, flat-bottomed wells; with its 'TiterplateLid' | | `beckman_coulter_biomek_96_wellplate_flat` | +| 'BCDeep96Square'
Part no.: 140504
96 deep, square, V-bottomed wells | | `beckman_coulter_biomek_96_deepwell_square` | +| 'Thomson_24w_Square_RB'
Part no.: 931568
24 square, round-bottomed wells; with its lid | | `beckman_coulter_biomek_24_wellplate_square_rb` | + +## Reservoirs + +| Description | Image | PLR definition | +|-|-|-| +| 'ThermoNUNC_350CB'
one flat-bottomed section; with its 'TiterplateLid' | | `beckman_coulter_biomek_reservoir_350cb` | +| 'Reservoir'
Part no.: 148033
one flat-bottomed section | | `beckman_coulter_biomek_reservoir` | +| 'ModularReservoir'
Part no.: 372795 (frame)
four V-bottomed sections | | `beckman_coulter_biomek_modular_reservoir` | diff --git a/pylabrobot/resources/__init__.py b/pylabrobot/resources/__init__.py index 07e878f25eb..00d3176d54e 100644 --- a/pylabrobot/resources/__init__.py +++ b/pylabrobot/resources/__init__.py @@ -3,6 +3,7 @@ from .agilent import * from .alpaqua import * from .azenta import * +from .beckman_coulter import * from .biorad import * from .boekel import * from .btx import * diff --git a/pylabrobot/resources/beckman_coulter/__init__.py b/pylabrobot/resources/beckman_coulter/__init__.py new file mode 100644 index 00000000000..4d4403ce12c --- /dev/null +++ b/pylabrobot/resources/beckman_coulter/__init__.py @@ -0,0 +1,24 @@ +from .biomek_resource import BiomekTip, BiomekWell, WellSegment +from .plates import ( + beckman_coulter_biomek_24_wellplate_square_rb, + beckman_coulter_biomek_96_deepwell_square, + beckman_coulter_biomek_96_wellplate_flat, + beckman_coulter_biomek_96_wellplate_vb, + beckman_coulter_biomek_modular_reservoir, + beckman_coulter_biomek_reservoir, + beckman_coulter_biomek_reservoir_350cb, +) +from .tip_racks import ( + beckman_coulter_biomek_96_tiprack_50uL_filter, + beckman_coulter_biomek_96_tiprack_190uL_filter, + beckman_coulter_biomek_96_tiprack_230uL, + beckman_coulter_biomek_96_tiprack_1025uL_filter, + beckman_coulter_biomek_96_tiprack_1070uL, +) +from .tips import ( + beckman_coulter_biomek_tip_50uL_filter, + beckman_coulter_biomek_tip_190uL_filter, + beckman_coulter_biomek_tip_230uL, + beckman_coulter_biomek_tip_1025uL_filter, + beckman_coulter_biomek_tip_1070uL, +) diff --git a/pylabrobot/resources/beckman_coulter/beckman_coulter_tests.py b/pylabrobot/resources/beckman_coulter/beckman_coulter_tests.py new file mode 100644 index 00000000000..72932f1c839 --- /dev/null +++ b/pylabrobot/resources/beckman_coulter/beckman_coulter_tests.py @@ -0,0 +1,204 @@ +"""Beckman Coulter Biomek tips, tip boxes, plates and reservoirs, against the figures of the Biomek +classes they transcribe (cm there, mm here).""" + +import math +import unittest + +from pylabrobot.resources import ( + BiomekTip, + Plate, + BiomekWell, + Resource, + WellSegment, + beckman_coulter_biomek_24_wellplate_square_rb, + beckman_coulter_biomek_96_deepwell_square, + beckman_coulter_biomek_96_tiprack_50uL_filter, + beckman_coulter_biomek_96_tiprack_190uL_filter, + beckman_coulter_biomek_96_tiprack_230uL, + beckman_coulter_biomek_96_tiprack_1025uL_filter, + beckman_coulter_biomek_96_tiprack_1070uL, + beckman_coulter_biomek_96_wellplate_flat, + beckman_coulter_biomek_96_wellplate_vb, + beckman_coulter_biomek_modular_reservoir, + beckman_coulter_biomek_reservoir, + beckman_coulter_biomek_reservoir_350cb, + beckman_coulter_biomek_tip_50uL_filter, + beckman_coulter_biomek_tip_190uL_filter, + beckman_coulter_biomek_tip_230uL, + beckman_coulter_biomek_tip_1025uL_filter, + beckman_coulter_biomek_tip_1070uL, +) +from pylabrobot.resources.tip_rack import StandingTipRack + + +class BiomekTipTests(unittest.TestCase): + def test_a_tip_has_its_class_figures(self) -> None: + # tipheight, capacity, filtered, coniclength (cm); every class seats 0.775 cm on the mandrel. + for make, length, volume, has_filter, cone in ( + (beckman_coulter_biomek_tip_50uL_filter, 51.359, 50.0, True, 38.227), + (beckman_coulter_biomek_tip_190uL_filter, 51.435, 190.0, True, 28.194), + (beckman_coulter_biomek_tip_230uL, 51.435, 230.0, False, 28.194), + (beckman_coulter_biomek_tip_1025uL_filter, 109.855, 1025.0, True, 19.8374), + (beckman_coulter_biomek_tip_1070uL, 109.855, 1070.0, False, 19.8374), + ): + with self.subTest(make.__name__): + tip = make("tip") + self.assertIsInstance(tip, BiomekTip) + self.assertAlmostEqual(tip.get_size_z(), length) + self.assertEqual(tip.maximal_volume, volume) + self.assertEqual(tip.has_filter, has_filter) + self.assertAlmostEqual(tip.fitting_depth, 7.75) + self.assertAlmostEqual(tip.cone_length, cone) + self.assertFalse(tip.is_conductive) + self.assertEqual(tip.model, make.__name__) + + def test_a_tip_widens_along_its_cone(self) -> None: + tip = beckman_coulter_biomek_tip_1070uL("tip") # mintipradius 0.0635, maxtipradius 0.2413 cm + self.assertAlmostEqual(tip.radius_at(0), 0.635) + self.assertAlmostEqual(tip.radius_at(19.8374 / 2), (0.635 + 2.413) / 2) + self.assertAlmostEqual(tip.radius_at(50), 2.413) + + def test_a_tip_reads_back_from_its_serialization(self) -> None: + tip = beckman_coulter_biomek_tip_230uL("tip") + back = Resource.deserialize(tip.serialize()) + self.assertIsInstance(back, BiomekTip) + self.assertEqual(back, tip) + self.assertNotEqual(back, beckman_coulter_biomek_tip_1070uL("tip")) + + +class BiomekTipBoxTests(unittest.TestCase): + BOXES = ( + # make, height, well1xoffset (mm), tip length + (beckman_coulter_biomek_96_tiprack_50uL_filter, 55.9, 14.5, 51.359), + (beckman_coulter_biomek_96_tiprack_190uL_filter, 55.9, 14.5, 51.435), + (beckman_coulter_biomek_96_tiprack_230uL, 55.9, 14.5, 51.435), + (beckman_coulter_biomek_96_tiprack_1025uL_filter, 114.1, 14.4, 109.855), + (beckman_coulter_biomek_96_tiprack_1070uL, 114.1, 14.4, 109.855), + ) + + def test_a_box_holds_96_of_its_tips_on_a_9_mm_grid(self) -> None: + for make, _, _, tip_length in self.BOXES: + with self.subTest(make.__name__): + rack = make("rack") + self.assertIsInstance(rack, StandingTipRack) + self.assertEqual((rack.num_items_x, rack.num_items_y), (12, 8)) + self.assertTrue(all(spot.has_tip() for spot in rack.get_all_items())) + self.assertAlmostEqual(rack.get_item("A1").get_tip().get_size_z(), tip_length) + a1 = rack.get_item("A1").get_location_wrt(rack) + a2 = rack.get_item("A2").get_location_wrt(rack) + b1 = rack.get_item("B1").get_location_wrt(rack) + self.assertAlmostEqual(a2.x - a1.x, 9.0) + self.assertAlmostEqual(a1.y - b1.y, 9.0) + + def test_tip_a1_stands_where_the_class_puts_it(self) -> None: + """A1's centre is `well1xoffset` from the left edge and 1.12 cm from the back edge; the tips' + tops are at the box's height, where the head's mandrels meet them.""" + for make, height, a1_x, _ in self.BOXES: + with self.subTest(make.__name__): + rack = make("rack") + self.assertEqual((rack.get_size_x(), rack.get_size_y()), (127.9, 85.4)) + self.assertAlmostEqual(rack.get_size_z(), height) + centre = rack.get_item("A1").get_location_wrt(rack, "c", "c", "b") + self.assertAlmostEqual(centre.x, a1_x) + self.assertAlmostEqual(centre.y, 85.4 - 11.2) + self.assertAlmostEqual(centre.z, height) + + def test_a_box_is_gripped_below_its_top(self) -> None: + # gripperinfo: the pads at its centre, the fingertips 0.23 cm below its bottom. + rack = beckman_coulter_biomek_96_tiprack_230uL("rack") + point = rack.preferred_pickup_location + assert point is not None + self.assertAlmostEqual(point.x, 127.9 / 2) + self.assertAlmostEqual(point.y, 85.4 / 2) + self.assertAlmostEqual(point.z, -2.3) + + +class BiomekPlateTests(unittest.TestCase): + def test_a_segment_holds_biomeks_section_volume(self) -> None: + # `sectionvolume` (uL) of each segment, from its outline: a cone, a frustum, a rectangular + # section, a round bottom (a spherical cap). + for make, volumes in ( + (beckman_coulter_biomek_96_wellplate_vb, (15.6665, 427.2566)), + (beckman_coulter_biomek_96_wellplate_flat, (365.708,)), + (beckman_coulter_biomek_96_deepwell_square, (133.645, 2282.995)), + (beckman_coulter_biomek_24_wellplate_square_rb, (1072.3303, 9248.0)), + ): + well = make("plate").get_well("A1") + assert isinstance(well, BiomekWell) + for segment, volume in zip(well.segments, volumes): + with self.subTest(make.__name__, volume=volume): + self.assertAlmostEqual(segment.volume(segment.height), volume, delta=0.002 * volume) + + def test_the_logged_liquid_level(self) -> None: + # 200 uL in Thermo96VB_PP: the 96-head's logged dispense rose 0.567 cm with the liquid. + well = beckman_coulter_biomek_96_wellplate_vb("plate").get_well("A1") + self.assertAlmostEqual(well.compute_height_from_volume(200), 5.667, delta=0.01) + assert isinstance(well, BiomekWell) + self.assertAlmostEqual(well.wall_distance(3.67, 0.0), 4.0) + + def test_a_square_well_meets_its_wall_at_the_side(self) -> None: + well = beckman_coulter_biomek_96_deepwell_square("plate").get_well("A1") + assert isinstance(well, BiomekWell) + self.assertAlmostEqual(well.get_size_x(), 8.28) + self.assertAlmostEqual(well.wall_distance(20.0, 0.0), 4.14) + self.assertAlmostEqual(well.wall_distance(20.0, math.pi / 4), 4.14 * math.sqrt(2)) + + def test_a_well_reads_back_from_its_serialization(self) -> None: + plate = beckman_coulter_biomek_96_wellplate_vb("plate", with_lid=True) + back = Resource.deserialize(plate.serialize()) + assert isinstance(back, Plate) + well = back.get_item("A1") + assert isinstance(well, BiomekWell) + self.assertEqual(well, plate.get_item("A1")) + self.assertEqual(well.segments[0], WellSegment(2.0, 2.735, 2.735, 0.0, 0.0)) + + def test_a_lid_sits_where_biomek_seats_it(self) -> None: + # Logged: the fingertips 1.000 cm above the plate's bottom for TiterplateLid on Thermo96VB_PP, + # and 4.200 cm for the Thomson lid on its plate. The lid covers the plate's footprint. + for make, tips_above in ( + (beckman_coulter_biomek_96_wellplate_vb, 10.0), + (beckman_coulter_biomek_24_wellplate_square_rb, 42.0), + ): + with self.subTest(make.__name__): + plate = make("plate", with_lid=True) + lid = plate.lid + assert lid is not None and lid.location is not None + point = lid.preferred_pickup_location + assert point is not None + self.assertAlmostEqual(lid.location.z + point.z, tips_above) + self.assertEqual( + (lid.get_size_x(), lid.get_size_y()), (plate.get_size_x(), plate.get_size_y()) + ) + + def test_an_uncentred_seat_moves_the_grip_point(self) -> None: + # The Thomson lid's seat is its plate's corner: its centre 0.381 mm left, 1.46 mm back. + plate = beckman_coulter_biomek_24_wellplate_square_rb("plate", with_lid=True) + lid = plate.lid + assert lid is not None and lid.preferred_pickup_location is not None + self.assertAlmostEqual(lid.preferred_pickup_location.x - lid.get_size_x() / 2, -0.381) + self.assertAlmostEqual(lid.preferred_pickup_location.y - lid.get_size_y() / 2, 1.4605) + + def test_plates_are_gripped_below_their_bottom(self) -> None: + plate = beckman_coulter_biomek_96_wellplate_vb("plate") + assert plate.preferred_pickup_location is not None + self.assertAlmostEqual(plate.preferred_pickup_location.z, -2.3) + + +class BiomekReservoirTests(unittest.TestCase): + def test_a_reservoir_section_is_a_box(self) -> None: + well = beckman_coulter_biomek_reservoir_350cb("res").get_well("A1") + self.assertAlmostEqual(well.compute_volume_from_height(10), 123.8 * 81.5 * 10, delta=0.01) + self.assertEqual(well.max_volume, 300000.0) + + def test_reservoirs_have_a_well_per_section(self) -> None: + self.assertEqual(len(beckman_coulter_biomek_reservoir("res").children), 1) + modular = beckman_coulter_biomek_modular_reservoir("mod") + self.assertEqual(len(modular.children), 4) + a1 = modular.get_item("A1") + self.assertAlmostEqual(a1.get_size_x(), 23.65) # x1 1.105 to x2 3.47 cm + assert isinstance(a1, BiomekWell) + self.assertEqual(a1.segments, ()) # a V bottom Biomek does not outline + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/resources/beckman_coulter/biomek_resource.py b/pylabrobot/resources/beckman_coulter/biomek_resource.py new file mode 100644 index 00000000000..63f6721c23d --- /dev/null +++ b/pylabrobot/resources/beckman_coulter/biomek_resource.py @@ -0,0 +1,219 @@ +"""Biomek's own shapes on PyLabRobot's resources: a tip's cone and a well's outline by height. + +Biomek describes a tip by its length, capacity and seating depth (which `Tip` holds) and also by its +cone, and a well by its sections from the bottom up, each with an outline that changes with height. +A Biomek touch-off places the tip against the wall at a height, so it needs both: these classes +carry them, and everything else about the resource is PyLabRobot's. +""" + +import math +from dataclasses import asdict, dataclass +from typing import Any, Dict, Mapping, Optional, Sequence, Tuple, Union + +from pylabrobot.resources.coordinate import Coordinate +from pylabrobot.resources.resource import Resource +from pylabrobot.resources.tip import Tip +from pylabrobot.resources.well import Well +from pylabrobot.utils.interpolation import interpolate_1d + + +class BiomekTip(Tip): + """A tip for Biomek instruments: a `Tip` with its cone, which Biomek uses to place the tip near a + wall (a touch-off), from `end_diameter` at its end to `diameter` over `cone_length` (mm).""" + + def __init__( + self, + name: str, + diameter: float, + size_z: float, + has_filter: bool, + maximal_volume: float, + fitting_depth: float, + end_diameter: float, + cone_length: float, + nominal_volume: Optional[float] = None, + collar_height: Optional[float] = None, + category: str = "tip", + model: Optional[str] = None, + pick_up_location: Optional[Coordinate] = None, + is_conductive: Optional[bool] = None, + ): + """Initialize a Biomek tip with its dimensions and its cone.""" + super().__init__( + name=name, + diameter=diameter, + size_z=size_z, + has_filter=has_filter, + maximal_volume=maximal_volume, + fitting_depth=fitting_depth, + nominal_volume=nominal_volume, + collar_height=collar_height, + category=category, + model=model, + pick_up_location=pick_up_location, + is_conductive=is_conductive, + ) + self.end_diameter = end_diameter + self.cone_length = cone_length + + def __eq__(self, other: object) -> bool: + """Compare tip fields and the cone.""" + return ( + isinstance(other, BiomekTip) + and super().__eq__(other) + and self.end_diameter == other.end_diameter + and self.cone_length == other.cone_length + ) + + def serialize(self) -> dict: + """Serialize a Biomek tip with its cone.""" + return { + **super().serialize(), + "end_diameter": self.end_diameter, + "cone_length": self.cone_length, + } + + def radius_at(self, from_end: float) -> float: + """The tip's outside radius `from_end` mm above its end: widening along the cone, then its + full radius.""" + end, full = self.end_diameter / 2, self.get_size_x() / 2 + if self.cone_length <= 0: + return full + return end + (full - end) * min(max(from_end, 0.0) / self.cone_length, 1.0) + + +@dataclass(frozen=True) +class WellSegment: + """One section of a Biomek well, from the bottom up, in mm. + + Attributes: + height: how tall the section is. + top_x, top_y: its half-widths at its top (the radius, for a round section). + bottom_x, bottom_y: its half-widths at its bottom (0 for a cone from a point). + round: whether its outline is round (else a rectangle). + cap: a round bottom: a spherical cap reaching `top_x` at `height`. + """ + + height: float + top_x: float + top_y: float + bottom_x: float + bottom_y: float + round: bool = True + cap: bool = False + + def half_widths(self, z: float) -> Tuple[float, float]: + """Half-widths (x, y), mm, `z` mm above the section's bottom.""" + if self.cap: + sphere = (self.top_x * self.top_x + self.height * self.height) / (2 * self.height) + r = math.sqrt(max(0.0, 2 * sphere * z - z * z)) + return r, r + t = z / self.height + return ( + self.bottom_x + (self.top_x - self.bottom_x) * t, + self.bottom_y + (self.top_y - self.bottom_y) * t, + ) + + def area(self, z: float) -> float: + """Cross-section, mm^2, `z` mm above the section's bottom.""" + hx, hy = self.half_widths(z) + return math.pi * hx * hy if self.round else 4 * hx * hy + + def volume(self, h: float) -> float: + """uL (mm^3) in the bottom `h` mm of the section. The area is quadratic in z for every shape, + so Simpson's rule is exact.""" + h = min(h, self.height) + if h <= 0: + return 0.0 + return h / 6 * (self.area(0) + 4 * self.area(h / 2) + self.area(h)) + + +# mm between a height -> volume table's heights where a section's cross-section changes with height +# (a cone, a cap): PyLabRobot interpolates between them. +KNOT_STEP = 0.1 + + +class BiomekWell(Well): + """A well with Biomek's outline by height (`segments`, bottom up): its height <-> volume table + (`height_volume_data`) is made from them, and `wall_distance` says where its wall is at a height. + With no segments it is a plain `Well`.""" + + def __init__( + self, + name: str, + size_x: float, + size_y: float, + size_z: float, + segments: Sequence[Union[WellSegment, Mapping[str, Any]]] = (), + height_volume_data: Optional[Dict[float, float]] = None, + max_volume: Optional[float] = None, + **kwargs: Any, + ): + self.segments: Tuple[WellSegment, ...] = tuple( + s if isinstance(s, WellSegment) else WellSegment(**s) for s in segments + ) + if height_volume_data is None and self.segments: + height_volume_data = self._height_volume_table(size_z) + if max_volume is None and height_volume_data is not None: + max_volume = interpolate_1d(size_z, height_volume_data, bounds_handling="error") + super().__init__( + name=name, + size_x=size_x, + size_y=size_y, + size_z=size_z, + height_volume_data=height_volume_data, + max_volume=max_volume, + **kwargs, + ) + + def half_widths(self, z: float) -> Tuple[float, float]: + """Half-widths (x, y), mm, `z` mm above the bottom (the top's above the top).""" + left = max(0.0, z) + for seg in self.segments: + if left <= seg.height: + return seg.half_widths(left) + left -= seg.height + last = self.segments[-1] + return last.half_widths(last.height) + + def wall_distance(self, z: float, angle: float) -> float: + """How far, mm, the wall is from the well's axis `z` mm above its bottom, in direction `angle` + (radians): the radius for a round well, to the nearest side for a rectangular one.""" + hx, hy = self.half_widths(z) + if all(s.round for s in self.segments): + return hx + c, s = abs(math.cos(angle)), abs(math.sin(angle)) + return min(hx / c if c > 1e-12 else math.inf, hy / s if s > 1e-12 else math.inf) + + def volume_at(self, z: float) -> float: + """uL held `z` mm above the bottom, by the segments.""" + left, v = z, 0.0 + for seg in self.segments: + v += seg.volume(left) + left -= seg.height + if left <= 0: + break + return v + + def _height_volume_table(self, depth: float) -> Dict[float, float]: + """A point at each section's ends, and every `KNOT_STEP` in a section whose cross-section + changes, up to the rim.""" + zs = [0.0] + for seg in self.segments: + h = seg.height + constant = seg.half_widths(0.0) == seg.half_widths(h) == seg.half_widths(h / 2) + n = 1 if constant else max(1, math.ceil(h / KNOT_STEP)) + zs += [zs[-1] + h * i / n for i in range(1, n + 1)] + if depth > zs[-1]: + zs.append(depth) + return {round(z, 6): self.volume_at(z) for z in zs} + + def __eq__(self, other: object) -> bool: + return ( + isinstance(other, BiomekWell) and super().__eq__(other) and self.segments == other.segments + ) + + __hash__ = Resource.__hash__ + + def serialize(self) -> dict: + return {**super().serialize(), "segments": [asdict(s) for s in self.segments]} diff --git a/pylabrobot/resources/beckman_coulter/plates.py b/pylabrobot/resources/beckman_coulter/plates.py new file mode 100644 index 00000000000..62de4335952 --- /dev/null +++ b/pylabrobot/resources/beckman_coulter/plates.py @@ -0,0 +1,348 @@ +"""Plates and reservoirs on Biomek's labware classes (cm there, mm here). + +- `xspan`, `yspan`, `height`: the footprint and height; `wellsx` / `wellsy`, `wellxspacing` / + `wellyspacing`, `well1xoffset` / `well1yoffset` (A1's centre from the left and back edges): the + grid; `welldepth`, the top segment's `topx` / `topy`: a well's size. +- `segments`: a well's outline from the bottom up (`WellSegment`), which gives its height <-> + volume table and where its wall is. +- a reservoir's `sections`: its wells, `x1..x2`, `y1..y2` from the left and back edges, `depth`. +- `gripperinfo`: where Biomek's gripper pads go (`preferred_pickup_location`), the fingertips + `gripperzoffset` above the bottom (below it for a plate). +- `stackablelabwareclasses`: how deep a lid sits on it. +""" + +from typing import Dict, Optional + +from pylabrobot.resources.coordinate import Coordinate +from pylabrobot.resources.lid import Lid +from pylabrobot.resources.plate import Plate +from pylabrobot.resources.utils import create_ordered_items_2d +from pylabrobot.resources.well import CrossSectionType, Well, WellBottomType + +from .biomek_resource import BiomekWell, WellSegment + +_96_WELLPLATE_VB_SEGMENTS = ( + WellSegment(2.0, 2.735, 2.735, 0.0, 0.0), + WellSegment(8.5, 4.0, 4.0, 4.0, 4.0), +) + +_96_WELLPLATE_FLAT_SEGMENTS = (WellSegment(10.668, 3.43, 3.43, 3.175, 3.175),) + +_96_DEEPWELL_SQUARE_SEGMENTS = ( + WellSegment(8.61, 3.85, 3.85, 0.0, 0.0), + WellSegment(33.3, 4.14, 4.14, 4.14, 4.14, round=False), +) + +_24_WELLPLATE_SQUARE_RB_SEGMENTS = ( + WellSegment(8.0, 8.0, 8.0, 0.0, 0.0, cap=True), + WellSegment(32.0, 8.5, 8.5, 8.5, 8.5, round=False), +) + + +def beckman_coulter_biomek_96_wellplate_vb(name: str, with_lid: bool = False) -> Plate: + """Greiner polystyrene microplate with 96 round, V-bottomed wells. Part no. 651XXX. + + Biomek labware class Thermo96VB_PP.""" + lid: Optional[Lid] = None + if with_lid: + # PyLabRobot's lid covers the plate's footprint; Biomek seats it + # (stackablelabwareclasses TiterplateLid: x 0.04, y 0.152, z 0.8 cm) 6.1 mm into the plate. + lid = Lid( + name=f"{name}_lid", + size_x=127.8, + size_y=85.6, + size_z=10.0, # TiterplateLid height 1.0 cm + nesting_z_height=6.1, + model="beckman_coulter_biomek_lid_titerplatelid", + ) + # Biomek's pads: the TiterplateLid's own centre on its seat, gripperzoffset above its bottom. + lid.preferred_pickup_location = Coordinate(63.9, 42.805, 2.0) + plate = Plate( + name=name, + size_x=127.8, # xspan 12.78 cm + size_y=85.6, # yspan 8.56 cm + size_z=14.1, # height 1.41 cm + model=beckman_coulter_biomek_96_wellplate_vb.__name__, + lid=lid, + ordered_items=create_ordered_items_2d( + BiomekWell, + num_items_x=12, + num_items_y=8, + dx=11.31, # well1xoffset 1.44 cm, less half the well + dy=8.31, # the front row; A1 (well1yoffset 1.12 cm) is at the back + dz=3.6, + item_dx=9.0, + item_dy=9.0, + size_x=6.18, + size_y=6.18, + size_z=10.5, # welldepth 1.05 cm + bottom_type=WellBottomType.V, + cross_section_type=CrossSectionType.CIRCLE, + segments=_96_WELLPLATE_VB_SEGMENTS, + max_volume=440.0, # wellvolume + name_prefix=name, + ), + ) + plate.preferred_pickup_location = Coordinate(63.9, 42.8, -2.3) + return plate + + +def beckman_coulter_biomek_96_wellplate_flat(name: str, with_lid: bool = False) -> Plate: + """Beckman Coulter microplate with 96 round, flat-bottomed wells. Part no. 609844. + + Biomek labware class BCFlat96.""" + lid: Optional[Lid] = None + if with_lid: + # PyLabRobot's lid covers the plate's footprint; Biomek seats it + # (stackablelabwareclasses TiterplateLid: x 0.038, y 0.146, z 0.8 cm) 6.224 mm into the plate. + lid = Lid( + name=f"{name}_lid", + size_x=127.762, + size_y=85.471, + size_z=10.0, # TiterplateLid height 1.0 cm + nesting_z_height=6.224, + model="beckman_coulter_biomek_lid_titerplatelid", + ) + # Biomek's pads: the TiterplateLid's own centre on its seat, gripperzoffset above its bottom. + lid.preferred_pickup_location = Coordinate(63.88, 42.736, 2.0) + plate = Plate( + name=name, + size_x=127.762, # xspan 12.7762 cm + size_y=85.471, # yspan 8.5471 cm + size_z=14.224, # height 1.4224 cm + model=beckman_coulter_biomek_96_wellplate_flat.__name__, + lid=lid, + ordered_items=create_ordered_items_2d( + BiomekWell, + num_items_x=12, + num_items_y=8, + dx=10.95, # well1xoffset 1.438 cm, less half the well + dy=7.811, # the front row; A1 (well1yoffset 1.123 cm) is at the back + dz=3.556, + item_dx=9.0, + item_dy=9.0, + size_x=6.86, + size_y=6.86, + size_z=10.668, # welldepth 1.0668 cm + bottom_type=WellBottomType.FLAT, + cross_section_type=CrossSectionType.CIRCLE, + segments=_96_WELLPLATE_FLAT_SEGMENTS, + max_volume=362.76, # wellvolume + name_prefix=name, + ), + ) + plate.preferred_pickup_location = Coordinate(63.881, 42.7355, -2.3) + return plate + + +def beckman_coulter_biomek_96_deepwell_square(name: str) -> Plate: + """Beckman Coulter microplate with 96 deep, square, V-bottomed wells. Part no. 140504. + + Biomek labware class BCDeep96Square.""" + plate = Plate( + name=name, + size_x=128.17, # xspan 12.817 cm + size_y=85.98, # yspan 8.598 cm + size_z=44.2, # height 4.42 cm + model=beckman_coulter_biomek_96_deepwell_square.__name__, + ordered_items=create_ordered_items_2d( + BiomekWell, + num_items_x=12, + num_items_y=8, + dx=10.2364, # well1xoffset 1.43764 cm, less half the well + dy=7.46, # the front row; A1 (well1yoffset 1.138 cm) is at the back + dz=2.29, + item_dx=9.0, + item_dy=9.0, + size_x=8.28, + size_y=8.28, + size_z=41.91, # welldepth 4.191 cm + bottom_type=WellBottomType.V, + cross_section_type=CrossSectionType.RECTANGLE, + segments=_96_DEEPWELL_SQUARE_SEGMENTS, + max_volume=2200.0, # wellvolume + name_prefix=name, + ), + ) + plate.preferred_pickup_location = Coordinate(64.085, 42.99, -2.3) + return plate + + +def beckman_coulter_biomek_24_wellplate_square_rb(name: str, with_lid: bool = False) -> Plate: + """Thomson microplate with 24 square, round-bottomed wells. Part no. 931568. + + Biomek labware class Thomson_24w_Square_RB.""" + lid: Optional[Lid] = None + if with_lid: + # PyLabRobot's lid covers the plate's footprint; Biomek seats it + # (stackablelabwareclasses Thomson_24w_Square_RB_Lid: x 0.0, y 0.0, z 3.4 cm) 10.0 mm into the plate. + lid = Lid( + name=f"{name}_lid", + size_x=127.762, + size_y=85.471, + size_z=10.0, # Thomson_24w_Square_RB_Lid height 1.0 cm + nesting_z_height=10.0, + model="beckman_coulter_biomek_lid_thomson_24w_square_rb_lid", + ) + # Biomek's pads: the Thomson_24w_Square_RB_Lid's own centre on its seat, gripperzoffset above its bottom. + lid.preferred_pickup_location = Coordinate(63.5, 44.196, 8.0) + plate = Plate( + name=name, + size_x=127.762, # xspan 12.7762 cm + size_y=85.471, # yspan 8.5471 cm + size_z=44.0, # height 4.4 cm + model=beckman_coulter_biomek_24_wellplate_square_rb.__name__, + lid=lid, + ordered_items=create_ordered_items_2d( + BiomekWell, + num_items_x=6, + num_items_y=4, + dx=10.5, # well1xoffset 1.9 cm, less half the well + dy=6.971, # the front row; A1 (well1yoffset 1.6 cm) is at the back + dz=4.0, + item_dx=18.0, + item_dy=18.0, + size_x=17.0, + size_y=17.0, + size_z=40.0, # welldepth 4.0 cm + bottom_type=WellBottomType.U, + cross_section_type=CrossSectionType.RECTANGLE, + segments=_24_WELLPLATE_SQUARE_RB_SEGMENTS, + max_volume=10000.0, # wellvolume + name_prefix=name, + ), + ) + plate.preferred_pickup_location = Coordinate(63.881, 42.7355, -2.3) + return plate + + +def beckman_coulter_biomek_reservoir_350cb(name: str, with_lid: bool = False) -> Plate: + """Thermo Nunc reservoir with one flat-bottomed section. + + Biomek labware class ThermoNUNC_350CB: a well per section.""" + lid: Optional[Lid] = None + if with_lid: + # PyLabRobot's lid covers the plate's footprint; Biomek seats it + # (stackablelabwareclasses TiterplateLid: x 0.0, y 0.0, z 3.4 cm) 4.0 mm into the plate. + lid = Lid( + name=f"{name}_lid", + size_x=127.8, + size_y=85.85, + size_z=10.0, # TiterplateLid height 1.0 cm + nesting_z_height=4.0, + model="beckman_coulter_biomek_lid_titerplatelid", + ) + # Biomek's pads: the TiterplateLid's own centre on its seat, gripperzoffset above its bottom. + lid.preferred_pickup_location = Coordinate(63.5, 44.575, 2.0) + wells: Dict[str, Well] = {} + wells["A1"] = BiomekWell( + name=f"{name}_A1", + size_x=123.8, # x1 0.2 to x2 12.58 cm + size_y=81.5, # y1 0.2 to y2 8.35 cm + size_z=37.4, # depth 3.74 cm + segments=(WellSegment(37.4, 61.9, 40.75, 61.9, 40.75, round=False),), + bottom_type=WellBottomType.FLAT, + cross_section_type=CrossSectionType.RECTANGLE, + max_volume=300000.0, # maxvolume + ) + wells["A1"].location = Coordinate(2.0, 2.35, 0.6) + plate = Plate( + name=name, + size_x=127.8, # xspan 12.78 cm + size_y=85.85, # yspan 8.585 cm + size_z=38.0, # height 3.8 cm + model=beckman_coulter_biomek_reservoir_350cb.__name__, + lid=lid, + ordered_items=wells, + ) + plate.preferred_pickup_location = Coordinate(63.9, 42.925, -2.0) + return plate + + +def beckman_coulter_biomek_reservoir(name: str) -> Plate: + """Reservoir used with the Multimek. Part no. 148033. + + Biomek labware class Reservoir: a well per section.""" + wells: Dict[str, Well] = {} + wells["A1"] = BiomekWell( + name=f"{name}_A1", + size_x=111.04, # x1 0.826 to x2 11.93 cm + size_y=72.65, # y1 0.635 to y2 7.9 cm + size_z=14.53, # depth 1.453 cm + segments=(WellSegment(14.53, 55.52, 36.325, 55.52, 36.325, round=False),), + bottom_type=WellBottomType.FLAT, + cross_section_type=CrossSectionType.RECTANGLE, + max_volume=110000.0, # maxvolume + ) + wells["A1"].location = Coordinate(8.26, 3.55, 14.68) + plate = Plate( + name=name, + size_x=127.0, # xspan 12.7 cm + size_y=82.55, # yspan 8.255 cm + size_z=29.21, # height 2.921 cm + model=beckman_coulter_biomek_reservoir.__name__, + ordered_items=wells, + ) + plate.preferred_pickup_location = Coordinate(63.5, 41.275, -2.3) + return plate + + +def beckman_coulter_biomek_modular_reservoir(name: str) -> Plate: + """Beckman Coulter reservoir that may be customized with added sections. Part no. 372795 (Frame); 372790(Quarter); 373792(Quarter Divided by Width); 372788 (Quarter Divided by Length); 372786(Half); 372794(Half Divided by Width). + + Biomek labware class ModularReservoir: a well per section.""" + wells: Dict[str, Well] = {} + wells["A1"] = BiomekWell( + name=f"{name}_A1", + size_x=23.65, # x1 1.105 to x2 3.47 cm + size_y=69.19, # y1 0.772 to y2 7.691 cm + size_z=24.79, # depth 2.479 cm + # a V bottom 1.156 cm deep: no outline + bottom_type=WellBottomType.V, + cross_section_type=CrossSectionType.RECTANGLE, + max_volume=40700.0, # maxvolume + ) + wells["A1"].location = Coordinate(11.05, 8.69, 14.07) + wells["A2"] = BiomekWell( + name=f"{name}_A2", + size_x=23.65, # x1 3.84825 to x2 6.21325 cm + size_y=69.19, # y1 0.772 to y2 7.691 cm + size_z=24.79, # depth 2.479 cm + # a V bottom 1.156 cm deep: no outline + bottom_type=WellBottomType.V, + cross_section_type=CrossSectionType.RECTANGLE, + max_volume=40700.0, # maxvolume + ) + wells["A2"].location = Coordinate(38.4825, 8.69, 14.07) + wells["A3"] = BiomekWell( + name=f"{name}_A3", + size_x=23.65, # x1 6.5915 to x2 8.9565 cm + size_y=69.19, # y1 0.772 to y2 7.691 cm + size_z=24.79, # depth 2.479 cm + # a V bottom 1.156 cm deep: no outline + bottom_type=WellBottomType.V, + cross_section_type=CrossSectionType.RECTANGLE, + max_volume=40700.0, # maxvolume + ) + wells["A3"].location = Coordinate(65.915, 8.69, 14.07) + wells["A4"] = BiomekWell( + name=f"{name}_A4", + size_x=23.65, # x1 9.33475 to x2 11.69975 cm + size_y=69.19, # y1 0.772 to y2 7.691 cm + size_z=24.79, # depth 2.479 cm + # a V bottom 1.156 cm deep: no outline + bottom_type=WellBottomType.V, + cross_section_type=CrossSectionType.RECTANGLE, + max_volume=40700.0, # maxvolume + ) + wells["A4"].location = Coordinate(93.3475, 8.69, 14.07) + plate = Plate( + name=name, + size_x=127.41, # xspan 12.741 cm + size_y=85.6, # yspan 8.56 cm + size_z=38.86, # height 3.886 cm + model=beckman_coulter_biomek_modular_reservoir.__name__, + ordered_items=wells, + ) + plate.preferred_pickup_location = Coordinate(63.705, 42.8, -2.3) + return plate diff --git a/pylabrobot/resources/beckman_coulter/tip_racks.py b/pylabrobot/resources/beckman_coulter/tip_racks.py new file mode 100644 index 00000000000..e00d258fa8c --- /dev/null +++ b/pylabrobot/resources/beckman_coulter/tip_racks.py @@ -0,0 +1,179 @@ +"""Beckman Coulter Biomek tip boxes, from Biomek's labware classes (cm there, mm here). + +- `xspan`, `yspan`, `height`: the box's footprint and height, tips in. +- `wellsx`, `wellsy`, `wellxspacing`, `wellyspacing`: the tip grid. +- `well1xoffset`, `well1yoffset`: tip A1's centre, from the box's left and back edges. +- `wellradius`: the radius of the hole a tip stands in. +- `gripperinfo`: where Biomek's gripper pads go (`preferred_pickup_location`). + +The tips' tops are at the box's `height`, where the head's mandrels meet them, so a tip spot sits +on the top face, as on a nested rack. +""" + +from pylabrobot.resources.coordinate import Coordinate +from pylabrobot.resources.tip_rack import StandingTipRack, TipSpot +from pylabrobot.resources.utils import create_ordered_items_2d + +from .tips import ( + beckman_coulter_biomek_tip_1025uL_filter, + beckman_coulter_biomek_tip_1070uL, + beckman_coulter_biomek_tip_190uL_filter, + beckman_coulter_biomek_tip_230uL, + beckman_coulter_biomek_tip_50uL_filter, +) + + +def beckman_coulter_biomek_96_tiprack_50uL_filter( + name: str, with_tips: bool = True +) -> StandingTipRack: + """Biomek BC50F tip box: 96 T50F tips (`beckman_coulter_biomek_tip_50uL_filter`). Beckman Coulter tip box containing 96 Aerosol Resistant T50 filter tips. Part no. B85888. + + Labware class BC50F.""" + rack = StandingTipRack( + name=name, + size_x=127.9, # xspan 12.79 cm + size_y=85.4, # yspan 8.54 cm + size_z=55.9, # height 5.59 cm + model=beckman_coulter_biomek_96_tiprack_50uL_filter.__name__, + ordered_items=create_ordered_items_2d( + TipSpot, + num_items_x=12, + num_items_y=8, + dx=11.7, # well1xoffset 1.45 cm, less the hole's radius + dy=8.4, # the front row's hole; A1 (well1yoffset 1.12 cm) is at the back + dz=55.9, + item_dx=9.0, + item_dy=9.0, + size_x=5.6, # wellradius 0.28 cm + size_y=5.6, + make_tip=beckman_coulter_biomek_tip_50uL_filter, + name_prefix=name, + ), + with_tips=with_tips, + ) + rack.preferred_pickup_location = Coordinate(63.95, 42.7, -2.3) + return rack + + +def beckman_coulter_biomek_96_tiprack_190uL_filter( + name: str, with_tips: bool = True +) -> StandingTipRack: + """Biomek BC190F tip box: 96 T190F tips (`beckman_coulter_biomek_tip_190uL_filter`). Beckman Coulter tip box containing 96 Aerosol Resistant T190 filter tips. Part no. B85911. + + Labware class BC190F.""" + rack = StandingTipRack( + name=name, + size_x=127.9, # xspan 12.79 cm + size_y=85.4, # yspan 8.54 cm + size_z=55.9, # height 5.59 cm + model=beckman_coulter_biomek_96_tiprack_190uL_filter.__name__, + ordered_items=create_ordered_items_2d( + TipSpot, + num_items_x=12, + num_items_y=8, + dx=11.7, # well1xoffset 1.45 cm, less the hole's radius + dy=8.4, # the front row's hole; A1 (well1yoffset 1.12 cm) is at the back + dz=55.9, + item_dx=9.0, + item_dy=9.0, + size_x=5.6, # wellradius 0.28 cm + size_y=5.6, + make_tip=beckman_coulter_biomek_tip_190uL_filter, + name_prefix=name, + ), + with_tips=with_tips, + ) + rack.preferred_pickup_location = Coordinate(63.95, 42.7, -2.3) + return rack + + +def beckman_coulter_biomek_96_tiprack_230uL(name: str, with_tips: bool = True) -> StandingTipRack: + """Biomek BC230 tip box: 96 T230 tips (`beckman_coulter_biomek_tip_230uL`). Beckman Coulter tip box containing 96 T230 tips. Part no. Sterile: B85906, Non-Sterile: B85903. + + Labware class BC230.""" + rack = StandingTipRack( + name=name, + size_x=127.9, # xspan 12.79 cm + size_y=85.4, # yspan 8.54 cm + size_z=55.9, # height 5.59 cm + model=beckman_coulter_biomek_96_tiprack_230uL.__name__, + ordered_items=create_ordered_items_2d( + TipSpot, + num_items_x=12, + num_items_y=8, + dx=11.7, # well1xoffset 1.45 cm, less the hole's radius + dy=8.4, # the front row's hole; A1 (well1yoffset 1.12 cm) is at the back + dz=55.9, + item_dx=9.0, + item_dy=9.0, + size_x=5.6, # wellradius 0.28 cm + size_y=5.6, + make_tip=beckman_coulter_biomek_tip_230uL, + name_prefix=name, + ), + with_tips=with_tips, + ) + rack.preferred_pickup_location = Coordinate(63.95, 42.7, -2.3) + return rack + + +def beckman_coulter_biomek_96_tiprack_1025uL_filter( + name: str, with_tips: bool = True +) -> StandingTipRack: + """Biomek BC1025F tip box: 96 T1025F tips (`beckman_coulter_biomek_tip_1025uL_filter`). Beckman Coulter tip box containing 96 Aerosol Resistant T1025 filtered tips. Part no. B85955. + + Labware class BC1025F.""" + rack = StandingTipRack( + name=name, + size_x=127.9, # xspan 12.79 cm + size_y=85.4, # yspan 8.54 cm + size_z=114.1, # height 11.41 cm + model=beckman_coulter_biomek_96_tiprack_1025uL_filter.__name__, + ordered_items=create_ordered_items_2d( + TipSpot, + num_items_x=12, + num_items_y=8, + dx=11.6, # well1xoffset 1.44 cm, less the hole's radius + dy=8.4, # the front row's hole; A1 (well1yoffset 1.12 cm) is at the back + dz=114.1, + item_dx=9.0, + item_dy=9.0, + size_x=5.6, # wellradius 0.28 cm + size_y=5.6, + make_tip=beckman_coulter_biomek_tip_1025uL_filter, + name_prefix=name, + ), + with_tips=with_tips, + ) + rack.preferred_pickup_location = Coordinate(63.95, 42.7, -2.3) + return rack + + +def beckman_coulter_biomek_96_tiprack_1070uL(name: str, with_tips: bool = True) -> StandingTipRack: + """Biomek BC1070 tip box: 96 T1070 tips (`beckman_coulter_biomek_tip_1070uL`). Beckman Coulter tip box containing 96 T1070 tips. Part no. Sterile: B85945, Non-Sterile: B85940. + + Labware class BC1070.""" + rack = StandingTipRack( + name=name, + size_x=127.9, # xspan 12.79 cm + size_y=85.4, # yspan 8.54 cm + size_z=114.1, # height 11.41 cm + model=beckman_coulter_biomek_96_tiprack_1070uL.__name__, + ordered_items=create_ordered_items_2d( + TipSpot, + num_items_x=12, + num_items_y=8, + dx=11.6, # well1xoffset 1.44 cm, less the hole's radius + dy=8.4, # the front row's hole; A1 (well1yoffset 1.12 cm) is at the back + dz=114.1, + item_dx=9.0, + item_dy=9.0, + size_x=5.6, # wellradius 0.28 cm + size_y=5.6, + make_tip=beckman_coulter_biomek_tip_1070uL, + name_prefix=name, + ), + with_tips=with_tips, + ) + rack.preferred_pickup_location = Coordinate(63.95, 42.7, -2.3) + return rack diff --git a/pylabrobot/resources/beckman_coulter/tips.py b/pylabrobot/resources/beckman_coulter/tips.py new file mode 100644 index 00000000000..756b870e92c --- /dev/null +++ b/pylabrobot/resources/beckman_coulter/tips.py @@ -0,0 +1,96 @@ +"""Beckman Coulter Biomek tips, from Biomek's tip classes (lengths in cm there, mm here). + +- `tipheight`: the tip's length; `capacity`: its volume in uL; `filtered`: a filter tip. +- `spanseatingdepth`: how far a mandrel goes into the tip. +- `maxtipradius`: the tip's radius where it seats on the mandrel. +- `mintipradius`, `coniclength`: its radius at the end, and the length over which it widens from + there to `maxtipradius` (the cone). +- `lls`: whether the tip is conductive, for liquid-level sensing. +""" + +from .biomek_resource import BiomekTip + + +def beckman_coulter_biomek_tip_50uL_filter(name: str) -> BiomekTip: + """Biomek T50F tip, 50 uL, filter: tip class T50F.""" + return BiomekTip( + name=name, + model=beckman_coulter_biomek_tip_50uL_filter.__name__, + diameter=5.182, # maxtipradius 0.2591 cm + size_z=51.359, # tipheight 5.1359 cm + has_filter=True, + maximal_volume=50.0, # capacity + nominal_volume=50.0, + fitting_depth=7.75, # spanseatingdepth 0.775 cm + end_diameter=0.812, # mintipradius 0.0406 cm + cone_length=38.227, # coniclength 3.8227 cm + is_conductive=False, # lls + ) + + +def beckman_coulter_biomek_tip_190uL_filter(name: str) -> BiomekTip: + """Biomek T190F tip, 190 uL, filter: tip class T190F.""" + return BiomekTip( + name=name, + model=beckman_coulter_biomek_tip_190uL_filter.__name__, + diameter=4.826, # maxtipradius 0.2413 cm + size_z=51.435, # tipheight 5.1435 cm + has_filter=True, + maximal_volume=190.0, # capacity + nominal_volume=190.0, + fitting_depth=7.75, # spanseatingdepth 0.775 cm + end_diameter=1.27, # mintipradius 0.0635 cm + cone_length=28.194, # coniclength 2.8194 cm + is_conductive=False, # lls + ) + + +def beckman_coulter_biomek_tip_230uL(name: str) -> BiomekTip: + """Biomek T230 tip, 230 uL, no filter: tip class T230.""" + return BiomekTip( + name=name, + model=beckman_coulter_biomek_tip_230uL.__name__, + diameter=4.826, # maxtipradius 0.2413 cm + size_z=51.435, # tipheight 5.1435 cm + has_filter=False, + maximal_volume=230.0, # capacity + nominal_volume=230.0, + fitting_depth=7.75, # spanseatingdepth 0.775 cm + end_diameter=1.27, # mintipradius 0.0635 cm + cone_length=28.194, # coniclength 2.8194 cm + is_conductive=False, # lls + ) + + +def beckman_coulter_biomek_tip_1025uL_filter(name: str) -> BiomekTip: + """Biomek T1025F tip, 1025 uL, filter: tip class T1025F.""" + return BiomekTip( + name=name, + model=beckman_coulter_biomek_tip_1025uL_filter.__name__, + diameter=4.826, # maxtipradius 0.2413 cm + size_z=109.855, # tipheight 10.9855 cm + has_filter=True, + maximal_volume=1025.0, # capacity + nominal_volume=1025.0, + fitting_depth=7.75, # spanseatingdepth 0.775 cm + end_diameter=1.27, # mintipradius 0.0635 cm + cone_length=19.8374, # coniclength 1.98374 cm + is_conductive=False, # lls + ) + + +def beckman_coulter_biomek_tip_1070uL(name: str) -> BiomekTip: + """Biomek T1070 tip, 1070 uL, no filter: tip class T1070.""" + return BiomekTip( + name=name, + model=beckman_coulter_biomek_tip_1070uL.__name__, + diameter=4.826, # maxtipradius 0.2413 cm + size_z=109.855, # tipheight 10.9855 cm + has_filter=False, + maximal_volume=1070.0, # capacity + nominal_volume=1070.0, + fitting_depth=7.75, # spanseatingdepth 0.775 cm + end_diameter=1.27, # mintipradius 0.0635 cm + cone_length=19.8374, # coniclength 1.98374 cm + is_conductive=False, # lls + ) From 89cfcf035a8aa54585ecc126d07751cd8c23f755 Mon Sep 17 00:00:00 2001 From: Cody Moore <46687103+cmoscy@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:55:54 +0000 Subject: [PATCH 03/11] `resources`: sort Beckman Coulter import blocks for ruff I001 --- .../resources/beckman_coulter/beckman_coulter_tests.py | 2 +- pylabrobot/resources/beckman_coulter/tip_racks.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pylabrobot/resources/beckman_coulter/beckman_coulter_tests.py b/pylabrobot/resources/beckman_coulter/beckman_coulter_tests.py index 72932f1c839..9d267dddfc9 100644 --- a/pylabrobot/resources/beckman_coulter/beckman_coulter_tests.py +++ b/pylabrobot/resources/beckman_coulter/beckman_coulter_tests.py @@ -6,8 +6,8 @@ from pylabrobot.resources import ( BiomekTip, - Plate, BiomekWell, + Plate, Resource, WellSegment, beckman_coulter_biomek_24_wellplate_square_rb, diff --git a/pylabrobot/resources/beckman_coulter/tip_racks.py b/pylabrobot/resources/beckman_coulter/tip_racks.py index e00d258fa8c..1e8ef072f54 100644 --- a/pylabrobot/resources/beckman_coulter/tip_racks.py +++ b/pylabrobot/resources/beckman_coulter/tip_racks.py @@ -15,11 +15,11 @@ from pylabrobot.resources.utils import create_ordered_items_2d from .tips import ( - beckman_coulter_biomek_tip_1025uL_filter, - beckman_coulter_biomek_tip_1070uL, + beckman_coulter_biomek_tip_50uL_filter, beckman_coulter_biomek_tip_190uL_filter, beckman_coulter_biomek_tip_230uL, - beckman_coulter_biomek_tip_50uL_filter, + beckman_coulter_biomek_tip_1025uL_filter, + beckman_coulter_biomek_tip_1070uL, ) From 3083c2e42cac3a903894112805884d59fcbbbf04 Mon Sep 17 00:00:00 2001 From: cmoscy <46687103+cmoscy@users.noreply.github.com> Date: Thu, 12 Nov 2026 00:57:51 -0800 Subject: [PATCH 04/11] `resources`: a tip mounting shaft's state is the tip it carries `TipMountingShaft.serialize_state` holds the tool the shaft carries (as it serializes; None for none), as a tip spot's state holds its tip, and `load_state` puts it back: the saved tip goes onto the shaft (a tool of the same name held elsewhere in the tree gives way first), and a saved None takes off the one it carries. State saved before shafts had any leaves the shaft as it is. With it, `save_state_to_file` / `load_state_from_file` keep the tips a head carries across sessions, which a device that cannot sense its tips needs. Tests: a carried tip saved and read back, its own state after it; None taking a tip off; the same tip staying; a tip of that name held elsewhere giving way. --- pylabrobot/resources/n_channel_pipettes.py | 27 +++++++++- .../resources/n_channel_pipettes_tests.py | 49 +++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) diff --git a/pylabrobot/resources/n_channel_pipettes.py b/pylabrobot/resources/n_channel_pipettes.py index 6e3fe04725c..72b6762fafe 100644 --- a/pylabrobot/resources/n_channel_pipettes.py +++ b/pylabrobot/resources/n_channel_pipettes.py @@ -4,7 +4,7 @@ from typing import Any, Dict, List, Literal, Mapping, Optional, cast, get_args from pylabrobot.resources.coordinate import Coordinate -from pylabrobot.resources.head_tool import HeadTool, move_tool +from pylabrobot.resources.head_tool import HeadTool, move_tool, release_named_tool from pylabrobot.resources.itemized_resource import ItemizedResource from pylabrobot.resources.resource import Resource from pylabrobot.resources.well import CrossSectionType @@ -145,6 +145,31 @@ def tip_bottom(self) -> Optional[Coordinate]: return None return Coordinate(0.0, 0.0, cast(Coordinate, tip.location).z) + def serialize_state(self) -> Dict[str, Any]: + """This shaft's state: the tool it carries (`tip`, as it serializes; None for none), as a tip + spot's state holds its tip. A device that cannot sense its tips reads them back from it.""" + tip = self.tip + return {**super().serialize_state(), "tip": None if tip is None else tip.serialize()} + + def load_state(self, state: Dict[str, Any]) -> None: + """Load this shaft's state: the saved `tip` goes onto it (a tool of the same name held + elsewhere in the same tree gives way first); a saved None takes off the one it carries. State + saved before shafts had any leaves it as it is.""" + super().load_state(state) + if "tip" not in state: + return + saved, current = state["tip"], self.tip + if current is not None and saved is not None and current.serialize() == saved: + return + if current is not None: + self.release_tip() + if saved is None: + return + release_named_tool(self.get_root(), saved["name"]) + tip = Resource.deserialize(saved) + assert isinstance(tip, HeadTool) + self.mount_tip(tip) + def serialize(self) -> dict: """What its size does not say: how it holds a tip, and that it is round rather than a box.""" return { diff --git a/pylabrobot/resources/n_channel_pipettes_tests.py b/pylabrobot/resources/n_channel_pipettes_tests.py index 319a5211e0f..212d0f79873 100644 --- a/pylabrobot/resources/n_channel_pipettes_tests.py +++ b/pylabrobot/resources/n_channel_pipettes_tests.py @@ -18,6 +18,55 @@ def test_a_shaft_is_round(self): TipMountingShaft(name="shaft", tip_pickup_mode="core", cross_section_type="rectangle") +class ShaftSavesItsTip(unittest.TestCase): + """A shaft's state is the tool it carries, so a device that cannot sense its tips reads them back.""" + + def setUp(self): + self.shaft = TipMountingShaft(name="shaft", tip_pickup_mode="core") + + def test_a_carried_tip_is_saved_and_read_back(self): + tip = hamilton_tip_300uL(name="tip") + self.shaft.mount_tip(tip) + tip.tracker.set_volume(120) + state = self.shaft.serialize_all_state() + self.assertEqual(state["shaft"]["tip"], tip.serialize()) + + other = TipMountingShaft(name="shaft", tip_pickup_mode="core") + other.load_all_state(state) + self.assertTrue(other.has_tip()) + assert other.tip is not None + self.assertEqual(other.tip.serialize(), tip.serialize()) + self.assertEqual(other.tip.location, tip.location) + self.assertEqual(other.tip.tracker.get_used_volume(), 120) # the tip's own state, after it + + def test_none_saved_takes_the_tip_off(self): + empty = self.shaft.serialize_all_state() + self.assertIsNone(empty["shaft"]["tip"]) + self.shaft.mount_tip(hamilton_tip_300uL(name="tip")) + self.shaft.load_all_state(empty) + self.assertFalse(self.shaft.has_tip()) + + def test_the_same_tip_stays_and_older_state_leaves_it(self): + tip = hamilton_tip_300uL(name="tip") + self.shaft.mount_tip(tip) + self.shaft.load_state(self.shaft.serialize_state()) + self.assertIs(self.shaft.tip, tip) + self.shaft.load_state({}) + self.assertIs(self.shaft.tip, tip) + + def test_a_tip_of_that_name_held_elsewhere_gives_way(self): + root = Resource("root", size_x=100, size_y=100, size_z=10) + first = TipMountingShaft(name="first", tip_pickup_mode="core") + second = TipMountingShaft(name="second", tip_pickup_mode="core") + root.assign_child_resource(first, location=Coordinate.zero()) + root.assign_child_resource(second, location=Coordinate(20, 0, 0)) + first.mount_tip(hamilton_tip_300uL(name="tip")) + saved = first.serialize_state() + second.load_state(saved) + self.assertTrue(second.has_tip()) + self.assertFalse(first.has_tip()) + + class ShaftHoldsItsTip(unittest.TestCase): """A mounting shaft carries its tip as a child, gripping it by the fitting depth.""" From 86ff6e49ad2a73582c5bfec05086946c47c04d0c Mon Sep 17 00:00:00 2001 From: Cody Moore <46687103+cmoscy@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:56:17 +0000 Subject: [PATCH 05/11] `resources`: narrow restored tip to Tip before reading its tracker --- pylabrobot/resources/n_channel_pipettes_tests.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pylabrobot/resources/n_channel_pipettes_tests.py b/pylabrobot/resources/n_channel_pipettes_tests.py index 212d0f79873..394256531d5 100644 --- a/pylabrobot/resources/n_channel_pipettes_tests.py +++ b/pylabrobot/resources/n_channel_pipettes_tests.py @@ -4,6 +4,7 @@ from pylabrobot.resources.hamilton import hamilton_core_gripper_tool, hamilton_tip_300uL from pylabrobot.resources.n_channel_pipettes import TipMountingShaft from pylabrobot.resources.resource import Resource +from pylabrobot.resources.tip import Tip class TestTipMountingShaft(unittest.TestCase): @@ -35,6 +36,7 @@ def test_a_carried_tip_is_saved_and_read_back(self): other.load_all_state(state) self.assertTrue(other.has_tip()) assert other.tip is not None + assert isinstance(other.tip, Tip) self.assertEqual(other.tip.serialize(), tip.serialize()) self.assertEqual(other.tip.location, tip.location) self.assertEqual(other.tip.tracker.get_used_volume(), 120) # the tip's own state, after it From 766ca414930632e9577562807894b3a2f2e94794 Mon Sep 17 00:00:00 2001 From: cmoscy <46687103+cmoscy@users.noreply.github.com> Date: Tue, 10 Nov 2026 23:51:17 -0800 Subject: [PATCH 06/11] `Biomek i7`: ACE boards over USB: framing, messages and read-only discovery The first part of a Beckman Coulter Biomek i7 driver that talks to the instrument's ACE boards directly over USB (0AB5:ACE0), one board per module: the chassis and one per pod. - `driver/framing.py`, `board.py`: length-prefixed frames packed into interrupt transfers; a board's replies matched to their requests by header, two-stage replies (ACCEPTED, DONE), unsolicited messages to subscribers. - `driver/protocol.py`, `errors.py`: every request the Master Controller was logged sending, plus three reads, and nothing else; each field layout as Biomek's `ace_io` log (Log.db3) decodes it. - `driver/master.py`, `features/chassis.py`, `features/pod.py`, `module.py`: discovery places each board by what it reports (Get Module ID: type and side), not by USB order or serial number, then reads each module's serial number, its boards with their application images and versions, and the names of its inputs, in the order of the Master Controller's cold start. It writes nothing to the boards. Unknown types or sides, two boards in one place, and no chassis are refused. - `driver/simulator.py`, `defaults/`: boards replayed from a cold-start recording; a generic one ships, every serial number replaced by a placeholder. Tests: one exact frame per command (from Biomek's `ace_io` log; three reads it never logged from their layout), build and parse round trips, framing inverses, the replay's rules, and discovery on the generic recording. Discovery sends the same requests as on the full driver this series comes from. --- pylabrobot/beckman_coulter/__init__.py | 1 + .../beckman_coulter/biomek_i7/__init__.py | 1 + .../biomek_i7/defaults/__init__.py | 13 + .../defaults/biomek_i7_generic_coldstart.json | 3004 +++++++++++++++++ .../beckman_coulter/biomek_i7/design.md | 28 + .../biomek_i7/driver/__init__.py | 1 + .../beckman_coulter/biomek_i7/driver/board.py | 292 ++ .../biomek_i7/driver/board_tests.py | 183 + .../biomek_i7/driver/configuration.py | 70 + .../biomek_i7/driver/errors.py | 141 + .../biomek_i7/driver/errors_tests.py | 41 + .../biomek_i7/driver/features/__init__.py | 1 + .../biomek_i7/driver/features/chassis.py | 67 + .../biomek_i7/driver/features/pod.py | 77 + .../biomek_i7/driver/framing.py | 100 + .../biomek_i7/driver/framing_tests.py | 118 + .../biomek_i7/driver/master.py | 225 ++ .../biomek_i7/driver/master_tests.py | 218 ++ .../biomek_i7/driver/module.py | 72 + .../biomek_i7/driver/protocol.py | 711 ++++ .../biomek_i7/driver/protocol_tests.py | 566 ++++ .../biomek_i7/driver/simulator.py | 103 + .../biomek_i7/driver/simulator_tests.py | 80 + .../biomek_i7/simulation_tests_support.py | 47 + 24 files changed, 6160 insertions(+) create mode 100644 pylabrobot/beckman_coulter/__init__.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/__init__.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/defaults/__init__.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/defaults/biomek_i7_generic_coldstart.json create mode 100644 pylabrobot/beckman_coulter/biomek_i7/design.md create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/__init__.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/board.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/board_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/errors.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/errors_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/features/__init__.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/features/chassis.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/framing.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/framing_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/master.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/master_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/module.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/protocol.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/protocol_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/simulator.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/simulator_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py diff --git a/pylabrobot/beckman_coulter/__init__.py b/pylabrobot/beckman_coulter/__init__.py new file mode 100644 index 00000000000..e113ad03137 --- /dev/null +++ b/pylabrobot/beckman_coulter/__init__.py @@ -0,0 +1 @@ +"""Beckman Coulter devices.""" diff --git a/pylabrobot/beckman_coulter/biomek_i7/__init__.py b/pylabrobot/beckman_coulter/biomek_i7/__init__.py new file mode 100644 index 00000000000..421a55e4014 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/__init__.py @@ -0,0 +1 @@ +"""Beckman Coulter Biomek i7, driven over USB through its ACE boards.""" diff --git a/pylabrobot/beckman_coulter/biomek_i7/defaults/__init__.py b/pylabrobot/beckman_coulter/biomek_i7/defaults/__init__.py new file mode 100644 index 00000000000..b7118bd6e87 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/defaults/__init__.py @@ -0,0 +1,13 @@ +"""A generic Biomek i7's cold start: what a simulated instrument answers when given no instrument's +own recording. + +Made from one instrument's cold-start recording (the requests the Master Controller sent at a +start and the boards' replies), with every serial number replaced by a placeholder of the same +length. +""" + +from pathlib import Path + +HERE = Path(__file__).parent + +GENERIC_RECORDING = HERE / "biomek_i7_generic_coldstart.json" diff --git a/pylabrobot/beckman_coulter/biomek_i7/defaults/biomek_i7_generic_coldstart.json b/pylabrobot/beckman_coulter/biomek_i7/defaults/biomek_i7_generic_coldstart.json new file mode 100644 index 00000000000..32739c1cac9 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/defaults/biomek_i7_generic_coldstart.json @@ -0,0 +1,3004 @@ +{ + "source": "the cold start of one Biomek i7, serial numbers replaced", + "boards": { + "chassis": [ + [ + "00000000", + [ + "000000010002008000" + ] + ], + [ + "00000003", + [ + "000000020302000200" + ] + ], + [ + "00000002", + [ + "0000000302020053494d554c415445443030313030303030303030303030303030303030303030" + ] + ], + [ + "00000012", + [ + "0000000412020078DB2D6D" + ] + ], + [ + "00000011", + [ + "00000005110200C4100400" + ] + ], + [ + "00000008", + [ + "000000060802000101000201002D0100" + ] + ], + [ + "02010003", + [ + "02010007030200E500" + ] + ], + [ + "02010010", + [ + "02010008100200302E322E34" + ] + ], + [ + "20000008", + [ + "2000000A080200210100220900280100" + ] + ], + [ + "22090001", + [ + "2209000B01020054656D7065726174757265" + ] + ], + [ + "22090012", + [ + "2209000C1202006465672E2043" + ] + ], + [ + "22080001", + [ + "2208000D010200416972205072657373757265" + ] + ], + [ + "22080012", + [ + "2208000E1202006B5061" + ] + ], + [ + "22070001", + [ + "2207000F01020048756D6964697479" + ] + ], + [ + "22070012", + [ + "2207001012020025205248" + ] + ], + [ + "22060001", + [ + "220600110102004C69676874204375727461696E20526567756C61746F72" + ] + ], + [ + "22060012", + [ + "2206001212020056" + ] + ], + [ + "22050001", + [ + "220500130102002B33365620496E7465726C6F636B6564" + ] + ], + [ + "22050012", + [ + "2205001412020056" + ] + ], + [ + "22040001", + [ + "220400150102002B333656205377697463686564" + ] + ], + [ + "22040012", + [ + "2204001612020056" + ] + ], + [ + "22030001", + [ + "220300170102002B323456205377697463686564" + ] + ], + [ + "22030012", + [ + "2203001812020056" + ] + ], + [ + "22020001", + [ + "220200190102002B333656" + ] + ], + [ + "22020012", + [ + "2202001A12020056" + ] + ], + [ + "22010001", + [ + "2201001B0102002B35562056427573" + ] + ], + [ + "22010012", + [ + "2201001C12020056" + ] + ], + [ + "21010001", + [ + "2101001E010200446F6F722053656E736F72" + ] + ], + [ + "2101001101", + [ + "2101001F110200" + ] + ], + [ + "21010010", + [ + "2101002010020001" + ] + ], + [ + "28010001", + [ + "280100220102004465636B204C69676874" + ] + ], + [ + "2801001101", + [ + "28010023110200" + ] + ], + [ + "28010010", + [ + "2801002410020000" + ] + ], + [ + "22010010", + [ + "22010025100200F173A540" + ] + ], + [ + "fe000018", + [ + "FE00002618020001000600" + ] + ], + [ + "01010050", + [ + "01010027500200" + ] + ], + [ + "0101001101", + [ + "01010028110200" + ] + ], + [ + "2d01001002", + [ + "2D010029100200" + ] + ], + [ + "ff0100100201", + [ + "FF01002A1002000101" + ] + ], + [ + "01010051", + [ + "0101002B51020000" + ] + ], + [ + "2d01001003", + [ + "2D01002C100200" + ] + ], + [ + "ff01001001790001", + [ + "FF01002F10020001790000" + ] + ], + [ + "ff01001001790000", + [ + "FF01003110020001790000" + ] + ], + [ + "ff010010019300", + [ + "FF010032100200019300" + ] + ], + [ + "22020010", + [ + "220200371002005E050F42" + ] + ], + [ + "22030010", + [ + "220300381002007470BF41" + ] + ], + [ + "22040010", + [ + "22040039100200884D0D42" + ] + ], + [ + "22050010", + [ + "2205003A100200A10E0E42" + ] + ], + [ + "22060010", + [ + "2206003B1002001854AF41" + ] + ], + [ + "22070010", + [ + "2207003C1002000B2B1642" + ] + ], + [ + "22080010", + [ + "2208003D100200EDFBDB42" + ] + ], + [ + "22090010", + [ + "2209003E100200C0F4BB41" + ] + ] + ], + "multichannel": [ + [ + "00000000", + [ + "00000001000200FD01" + ] + ], + [ + "00000003", + [ + "000000020302000100" + ] + ], + [ + "00000002", + [ + "0000000302020053494d554c415445443030323030303030303030303030303030303030303030" + ] + ], + [ + "00000012", + [ + "0000000412020078DB2D6D" + ] + ], + [ + "00000011", + [ + "00000005110200C4100400" + ] + ], + [ + "00000008", + [ + "00000006080200010100020700" + ] + ], + [ + "02070003", + [ + "02070007030200E300" + ] + ], + [ + "02070010", + [ + "02070009100200322E322E33" + ] + ], + [ + "02060003", + [ + "0206000A0302000001" + ] + ], + [ + "02060002", + [ + "0206000b02020053494d554c415445443030333030303030303030303030303030303030303030" + ] + ], + [ + "02060012", + [ + "0206000C12020078DB2D6D" + ] + ], + [ + "02060011", + [ + "0206000D110200C4100400" + ] + ], + [ + "02050003", + [ + "0205000E0302000001" + ] + ], + [ + "02050002", + [ + "0205000f02020053494d554c415445443030343030303030303030303030303030303030303030" + ] + ], + [ + "02050012", + [ + "0205001012020078DB2D6D" + ] + ], + [ + "02050011", + [ + "02050011110200C4100400" + ] + ], + [ + "02040003", + [ + "020400120302000001" + ] + ], + [ + "02040002", + [ + "0204001302020053494d554c415445443030353030303030303030303030303030303030303030" + ] + ], + [ + "02040012", + [ + "0204001412020078DB2D6D" + ] + ], + [ + "02040011", + [ + "02040015110200C4100400" + ] + ], + [ + "02030003", + [ + "020300160302000001" + ] + ], + [ + "02030002", + [ + "0203001702020053494d554c415445443030363030303030303030303030303030303030303030" + ] + ], + [ + "02030012", + [ + "0203001812020078DB2D6D" + ] + ], + [ + "02030011", + [ + "02030019110200C4100400" + ] + ], + [ + "02020003", + [ + "0202001A0302000001" + ] + ], + [ + "02020002", + [ + "0202001b02020053494d554c415445443030373030303030303030303030303030303030303030" + ] + ], + [ + "02020012", + [ + "0202001C12020078DB2D6D" + ] + ], + [ + "02020011", + [ + "0202001D110200C4100400" + ] + ], + [ + "02010003", + [ + "0201001E0302000001" + ] + ], + [ + "02010002", + [ + "0201001f02020053494d554c415445443030383030303030303030303030303030303030303030" + ] + ], + [ + "02010012", + [ + "0201002012020078DB2D6D" + ] + ], + [ + "02010011", + [ + "02010021110200C4100400" + ] + ], + [ + "20000008", + [ + "20000023080200220400" + ] + ], + [ + "22040001", + [ + "220400240102002B33365620496E7465726C6F636B" + ] + ], + [ + "22040012", + [ + "2204002512020056" + ] + ], + [ + "22030001", + [ + "220300260102002B355620555342" + ] + ], + [ + "22030012", + [ + "2203002712020056" + ] + ], + [ + "22020001", + [ + "220200280102002B333656" + ] + ], + [ + "22020012", + [ + "2202002912020056" + ] + ], + [ + "22010001", + [ + "2201002A0102002B35562056427573" + ] + ], + [ + "22010012", + [ + "2201002B12020056" + ] + ], + [ + "22010010", + [ + "2201002E1002004DC8A440" + ] + ], + [ + "02070004", + [ + "02070031040200312E302E30" + ] + ], + [ + "af0100f7", + [ + "AF010032F70200280FBB405DDC7740E2A38A40" + ] + ], + [ + "110100100001000000807d02000100000000fc0300010000000088130000000000005a050003000300320000605b0300c8000000002d3101b80b0000000200000180ff800c0000b80b307532000000803801000a0000b80b000050000000000000fb1027000010270000000000000000000060ea000000000000800100000000f401a00f00000000000000ffffffff0a0064000000000000002f440000803f000000000000905f0100c94eaa3acea074395d1feb330000000000000000141b000014000000b1010000ea100000401f000000000000f4010000102700000f0000000000000000000000000000000000020000002c01000032000000", + [ + "11010033100200" + ] + ], + [ + "11020010000100000000ee02000100000000b0040001000000001027000000000000e80300030003003200000071020064000000c0e1e400d007000000020000018000800c0000b80b307532000000803801000a0000b004000050000000000000fb1027000010270000000000000000000060ea000000000000800100000000f401a00f00000000000000ffffffff0a0064000000000000002f440000803f000000000000905f0100c94eaa3acea074395d1feb330000000000000000141b000014000000b1010000ea100000401f000000000000f4010000102700000f0000000000000000000000000000000000020000002c01000032000000", + [ + "11020034100200" + ] + ], + [ + "110300100001000000005f00000100000000f401000100000000aa0a000018fcff0000000003000300140000a0860100e803000040420f00e80300008000000008800034080000800c0852d007000000000000010000f401000050000000000000fa1027000010270000c8000000000000003075000018fcffff800100000000e803881300000000000080ffffffff0a006400000000000000000000000000000000000000000000000000000000000000000000000000000050c3000000000000000000000000000000000000000000000000000000000000000000000fd007410000000000000002000000000000000000000000000000000000", + [ + "11030035100200" + ] + ], + [ + "110400100001000000000003000100000000c01200000000000000000000000000801a06000300000050000050c300006400000000000000c8000000b80b00000d00ff480d0000f00a3075b4000000000000000a0000c012000040010000000000fb10270000401f00000000000000000000a8610000a8a80000000000000000f401dc0500000000000080ffffffff0a00102700000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000000000000000000000000000000000", + [ + "11040036100200" + ] + ], + [ + "110500100001000000030f01000100000029830100010000009b1f0f000000000052060300030003f23d0000400d0300e80300000048e80194110000f30100000d0000b0040000dc05640018010000000000000a00298301006f4d000000000000fb10270000d6060a000000000000000000983a000000000000c60000000000f401a00f00000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000000000000000000000000000000000", + [ + "11050037100200" + ] + ], + [ + "1106001000010000001966010001000000f9f91b0001000000bac317010000000002f00200030003b735000050c30000e803000080841e00d0070000e10300000d0000bc020000dc056400fa000000e02e00000a00f9f91b001966010000000000fb4c1d000020030a000000000000000000a861000000000000290700000000f401d00700000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000d4feffff3705000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000dc0500000000000000000000000000000000", + [ + "11060038100200" + ] + ], + [ + "11070010000a000000415d0000bc02000030b301000000000000000000d03effff00000000010003380600000000000000000000000000000000000000000000090000b80b0000dc05e8030000000000000000000030b30100161f000000000000fc1027000088130a000000000000000000c8af0000000000003e0158020000640000000000e803fa0000ffffffff0a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000000000000000000000000000000000", + [ + "11070039100200" + ] + ], + [ + "110800100001000000ebb8010001000000b9bd050001000000e5f61600c396c6ff000000000300039475000020a107006400000080841e00f40100004b0000000d0000bc020000dc05640004010000b03600000200b9bd050075dc000000000000fa4c1d000020030a000000000000000000983a000000000000f00200000000f401c40900000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000dc0500000000000000000000000000000000", + [ + "1108003A100200" + ] + ], + [ + "0000000f", + [ + "0000003B0F0200" + ] + ], + [ + "11010021", + [ + "1101003C21020001" + ] + ], + [ + "1103001200", + [ + "1103003D120200" + ] + ], + [ + "1000000f", + [ + "1000003E0F0200" + ] + ], + [ + "1107001200", + [ + "1107003F120200" + ] + ], + [ + "1108001200", + [ + "11080040120200" + ] + ], + [ + "1105001200", + [ + "11050041120200" + ] + ], + [ + "1106001200", + [ + "11060042120200" + ] + ], + [ + "1104001200", + [ + "11040044120200" + ] + ], + [ + "1101001200", + [ + "11010045120200" + ] + ], + [ + "1102001200", + [ + "11020046120200" + ] + ], + [ + "11070024", + [ + "110700472402005EFFFFFF" + ] + ], + [ + "11080024", + [ + "11080048240200B352FDFF" + ] + ], + [ + "11050024", + [ + "1105004924020009F90000" + ] + ], + [ + "11060024", + [ + "1106004A24020000000000" + ] + ], + [ + "11030024", + [ + "1103004B24020001FFFFFF" + ] + ], + [ + "11040024", + [ + "1104004C24020090A80000" + ] + ], + [ + "11010024", + [ + "1101004D240200E28B0000" + ] + ], + [ + "11020024", + [ + "1102004E2402008D910000" + ] + ], + [ + "11030040005f000000f4010000aa0a000000000018fcffff0000", + [ + "11030072400032" + ] + ], + [ + "11030051", + [ + "11030073510100", + "11030073510200" + ] + ], + [ + "11070040415d000030b301000000000000000000000000000000", + [ + "11070075400032" + ] + ], + [ + "11070051", + [ + "11070079510100", + "11070079510200" + ] + ], + [ + "1106004019660100f9f91b00bac3170100000000000000000000", + [ + "1106007B400032" + ] + ], + [ + "11060051", + [ + "1106007C510100", + "1106007C510200" + ] + ], + [ + "1106004019660100f9f91b00bac3170100000000a98b00000000", + [ + "1106007E400200" + ] + ], + [ + "1106005030750000", + [ + "1106007F500100", + "1106007F500200" + ] + ], + [ + "11080040ebb80100b9bd0500e5f6160000000000000000000000", + [ + "11080081400032" + ] + ], + [ + "11080051", + [ + "11080082510100", + "11080082510200" + ] + ], + [ + "22020010", + [ + "22020083100200491C1042" + ] + ], + [ + "11080040ebb80100b9bd0500e5f61600000000009bc1fcff0000", + [ + "11080085400200" + ] + ], + [ + "1108005030750000", + [ + "11080086500100", + "11080086500200" + ] + ], + [ + "11080040ebb80100b9bd0500e5f61600000000009454fdff0000", + [ + "11080088400200" + ] + ], + [ + "11050040030f0100298301009b1f0f0000000000000000000000", + [ + "1105008B400032" + ] + ], + [ + "11050051", + [ + "1105008C510100", + "1105008C510200" + ] + ], + [ + "22030010", + [ + "2203008D1002007A9EA740" + ] + ], + [ + "1107005030750000", + [ + "11070090500100", + "11070090500200" + ] + ], + [ + "11050040030f0100298301009b1f0f0000000000d6b900000000", + [ + "11050093400200" + ] + ], + [ + "1105005030750000", + [ + "11050094500100", + "11050094500200" + ] + ], + [ + "1102004000ee020000b004000010270000000000000000000000", + [ + "11020096400032" + ] + ], + [ + "11020051", + [ + "11020097510100", + "11020097510200" + ] + ], + [ + "1102005030750000", + [ + "1102009A500100", + "1102009A500200" + ] + ], + [ + "11080040ebb80100b9bd0500e5f6160000000000dbd8fdff0000", + [ + "1108009C400200" + ] + ], + [ + "11010040807d020000fc03000088130000000000000000000000", + [ + "1101009F400032" + ] + ], + [ + "11010051", + [ + "110100A0510100", + "110100A0510200" + ] + ], + [ + "22040010", + [ + "220400A110020033BD1042" + ] + ], + [ + "11010040807d020000fc03000088130000000000008c00000000", + [ + "110100A3400200" + ] + ], + [ + "1101005030750000", + [ + "110100A4500100", + "110100A4500200" + ] + ], + [ + "110400400000030000c012000000000000000000a8a800000000", + [ + "110400A6400032" + ] + ], + [ + "11040051", + [ + "110400A7510100", + "110400A7510200" + ] + ], + [ + "11030040005f000000f4010000aa0a000000000000fbffff0000", + [ + "110300F7400200" + ] + ], + [ + "1000005073140000", + [ + "100000F8500100", + "100000F8500200" + ] + ], + [ + "11080040a925000037c60000403a0400000000006cd8fdff0000", + [ + "11080002400200" + ] + ], + [ + "11080040ebb80100b9bd0500e5f6160000000000ad52fdff0000", + [ + "1108000D400200" + ] + ], + [ + "1103004095090000f01f0000bf7f00000000000000ffffff0000", + [ + "1103000E400200" + ] + ], + [ + "100000500c170000", + [ + "1000000F500100", + "1000000F500200" + ] + ], + [ + "11010040150000001f0000003201000000000000038c00000000", + [ + "11010018400200" + ] + ], + [ + "11050040030f0100298301009b1f0f000000000013f900000000", + [ + "11050019400200" + ] + ], + [ + "11020040b86f0200077b030044ce2200000000008a9100000000", + [ + "1102001A400200" + ] + ], + [ + "100000501b170000", + [ + "1000001B500100", + "1000001B500200" + ] + ], + [ + "11070040415d000030b30100000000000000000061ffffff0000", + [ + "11070024400200" + ] + ], + [ + "10000050d4130000", + [ + "10000025500100", + "10000025500200" + ] + ], + [ + "1106004019660100f9f91b00bac3170100000000a78800000000", + [ + "11060026400200" + ] + ], + [ + "10000050f7130000", + [ + "10000027500100", + "10000027500200" + ] + ] + ], + "span8": [ + [ + "00000000", + [ + "00000001000200FB02" + ] + ], + [ + "00000003", + [ + "000000020302000100" + ] + ], + [ + "00000002", + [ + "0000000302020053494d554c415445443030393030303030303030303030303030303030303030" + ] + ], + [ + "00000012", + [ + "0000000412020078DB2D6D" + ] + ], + [ + "00000011", + [ + "00000005110200C4100400" + ] + ], + [ + "00000008", + [ + "00000006080200010100020A00" + ] + ], + [ + "020a0003", + [ + "020A0007030200E300" + ] + ], + [ + "02090003", + [ + "02090009030200E200" + ] + ], + [ + "02090010", + [ + "0209000A100200352E302E39" + ] + ], + [ + "02080003", + [ + "0208000B0302000001" + ] + ], + [ + "02080002", + [ + "0208000c02020053494d554c415445443031303030303030303030303030303030303030303030" + ] + ], + [ + "02080012", + [ + "0208000D12020078DB2D6D" + ] + ], + [ + "02080011", + [ + "0208000E110200C4100400" + ] + ], + [ + "02070003", + [ + "0207000F0302000001" + ] + ], + [ + "02070002", + [ + "0207001002020053494d554c415445443031313030303030303030303030303030303030303030" + ] + ], + [ + "02070012", + [ + "0207001112020078DB2D6D" + ] + ], + [ + "02070011", + [ + "02070012110200C4100400" + ] + ], + [ + "02060003", + [ + "02060013030200E100" + ] + ], + [ + "02060010", + [ + "02060014100200302E372E38" + ] + ], + [ + "02050003", + [ + "02050015030200E000" + ] + ], + [ + "02050010", + [ + "02050016100200302E332E3134" + ] + ], + [ + "02040003", + [ + "02040017030200E000" + ] + ], + [ + "02040010", + [ + "02040018100200302E332E3134" + ] + ], + [ + "02030003", + [ + "02030019030200E000" + ] + ], + [ + "02030010", + [ + "0203001A100200302E332E3134" + ] + ], + [ + "02020003", + [ + "0202001B030200E000" + ] + ], + [ + "02020010", + [ + "0202001C100200302E332E3134" + ] + ], + [ + "02010003", + [ + "0201001D0302000001" + ] + ], + [ + "02010002", + [ + "0201001e02020053494d554c415445443031323030303030303030303030303030303030303030" + ] + ], + [ + "02010012", + [ + "0201001F12020078DB2D6D" + ] + ], + [ + "02010011", + [ + "02010020110200C4100400" + ] + ], + [ + "20000008", + [ + "20000022080200220400" + ] + ], + [ + "22040001", + [ + "220400230102002B33365620496E7465726C6F636B" + ] + ], + [ + "22040012", + [ + "2204002412020056" + ] + ], + [ + "22030001", + [ + "220300250102002B355620555342" + ] + ], + [ + "22030012", + [ + "2203002612020056" + ] + ], + [ + "22020001", + [ + "220200270102002B333656" + ] + ], + [ + "22020012", + [ + "2202002812020056" + ] + ], + [ + "22010001", + [ + "220100290102002B35562056427573" + ] + ], + [ + "22010012", + [ + "2201002A12020056" + ] + ], + [ + "22010010", + [ + "2201002D100200C92CA640" + ] + ], + [ + "11010010000100000000ee02000100000000b00400010000000010270000a6faff0000000003000300320000007102006400000080c3c901b80b0000000200000180ff800c0000b80b307532000000803801000a0000b80b000050000000000000fa1027000010270000000000000000000060ea000000000000800100000000f401a00f00000000000000ffffffff0a0064000000000000002f440000803f000000000000905f0100c94eaa3acea074395d1feb330000000000000000141b000014000000b1010000ea100000401f000000000000f4010000102700000f0000000000000000000000000000001800020000002c01000032000000", + [ + "1101002E100200" + ] + ], + [ + "11020010ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + [ + "1102002F100200" + ] + ], + [ + "11030010ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + [ + "11030030100200" + ] + ], + [ + "11040010ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + [ + "11040031100200" + ] + ], + [ + "11050010ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + [ + "11050032100200" + ] + ], + [ + "11060010ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + [ + "11060033100200" + ] + ], + [ + "11070010ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + [ + "11070034100200" + ] + ], + [ + "11080010ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + [ + "11080035100200" + ] + ], + [ + "11090010ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + [ + "11090036100200" + ] + ], + [ + "110a0010ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee020000ffc4098a02000088130000", + [ + "110A0037100200" + ] + ], + [ + "110b0010ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee02000001c4098a02000088130000", + [ + "110B0038100200" + ] + ], + [ + "110c0010ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee020000ffc4098a02000088130000", + [ + "110C0039100200" + ] + ], + [ + "110d0010ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee02000001c4098a02000088130000", + [ + "110D003A100200" + ] + ], + [ + "110e0010ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee020000ffc4098a02000088130000", + [ + "110E003B100200" + ] + ], + [ + "110f0010ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee02000001c4098a02000088130000", + [ + "110F003C100200" + ] + ], + [ + "11100010ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee020000ffc4098a02000088130000", + [ + "1110003D100200" + ] + ], + [ + "11110010ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee02000001c4098a02000088130000", + [ + "1111003E100200" + ] + ], + [ + "12010010c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + [ + "1201003F100200" + ] + ], + [ + "12020010c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + [ + "12020040100200" + ] + ], + [ + "12030010c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + [ + "12030041100200" + ] + ], + [ + "12040010c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + [ + "12040042100200" + ] + ], + [ + "12050010c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + [ + "12050043100200" + ] + ], + [ + "12060010c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + [ + "12060044100200" + ] + ], + [ + "12070010c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + [ + "12070045100200" + ] + ], + [ + "12080010c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + [ + "12080046100200" + ] + ], + [ + "111200100001000000030f01000100000029830100010000009b1f0f000000000052060300030003f23d0000400d0300e80300000048e80194110000f30100000d0000b0040000dc05640018010000000000000a00298301006f4d000000000000fb10270000d6060a000000000000000000983a000000000000c60000000000f401a00f00000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000001800000000000000000000000000", + [ + "11120047100200" + ] + ], + [ + "1113001000010000001966010001000000f9f91b0001000000bac317010000000002f00200030003b735000050c30000e803000080841e00d0070000e10300000d0000bc020000dc056400fa000000e02e00000a00f9f91b001966010000000000fb4c1d000020030a000000000000000000a861000000000000290700000000f401d00700000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000d4feffff3705000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000dc0500000000000000000000000000000000", + [ + "11130048100200" + ] + ], + [ + "11140010000a000000415d0000bc02000030b301000000000000000000d03effff00000000010003380600000000000000000000000000000000000000000000090000b80b0000dc05e8030000000000000000000030b30100161f000000000000fc1027000088130a000000000000000000c8af0000000000003e0158020000640000000000e803fa0000ffffffff0a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000000000000000000000000000000000", + [ + "11140049100200" + ] + ], + [ + "111500100001000000ebb8010001000000b9bd050001000000e5f61600c396c6ff000000000300039475000020a107006400000080841e00f40100004b0000000d0000bc020000dc05640004010000b03600000200b9bd050075dc000000000000fa4c1d000020030a000000000000000000983a000000000000f00200000000f401c40900000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000dc0500000000000000000000000000000000", + [ + "1115004A100200" + ] + ], + [ + "0000000f", + [ + "0000004B0F0200" + ] + ], + [ + "1000000f", + [ + "1000004C0F0200" + ] + ], + [ + "1115001200", + [ + "1115004D120200" + ] + ], + [ + "1113001200", + [ + "1113004E120200" + ] + ], + [ + "1114001200", + [ + "1114004F120200" + ] + ], + [ + "1208001200", + [ + "12080050120200" + ] + ], + [ + "1112001200", + [ + "11120051120200" + ] + ], + [ + "1206001200", + [ + "12060052120200" + ] + ], + [ + "1207001200", + [ + "12070053120200" + ] + ], + [ + "1204001200", + [ + "12040054120200" + ] + ], + [ + "1205001200", + [ + "12050055120200" + ] + ], + [ + "1202001200", + [ + "12020056120200" + ] + ], + [ + "1203001200", + [ + "12030057120200" + ] + ], + [ + "1111001200", + [ + "11110058120200" + ] + ], + [ + "1201001200", + [ + "12010059120200" + ] + ], + [ + "110f001200", + [ + "110F005A120200" + ] + ], + [ + "1110001200", + [ + "1110005B120200" + ] + ], + [ + "110d001200", + [ + "110D005C120200" + ] + ], + [ + "110e001200", + [ + "110E005D120200" + ] + ], + [ + "110b001200", + [ + "110B005E120200" + ] + ], + [ + "110c001200", + [ + "110C005F120200" + ] + ], + [ + "1109001200", + [ + "11090060120200" + ] + ], + [ + "110a001200", + [ + "110A0061120200" + ] + ], + [ + "1107001200", + [ + "11070062120200" + ] + ], + [ + "1108001200", + [ + "11080063120200" + ] + ], + [ + "1105001200", + [ + "11050064120200" + ] + ], + [ + "1106001200", + [ + "11060065120200" + ] + ], + [ + "1103001200", + [ + "11030066120200" + ] + ], + [ + "1104001200", + [ + "11040067120200" + ] + ], + [ + "1101001200", + [ + "11010068120200" + ] + ], + [ + "1102001200", + [ + "11020069120200" + ] + ], + [ + "11150024", + [ + "1115006A2402006251FDFF" + ] + ], + [ + "11130024", + [ + "1113006B24020000000000" + ] + ], + [ + "11140024", + [ + "1114006C2402005EFFFFFF" + ] + ], + [ + "12080024", + [ + "1208006D240200E0010000" + ] + ], + [ + "11120024", + [ + "1112006E2402008EF80000" + ] + ], + [ + "12060024", + [ + "1206006F240200E0010000" + ] + ], + [ + "12070024", + [ + "12070070240200E0010000" + ] + ], + [ + "12040024", + [ + "12040071240200E0010000" + ] + ], + [ + "12050024", + [ + "12050072240200E0010000" + ] + ], + [ + "12020024", + [ + "12020073240200E0010000" + ] + ], + [ + "12030024", + [ + "12030074240200E0010000" + ] + ], + [ + "11110024", + [ + "111100752402006B200000" + ] + ], + [ + "12010024", + [ + "12010076240200E0010000" + ] + ], + [ + "110f0024", + [ + "110F0077240200DC1F0000" + ] + ], + [ + "11100024", + [ + "1110007824020052200000" + ] + ], + [ + "110d0024", + [ + "110D0079240200EE1F0000" + ] + ], + [ + "110e0024", + [ + "110E007A2402000A200000" + ] + ], + [ + "110b0024", + [ + "110B007B240200F81F0000" + ] + ], + [ + "110c0024", + [ + "110C007C24020026200000" + ] + ], + [ + "11090024", + [ + "1109007D2402006D1A0300" + ] + ], + [ + "110a0024", + [ + "110A007E240200E71F0000" + ] + ], + [ + "11070024", + [ + "1107007F2402005F1A0300" + ] + ], + [ + "11080024", + [ + "110800802402006B1A0300" + ] + ], + [ + "11050024", + [ + "110500812402006B1A0300" + ] + ], + [ + "11060024", + [ + "110600822402006B1A0300" + ] + ], + [ + "11030024", + [ + "110300832402006A1A0300" + ] + ], + [ + "11040024", + [ + "110400842402006B1A0300" + ] + ], + [ + "11010024", + [ + "110100852402006CE1FFFF" + ] + ], + [ + "11020024", + [ + "11020086240200691A0300" + ] + ], + [ + "11100040a6ae02006f711100fcc4f53100000000af2500000000", + [ + "11100005400032" + ] + ], + [ + "11110040a6ae02006f711100fcc4f53100000000af2500000000", + [ + "11110006400032" + ] + ], + [ + "110e0040a6ae02006f711100fcc4f53100000000af2500000000", + [ + "110E0007400032" + ] + ], + [ + "110f0040a6ae02006f711100fcc4f53100000000af2500000000", + [ + "110F0008400032" + ] + ], + [ + "110c0040a6ae02006f711100fcc4f53100000000af2500000000", + [ + "110C0009400032" + ] + ], + [ + "110d0040a6ae02006f711100fcc4f53100000000af2500000000", + [ + "110D000A400032" + ] + ], + [ + "110a0040a6ae02006f711100fcc4f53100000000af2500000000", + [ + "110A000B400032" + ] + ], + [ + "110b0040a6ae02006f711100fcc4f53100000000af2500000000", + [ + "110B000C400032" + ] + ], + [ + "110a0051", + [ + "110A0010510100", + "110A0010510200" + ] + ], + [ + "110e0051", + [ + "110E0011510100", + "110E0011510200" + ] + ], + [ + "110b0051", + [ + "110B0014510100", + "110B0014510200" + ] + ], + [ + "110f0051", + [ + "110F0015510100", + "110F0015510200" + ] + ], + [ + "110c0051", + [ + "110C0018510100", + "110C0018510200" + ] + ], + [ + "11100051", + [ + "11100019510100", + "11100019510200" + ] + ], + [ + "110d0051", + [ + "110D001C510100", + "110D001C510200" + ] + ], + [ + "11110051", + [ + "1111001D510100", + "1111001D510200" + ] + ], + [ + "1000005088130000", + [ + "1000002E500100", + "1000002E500200" + ] + ], + [ + "11140040415d000030b301000000000000000000000000000000", + [ + "11140030400032" + ] + ], + [ + "11140051", + [ + "11140035510100", + "11140035510200" + ] + ], + [ + "1113004019660100f9f91b00bac3170100000000000000000000", + [ + "11130037400032" + ] + ], + [ + "11130051", + [ + "11130039510100", + "11130039510200" + ] + ], + [ + "1113004019660100f9f91b00bac3170100000000a98b00000000", + [ + "1113003B400200" + ] + ], + [ + "1113005030750000", + [ + "1113003C500100", + "1113003C500200" + ] + ], + [ + "22020010", + [ + "2202003D1002001AFC0F42" + ] + ], + [ + "11150040ebb80100b9bd0500e5f6160000000000000000000000", + [ + "1115003F400032" + ] + ], + [ + "11150051", + [ + "11150041510100", + "11150041510200" + ] + ], + [ + "11150040ebb80100b9bd0500e5f61600000000009bc1fcff0000", + [ + "11150043400200" + ] + ], + [ + "1115005030750000", + [ + "11150044500100", + "11150044500200" + ] + ], + [ + "11150040ebb80100b9bd0500e5f61600000000009454fdff0000", + [ + "11150046400200" + ] + ], + [ + "11120040030f0100298301009b1f0f0000000000000000000000", + [ + "11120049400032" + ] + ], + [ + "11120051", + [ + "1112004B510100", + "1112004B510200" + ] + ], + [ + "22030010", + [ + "2203004C100200424FA740" + ] + ], + [ + "1114005030750000", + [ + "1114004F500100", + "1114004F500200" + ] + ], + [ + "11120040030f0100298301009b1f0f0000000000d6b900000000", + [ + "11120053400200" + ] + ], + [ + "1112005030750000", + [ + "11120054500100", + "11120054500200" + ] + ], + [ + "1108004043700100f0f2020080e29e0000000000000000000000", + [ + "1108005D400032" + ] + ], + [ + "1109004043700100f0f2020080e29e0000000000000000000000", + [ + "1109005E400032" + ] + ], + [ + "1106004043700100f0f2020080e29e0000000000000000000000", + [ + "1106005F400032" + ] + ], + [ + "1107004043700100f0f2020080e29e0000000000000000000000", + [ + "11070060400032" + ] + ], + [ + "1104004043700100f0f2020080e29e0000000000000000000000", + [ + "11040061400032" + ] + ], + [ + "1105004043700100f0f2020080e29e0000000000000000000000", + [ + "11050062400032" + ] + ], + [ + "1102004043700100f0f2020080e29e0000000000000000000000", + [ + "11020063400032" + ] + ], + [ + "1103004043700100f0f2020080e29e0000000000000000000000", + [ + "11030064400032" + ] + ], + [ + "11020051", + [ + "1102006E510100", + "1102006E510200" + ] + ], + [ + "22040010", + [ + "2204006F100200A5E60F42" + ] + ], + [ + "11150040ebb80100b9bd0500e5f6160000000000dbd8fdff0000", + [ + "11150093400200" + ] + ], + [ + "1101004000ee020000b004000010270000000000000000000000", + [ + "11010096400032" + ] + ], + [ + "11010051", + [ + "11010098510100", + "11010098510200" + ] + ], + [ + "1101004000ee020000b00400001027000000000000f6ffff0000", + [ + "1101009A400200" + ] + ], + [ + "1101005030750000", + [ + "1101009B500100", + "1101009B500200" + ] + ], + [ + "13010010", + [ + "1301009C1002000202020202020202" + ] + ], + [ + "110b0040ffaa0200ae59110021bdb131000000009d1500000000", + [ + "110B00C8400200" + ] + ], + [ + "110a0040fcad02001d6d11007766e931000000008b1500000000", + [ + "110A00C9400200" + ] + ], + [ + "110d0040feab020029601100e84ac43100000000971500000000", + [ + "110D00CA400200" + ] + ], + [ + "110c004007a30200dc251100e54e1d3100000000cd1500000000", + [ + "110C00CB400200" + ] + ], + [ + "110f0040a6ae02006f711100fcc4f53100000000871500000000", + [ + "110F00CC400200" + ] + ], + [ + "110e004083a60200883c11001f3f5e3100000000b81500000000", + [ + "110E00CD400200" + ] + ], + [ + "11110040bd97020071dc100011084b3000000000111600000000", + [ + "111100CE400200" + ] + ], + [ + "11100040649b020032f41000ed0f8f3000000000fb1500000000", + [ + "111000CF400200" + ] + ], + [ + "1000005002140000", + [ + "100000D0500100", + "100000D0500200" + ] + ], + [ + "110b004001260200d0f80d00f89a0428000000009a1500000000", + [ + "110B000C400200" + ] + ], + [ + "110a004001260200d0f80d00f89a042800000000881500000000", + [ + "110A000D400200" + ] + ], + [ + "110d004001260200d0f80d00f89a042800000000941500000000", + [ + "110D000E400200" + ] + ], + [ + "110c004001260200d0f80d00f89a042800000000ca1500000000", + [ + "110C000F400200" + ] + ], + [ + "110f0040ac6e01008b500900a5bcad1a00000000851500000000", + [ + "110F0010400200" + ] + ], + [ + "110e004001260200d0f80d00f89a042800000000b51500000000", + [ + "110E0011400200" + ] + ], + [ + "11110040ac6e01008b500900a5bcad1a000000000f1600000000", + [ + "11110012400200" + ] + ], + [ + "11100040ac6e01008b500900a5bcad1a00000000f91500000000", + [ + "11100013400200" + ] + ], + [ + "100000508e130000", + [ + "10000014500100", + "10000014500200" + ] + ], + [ + "11150040ebb80100b9bd0500e5f616000000000099d8fdff0000", + [ + "1115004F400200" + ] + ], + [ + "11010040ae060000451600001359000000000000faf5ffff0000", + [ + "11010050400200" + ] + ], + [ + "10000050f8130000", + [ + "10000051500100", + "10000051500200" + ] + ], + [ + "1101004000ee020000b004000010270000000000afe1ffff0000", + [ + "1101006F400200" + ] + ], + [ + "100000501a150000", + [ + "10000070500100", + "10000070500200" + ] + ], + [ + "1103004043700100f0f2020080e29e00000000006a1a03000000", + [ + "1103008E400200" + ] + ], + [ + "1102004043700100f0f2020080e29e00000000006a1a03000000", + [ + "1102008F400200" + ] + ], + [ + "1105004043700100f0f2020080e29e00000000006a1a03000000", + [ + "11050090400200" + ] + ], + [ + "1104004043700100f0f2020080e29e00000000006a1a03000000", + [ + "11040091400200" + ] + ], + [ + "1107004043700100f0f2020080e29e00000000006a1a03000000", + [ + "11070092400200" + ] + ], + [ + "1106004043700100f0f2020080e29e00000000006a1a03000000", + [ + "11060093400200" + ] + ], + [ + "1109004043700100f0f2020080e29e00000000006a1a03000000", + [ + "11090094400200" + ] + ], + [ + "1108004043700100f0f2020080e29e00000000006a1a03000000", + [ + "11080095400200" + ] + ], + [ + "10000050f01d0000", + [ + "10000096500100", + "10000096500200" + ] + ], + [ + "11150040ebb80100b9bd0500e5f61600000000006251fdff0000", + [ + "111500B5400200" + ] + ], + [ + "100000500f170000", + [ + "100000B6500100", + "100000B6500200" + ] + ], + [ + "110b0040099e020066051100ee56c03000000000e91800000000", + [ + "110B00B9400200" + ] + ], + [ + "110a004046ac020000621100b190c93100000000e91800000000", + [ + "110A00BA400200" + ] + ], + [ + "110d0040c8a202004424110084bf183100000000e91800000000", + [ + "110D00BB400200" + ] + ], + [ + "110c004011780200760e10003b12fd2d00000000e91800000000", + [ + "110C00BC400200" + ] + ], + [ + "110f0040a6ae02006f711100fcc4f53100000000e91800000000", + [ + "110F00BD400200" + ] + ], + [ + "110e0040ad8802007f7a10004980322f00000000e91800000000", + [ + "110E00BE400200" + ] + ], + [ + "111100407b4102007eab0e00795f042a00000000e91800000000", + [ + "111100BF400200" + ] + ], + [ + "11100040e2520200ac1c0f00a189482b00000000e91800000000", + [ + "111000C0400200" + ] + ], + [ + "10000050c1130000", + [ + "100000C1500100", + "100000C1500200" + ] + ], + [ + "1101004000ee020000b004000010270000000000aee1ffff0000", + [ + "1101001A400200" + ] + ], + [ + "10000050a0130000", + [ + "1000001B500100", + "1000001B500200" + ] + ], + [ + "110b004099aa000073550400856f1f0e000000007de2feff0000", + [ + "110B0058400200" + ] + ], + [ + "110a0040f8aa0000d9570400d54c270e00000000d1e1feff0000", + [ + "110A0059400200" + ] + ], + [ + "110d0040aaab00005c5c04002509360e000000008ee0feff0000", + [ + "110D005A400200" + ] + ], + [ + "110c0040d7aa0000035704007991240e000000000de2feff0000", + [ + "110C005B400200" + ] + ], + [ + "110f0040d8aa000006570400aaa6240e000000000ce2feff0000", + [ + "110F005C400200" + ] + ], + [ + "110e00403dab00009859040022032d0e0000000054e1feff0000", + [ + "110E005D400200" + ] + ], + [ + "1111004096aa00005a550400f12f1f0e0000000084e2feff0000", + [ + "1111005E400200" + ] + ], + [ + "1110004082aa0000d954040016881d0e00000000a8e2feff0000", + [ + "1110005F400200" + ] + ], + [ + "100000503f1b0000", + [ + "10000060500100", + "10000060500200" + ] + ], + [ + "12010051", + [ + "12010069510100", + "12010069510200" + ] + ], + [ + "12020040c8000000a05a0000c800000050c300000000000000", + [ + "1202007B400200" + ] + ], + [ + "12010040c8000000a05a0000c800000050c300000000000000", + [ + "1201007C400200" + ] + ], + [ + "12040040c8000000a05a0000c800000050c300000000000000", + [ + "1204007D400200" + ] + ], + [ + "12030040c8000000a05a0000c800000050c300000000000000", + [ + "1203007E400200" + ] + ], + [ + "12060040c8000000a05a0000c800000050c300000000000000", + [ + "1206007F400200" + ] + ], + [ + "12050040c8000000a05a0000c800000050c300000000000000", + [ + "12050080400200" + ] + ], + [ + "12080040c8000000a05a0000c800000050c300000000000000", + [ + "12080081400200" + ] + ], + [ + "12070040c8000000a05a0000c800000050c300000000000000", + [ + "12070082400200" + ] + ], + [ + "1000005070170000", + [ + "10000083500100", + "10000083500200" + ] + ], + [ + "12020040c800000098480000c8000000409c0000c05d000000", + [ + "12020084400200" + ] + ], + [ + "12010040c800000098480000c8000000409c0000c05d000000", + [ + "12010085400200" + ] + ], + [ + "12040040c800000098480000c8000000409c0000c05d000000", + [ + "12040086400200" + ] + ], + [ + "12030040c800000098480000c8000000409c0000c05d000000", + [ + "12030087400200" + ] + ], + [ + "12060040c800000098480000c8000000409c0000c05d000000", + [ + "12060088400200" + ] + ], + [ + "12050040c800000098480000c8000000409c0000c05d000000", + [ + "12050089400200" + ] + ], + [ + "12080040c800000098480000c8000000409c0000c05d000000", + [ + "1208008A400200" + ] + ], + [ + "12070040c800000098480000c8000000409c0000c05d000000", + [ + "1207008B400200" + ] + ], + [ + "10000050b41a0000", + [ + "1000008C500100", + "1000008C500200" + ] + ], + [ + "12020040c8000000a05a0000c800000050c30000c05d000001", + [ + "1202008D400200" + ] + ], + [ + "12010040c8000000a05a0000c800000050c30000c05d000001", + [ + "1201008E400200" + ] + ], + [ + "12040040c8000000a05a0000c800000050c30000c05d000001", + [ + "1204008F400200" + ] + ], + [ + "12030040c8000000a05a0000c800000050c30000c05d000001", + [ + "12030090400200" + ] + ], + [ + "12060040c8000000a05a0000c800000050c30000c05d000001", + [ + "12060091400200" + ] + ], + [ + "12050040c8000000a05a0000c800000050c30000c05d000001", + [ + "12050092400200" + ] + ], + [ + "12080040c8000000a05a0000c800000050c30000c05d000001", + [ + "12080093400200" + ] + ], + [ + "12070040c8000000a05a0000c800000050c30000c05d000001", + [ + "12070094400200" + ] + ], + [ + "12020040c800000098480000c8000000409c00000000000001", + [ + "12020096400200" + ] + ], + [ + "12010040c800000098480000c8000000409c00000000000001", + [ + "12010097400200" + ] + ], + [ + "12040040c800000098480000c8000000409c00000000000001", + [ + "12040098400200" + ] + ], + [ + "12030040c800000098480000c8000000409c00000000000001", + [ + "12030099400200" + ] + ], + [ + "12060040c800000098480000c8000000409c00000000000001", + [ + "1206009A400200" + ] + ], + [ + "12050040c800000098480000c8000000409c00000000000001", + [ + "1205009B400200" + ] + ], + [ + "12080040c800000098480000c8000000409c00000000000001", + [ + "1208009C400200" + ] + ], + [ + "12070040c800000098480000c8000000409c00000000000001", + [ + "1207009D400200" + ] + ], + [ + "100000505b1a0000", + [ + "1000009E500100", + "1000009E500200" + ] + ], + [ + "110b004066aa0200ca551100fcc4f53100000000e91800000000", + [ + "110B0032400200" + ] + ], + [ + "110a0040e0ab0200655f1100fcc4f53100000000e91800000000", + [ + "110A0033400200" + ] + ], + [ + "110d0040a6ae02006f711100fcc4f53100000000e91800000000", + [ + "110D0034400200" + ] + ], + [ + "110c00405cab02000c5c1100fcc4f53100000000e91800000000", + [ + "110C0035400200" + ] + ], + [ + "110f00405eab02001a5c1100fcc4f53100000000e91800000000", + [ + "110F0036400200" + ] + ], + [ + "110e0040f3ac020060661100fcc4f53100000000e91800000000", + [ + "110E0037400200" + ] + ], + [ + "1111004056aa020066551100fcc4f53100000000e91800000000", + [ + "11110038400200" + ] + ], + [ + "1110004007aa020064531100fcc4f53100000000e91800000000", + [ + "11100039400200" + ] + ], + [ + "10000050eb150000", + [ + "1000003A500100", + "1000003A500200" + ] + ], + [ + "12020040c8000000e8000000c800000010270000e001000001", + [ + "1202003B400200" + ] + ], + [ + "12010040c8000000e8000000c800000010270000e001000001", + [ + "1201003C400200" + ] + ], + [ + "12040040c8000000e8000000c800000010270000e001000001", + [ + "1204003D400200" + ] + ], + [ + "12030040c8000000e8000000c800000010270000e001000001", + [ + "1203003E400200" + ] + ], + [ + "12060040c8000000e8000000c800000010270000e001000001", + [ + "1206003F400200" + ] + ], + [ + "12050040c8000000e8000000c800000010270000e001000001", + [ + "12050040400200" + ] + ], + [ + "12080040c8000000e8000000c800000010270000e001000001", + [ + "12080041400200" + ] + ], + [ + "12070040c8000000e8000000c800000010270000e001000001", + [ + "12070042400200" + ] + ], + [ + "10000050951e0000", + [ + "10000043500100", + "10000043500200" + ] + ], + [ + "110b0040a6ae02006f711100fcc4f53100000000542200000000", + [ + "110B00D5400200" + ] + ], + [ + "110a0040a6ae02006f711100fcc4f53100000000542200000000", + [ + "110A00D6400200" + ] + ], + [ + "110d0040a6ae02006f711100fcc4f53100000000542200000000", + [ + "110D00D7400200" + ] + ], + [ + "110c0040a6ae02006f711100fcc4f53100000000542200000000", + [ + "110C00D8400200" + ] + ], + [ + "110f0040a6ae02006f711100fcc4f53100000000542200000000", + [ + "110F00D9400200" + ] + ], + [ + "110e0040a6ae02006f711100fcc4f53100000000542200000000", + [ + "110E00DA400200" + ] + ], + [ + "11110040a6ae02006f711100fcc4f53100000000542200000000", + [ + "111100DB400200" + ] + ], + [ + "11100040a6ae02006f711100fcc4f53100000000542200000000", + [ + "111000DC400200" + ] + ], + [ + "10000050e6130000", + [ + "100000DD500100", + "100000DD500200" + ] + ], + [ + "11010040360000005d01000024e7030000000000aee1ffff0000", + [ + "110100FB400200" + ] + ], + [ + "110b00400aaa020075531100e9e79f31000000009d1500000000", + [ + "110B00FC400200" + ] + ], + [ + "110a0040cfad0200fc6b11006d28e631000000008b1500000000", + [ + "110A00FD400200" + ] + ], + [ + "110d00404cab0200a25b1100c052b73100000000971500000000", + [ + "110D00FE400200" + ] + ], + [ + "110c0040fb9f02000c1211003491e43000000000cd1500000000", + [ + "110C00FF400200" + ] + ], + [ + "110e004062a40200aa2e11002387363100000000b81500000000", + [ + "110E0002400200" + ] + ], + [ + "11110040bc91020063b51000b32bdb2f00000000111600000000", + [ + "11110003400200" + ] + ], + [ + "11100040589602005dd31000c608313000000000fb1500000000", + [ + "11100004400200" + ] + ], + [ + "10000050f5130000", + [ + "10000005500100", + "10000005500200" + ] + ], + [ + "110a0040513b0000bd540000634f030000000000452300000000", + [ + "110A0023400200" + ] + ], + [ + "110c0040343a000026530000793f030000000000452300000000", + [ + "110C0024400200" + ] + ], + [ + "110b0040033b00004e5400000c4b030000000000452300000000", + [ + "110B0025400200" + ] + ], + [ + "110e00408f3a0000a75300008944030000000000452300000000", + [ + "110E0026400200" + ] + ], + [ + "110d00401d3b0000735400007f4c030000000000452300000000", + [ + "110D0027400200" + ] + ], + [ + "111000406d3900000a5200006134030000000000452300000000", + [ + "11100028400200" + ] + ], + [ + "110f0040623b0000d65400005a50030000000000452300000000", + [ + "110F0029400200" + ] + ], + [ + "11120040030f0100298301009b1f0f00000000008df800000000", + [ + "1112002A400200" + ] + ], + [ + "111100400e39000082510000132f030000000000452300000000", + [ + "1111002B400200" + ] + ], + [ + "1000005018170000", + [ + "1000002C500100", + "1000002C500200" + ] + ], + [ + "11140040415d000030b30100000000000000000061ffffff0000", + [ + "1114004A400200" + ] + ], + [ + "10000050d4130000", + [ + "1000004B500100", + "1000004B500200" + ] + ], + [ + "1113004019660100f9f91b00bac3170100000000398800000000", + [ + "1113004C400200" + ] + ], + [ + "10000050fc130000", + [ + "1000004D500100", + "1000004D500200" + ] + ] + ] + } +} diff --git a/pylabrobot/beckman_coulter/biomek_i7/design.md b/pylabrobot/beckman_coulter/biomek_i7/design.md new file mode 100644 index 00000000000..6f5de098859 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/design.md @@ -0,0 +1,28 @@ +# How the Biomek i7 integration is built + +The patterns this driver follows. It follows the STAR's (`pylabrobot/hamilton/star/design.md`, +P1-P20); this says only where the Biomek differs or adds something. + +## What makes the Biomek different + +A STAR takes operations ("pick up tips here") and plans the motion itself. A Biomek's boards take +one axis at a time, in encoder counts. Three layers of Beckman software sit between a method and the +boards: **Biomek** (the application) plans operations, safe heights, collisions and liquid handling; +**the Master Controller** (MC) takes host commands in counts (`AM`, `HM`, `LT`...), coordinates each +pod's axes and keeps their positions; **the ACE boards** (a chassis and one per pod) take +single-axis commands over USB. This driver replaces the top two and talks to the boards directly. + +| Layer | What it reproduces | Where | +|---|---|---| +| L1 wire | the ACE messages | `driver/framing.py`, `board.py`, `protocol.py` | +| L2 board commands | one board request each | `_unchecked_fw_*` on the pods and chassis | +| L3 MC | one MC host command each | the pods' public primitives, `driver/recipes/` | +| L4 planning | Biomek's planning | `driver/motion.py`, `pod_geometry.py`, `liquid.py` (no I/O) | +| L5 PyLabRobot | the PLR API | `device.py`, the operation features, `resource_model/` | + +Each layer calls only the one below it. + +**I1. The boards say what is fitted.** `discover()` (read-only) asks each board its module type and +side; that places it, not the USB serial number or the enumeration order. An unknown type or side, +two boards claiming one place, or no chassis is refused. `driver/simulator.py` simulates the boards +at the wire, answering identity reads from a recording of a real instrument's. diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/__init__.py b/pylabrobot/beckman_coulter/biomek_i7/driver/__init__.py new file mode 100644 index 00000000000..582f4e5646a --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/__init__.py @@ -0,0 +1 @@ +"""The Biomek i7's ACE boards: framing, messages, and the boards themselves.""" diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/board.py b/pylabrobot/beckman_coulter/biomek_i7/driver/board.py new file mode 100644 index 00000000000..1eddc8fdfd7 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/board.py @@ -0,0 +1,292 @@ +"""One ACE board: its USB link, its sequence numbers, and the replies it sends back. + +A Biomek i7 has one ACE board per module (the chassis, and one per arm), each its own USB device +(VID 0x0AB5, PID 0xACE0). A board accepts many requests at once and answers them in whatever +order they finish, so replies are matched to requests by their header, not by order. Moves and +homes answer twice, ACCEPTED when they start and DONE when they finish. The board also sends +messages nobody asked for, with sequence 0; those go to subscribers. + +When a Move All fails, the axes that failed answer with the Move All's sequence under their own +device and index, before the Move All's own DONE; those replies are kept with the Move All and +raised with it. +""" + +import asyncio +import logging +from dataclasses import dataclass, field, replace +from typing import Callable, Dict, List, Optional, Sequence, Tuple + +from pylabrobot.beckman_coulter.biomek_i7.driver.errors import FrameError, ace_error +from pylabrobot.beckman_coulter.biomek_i7.driver.framing import IN_PACKET_SIZE, FrameReader, pack +from pylabrobot.beckman_coulter.biomek_i7.driver.protocol import ( + SAGIAN_CAN, + Reply, + Request, + Status, + describe_routine_unsolicited, + describe_sagian_can, +) +from pylabrobot.io.usb import USB + +logger = logging.getLogger(__name__) + +ACE_VENDOR_ID = 0x0AB5 +ACE_PRODUCT_ID = 0xACE0 +ACE_READ_ENDPOINT = 0x81 +ACE_WRITE_ENDPOINT = 0x02 + +UnsolicitedCallback = Callable[[Reply], None] + + +@dataclass +class _Pending: + request: Request + done: "asyncio.Future[Reply]" + accepted: "asyncio.Future[Reply]" + related: List[Reply] = field(default_factory=list) + + +class AceBoard: + """The link to one ACE board.""" + + def __init__( + self, + serial_number: Optional[str] = None, + device_address: Optional[int] = None, + io: Optional[USB] = None, + name: str = "Biomek i7 ACE board", + default_timeout: float = 10.0, + ): + """ + Args: + serial_number: the board's USB serial number. With neither it nor `device_address`, the + first ACE board found is used. + device_address: the board's USB address, an alternative to the serial number. + io: a transport to use instead of opening the USB device; for tests and simulators. + name: what logs and errors call this board. + default_timeout: seconds to wait for a request's final reply when the caller gives none. + """ + self.name = name + self.usb_serial_number = serial_number + self.default_timeout = default_timeout + self.io = io or USB( + id_vendor=ACE_VENDOR_ID, + id_product=ACE_PRODUCT_ID, + human_readable_device_name=name, + serial_number=serial_number, + device_address=device_address, + read_endpoint_address=ACE_READ_ENDPOINT, + write_endpoint_address=ACE_WRITE_ENDPOINT, + zero_length_packets=False, + packet_read_timeout=0.5, + ) + self._frames = FrameReader() + self._pending: Dict[Tuple[int, int, int, int], _Pending] = {} + self._sequence = 0 + self._write_lock = asyncio.Lock() + self._reader: Optional["asyncio.Task[None]"] = None + self._subscribers: List[UnsolicitedCallback] = [] + + # -- lifecycle ------------------------------------------------------------- + + async def setup(self) -> None: + """Open the board and start reading its replies.""" + await self.io.setup() + self._frames.reset() + self._reader = asyncio.create_task(self._read_loop(), name=f"{self.name} reader") + + async def stop(self) -> None: + """Stop reading, fail every request still waiting, and release the board.""" + if self._reader is not None: + self._reader.cancel() + try: + await self._reader + except asyncio.CancelledError: + pass + self._reader = None + self._fail_pending(ConnectionError(f"{self.name} stopped")) + await self.io.stop() + + @property + def connected(self) -> bool: + return self._reader is not None and not self._reader.done() + + def subscribe(self, callback: UnsolicitedCallback) -> Callable[[], None]: + """Call `callback` with every message the board sends unasked. Returns an unsubscribe.""" + self._subscribers.append(callback) + return lambda: self._subscribers.remove(callback) + + # -- requests -------------------------------------------------------------- + + async def send(self, request: Request, timeout: Optional[float] = None) -> Reply: + """Send one request and return its final reply. + + Raises: + AceError: if the board reports an error. + TimeoutError: if no final reply arrives within `timeout` seconds. + """ + return (await self.send_many([request], timeout=timeout))[0] + + async def send_many( + self, + requests: Sequence[Request], + timeout: Optional[float] = None, + raise_errors: bool = True, + ) -> List[Reply]: + """Send requests together, packed into as few transfers as fit, and return their final + replies in request order. Every request is waited for before any error is raised; the first + error in request order is raised. + + Args: + requests: the requests, sent in this order. + timeout: seconds to wait for every final reply. Defaults to `default_timeout`. + raise_errors: when False, replies that report an error are returned instead of raised, for + a caller that decides on them (such as a move refused because the axis is not homed). + + Raises: + AceError: if `raise_errors` and the board reports an error for any of them. + TimeoutError: if any final reply does not arrive within `timeout` seconds. + """ + if not self.connected: + raise ConnectionError(f"{self.name} is not set up") + timeout = self.default_timeout if timeout is None else timeout + loop = asyncio.get_running_loop() + entries: List[Tuple[Tuple[int, int, int, int], _Pending]] = [] + messages = [] + for request in requests: + sequence = self._next_sequence() + key = (request.device, request.index, sequence, request.opcode) + entry = _Pending(request, loop.create_future(), loop.create_future()) + self._pending[key] = entry + entries.append((key, entry)) + messages.append(request.encode(sequence)) + try: + async with self._write_lock: + for message in messages: # one line per message, unframed, as Biomek's `ace_io` logs them + logger.debug("%s write %s", self.name, message.hex()) + for transfer in pack(messages): + await self.io.write(transfer) + done, not_done = await asyncio.wait([e.done for _, e in entries], timeout=timeout) + if not_done: + late = [str(e.request) for _, e in entries if not e.done.done()] + raise TimeoutError(f"{self.name}: no reply within {timeout} s to {', '.join(late)}") + replies = [replace(e.done.result(), related=tuple(e.related)) for _, e in entries] + if raise_errors: + for (_, entry), reply in zip(entries, replies): + self._raise_for(entry, reply) + return replies + finally: + for key, entry in entries: + self._pending.pop(key, None) + for future in (entry.done, entry.accepted): + if not future.done(): + future.cancel() + + def _raise_for(self, entry: _Pending, reply: Reply) -> None: + """Raise the reply's error, with the errors of the axes a failed Move All names.""" + if reply.error_code is None: + return + error = ace_error( + reply.error_code, reply.device_error, str(entry.request), reply.device, reply.index + ) + causes = [r for r in entry.related if r.error_code is not None] + if causes: + error.axis_errors = [ + ace_error( + r.error_code or 0, + r.device_error, + f"device 0x{r.device:02X} index {r.index}", + r.device, + r.index, + ) + for r in causes + ] + error.args = (str(error) + "; " + "; ".join(str(e) for e in error.axis_errors),) + raise error + + def _next_sequence(self) -> int: + """The next free sequence number, 1-255 then 1 again; 0 is the board's own.""" + in_use = {key[2] for key in self._pending} + for _ in range(255): + self._sequence = self._sequence % 255 + 1 + if self._sequence not in in_use: + return self._sequence + raise RuntimeError(f"{self.name}: all 255 sequence numbers are waiting for replies") + + # -- replies --------------------------------------------------------------- + + async def _read_loop(self) -> None: + while True: + try: + data = await self.io.read(timeout=1, size=IN_PACKET_SIZE) + except TimeoutError: + continue + except asyncio.CancelledError: + raise + except Exception as e: # the link is gone; nobody will answer what is waiting + logger.error("%s: read failed: %s", self.name, e) + self._fail_pending(ConnectionError(f"{self.name}: read failed: {e}")) + return + try: + messages = self._frames.feed(data) + except FrameError as e: + logger.error("%s: %s", self.name, e) + continue + for message in messages: + self._dispatch(message) + + def _dispatch(self, message: bytes) -> None: + logger.debug("%s read %s", self.name, message.hex()) + try: + reply = Reply.parse(message) + except ValueError as e: + logger.error("%s: %s", self.name, e) + return + if reply.unsolicited: + self._deliver_unsolicited(reply) + return + entry = self._pending.get(reply.key) + if entry is None: + related = self._pending_with_sequence(reply.sequence, reply.opcode) + if related is not None: + related.related.append(reply) + else: + logger.warning("%s: reply to no waiting request: %s", self.name, message.hex()) + return + if reply.status == Status.ACCEPTED and reply.error_code is None: + if not entry.accepted.done(): + entry.accepted.set_result(reply) + return + if not entry.done.done(): + entry.done.set_result(reply) + + def _pending_with_sequence(self, sequence: int, opcode: int) -> Optional[_Pending]: + for key, entry in self._pending.items(): + if key[2] == sequence and key[3] == opcode: + return entry + return None + + def _deliver_unsolicited(self, reply: Reply) -> None: + if (reply.device, reply.opcode) == SAGIAN_CAN: + # A message the board saw on its SAGIAN CAN bus, passed up: normal when a success or a + # request (see `describe_sagian_can`), flagged otherwise. + text, normal = describe_sagian_can(reply.data) + if normal: + logger.debug("%s: SAGIAN CAN %s (forwarded, normal)", self.name, text) + else: + logger.info("%s: SAGIAN CAN %s: a status not seen in normal operation", self.name, text) + elif (routine := describe_routine_unsolicited(reply)) is not None: + logger.debug("%s: %s (routine)", self.name, routine) + elif reply.status in (Status.EMERGENCY, Status.EVENT) or reply.error_code is not None: + logger.info("%s: unsolicited %s", self.name, reply) + for callback in list(self._subscribers): + try: + callback(reply) + except Exception: + logger.exception("%s: subscriber failed on %s", self.name, reply) + + def _fail_pending(self, error: Exception) -> None: + for entry in self._pending.values(): + if not entry.done.done(): + entry.done.set_exception(error) + self._pending.clear() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/board_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/board_tests.py new file mode 100644 index 00000000000..f625baa7680 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/board_tests.py @@ -0,0 +1,183 @@ +"""AceBoard against a fake board: matching, two-stage replies, unsolicited messages, errors.""" + +import asyncio +import unittest +from typing import Callable, List, Optional + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.errors import ( + InterlockTrippedError, + MotionError, + NotHomedError, +) +from pylabrobot.beckman_coulter.biomek_i7.driver.framing import frame, split +from pylabrobot.io.usb import USB + +Handler = Callable[[bytes], List[bytes]] + + +def done(request: bytes, payload: bytes = b"") -> bytes: + return request[:5] + b"\x02\x00" + payload + + +def accepted(request: bytes) -> bytes: + return request[:5] + b"\x01\x00" + + +def recorder(into: List[bytes], answer: Handler = lambda m: []) -> Handler: + """A handler that keeps every request in `into`, then answers with `answer`.""" + + def handler(message: bytes) -> List[bytes]: + into.append(message) + return answer(message) + + return handler + + +def answer_done(message: bytes) -> List[bytes]: + return [done(message)] + + +class FakeAceUSB(USB): + """A board on the far side of the USB link: records transfers, answers through `handler`, and + sends replies in 16-byte packets as a board does.""" + + def __init__(self, handler: Optional[Handler] = None): + super().__init__(0x0AB5, 0xACE0, "fake ACE board") + self.handler: Handler = handler or answer_done + self.transfers: List[bytes] = [] + self._packets: "asyncio.Queue[bytes]" = asyncio.Queue() + + async def setup(self, empty_buffer=True): + pass + + async def stop(self): + pass + + async def write(self, data: bytes, timeout: Optional[float] = None): + self.transfers.append(data) + for message in split(data): + for reply in self.handler(message): + self.push(reply) + + def push(self, message: bytes) -> None: + framed = frame(message) + for i in range(0, len(framed), 16): + self._packets.put_nowait(framed[i : i + 16]) + + async def read(self, timeout=None, size=None, endpoint=None) -> bytes: + try: + return await asyncio.wait_for(self._packets.get(), timeout=0.01) + except asyncio.TimeoutError: + raise TimeoutError("no packet") from None + + +class BoardTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + self.usb = FakeAceUSB() + self.board = AceBoard(io=self.usb, default_timeout=1) + await self.board.setup() + + async def asyncTearDown(self) -> None: + await self.board.stop() + + async def test_simple_request(self) -> None: + self.usb.handler = lambda m: [done(m, b"\x80\x00")] + reply = await self.board.send(p.get_module_id()) + self.assertEqual(p.parse_module_id(reply.payload).type, "chassis") + self.assertEqual(self.usb.transfers, [frame(p.get_module_id().encode(1))]) + + async def test_replies_out_of_order_match_their_requests(self) -> None: + held: List[bytes] = [] + self.usb.handler = recorder(held) + task = asyncio.create_task( + self.board.send_many([p.get_current_position(p.Device.MOTOR, axis) for axis in range(1, 9)]) + ) + while len(held) < 8: + await asyncio.sleep(0) + for message in reversed(held): + self.usb.push(done(message, message[1].to_bytes(4, "little"))) + replies = await task + self.assertEqual([p.parse_s32(r.payload) for r in replies], list(range(1, 9))) + self.assertEqual(len(self.usb.transfers), 1) # packed together + + async def test_two_stage_reply_waits_for_done(self) -> None: + held: List[bytes] = [] + self.usb.handler = recorder(held, lambda m: [accepted(m)]) + task = asyncio.create_task(self.board.send(p.move_all(5000))) + await asyncio.sleep(0.05) + self.assertFalse(task.done()) + self.usb.push(done(held[0])) + self.assertEqual((await task).status, p.Status.DONE) + + async def test_unsolicited_messages_go_to_subscribers_between_replies(self) -> None: + seen: List[p.Reply] = [] + self.board.subscribe(seen.append) + host_alive = bytes.fromhex("0000000040FE00") + emcy = bytes.fromhex("0000000031FF007E0010013704110000") + self.usb.handler = lambda m: [host_alive, emcy, done(m)] + await self.board.send(p.get_module_serial_number()) + await asyncio.sleep(0.05) + self.assertEqual([(r.device, r.opcode) for r in seen], [p.HOST_ALIVE, p.EMCY]) + self.assertEqual(p.parse_emcy(seen[1].data).device_error, 0x0437) + + async def test_error_status_raises(self) -> None: + self.usb.handler = lambda m: [m[:5] + b"\x00\x32"] + with self.assertRaises(NotHomedError): + await self.board.send(p.set_motor_move_parameters(1, 0, 1, 1, 1)) + + async def test_failed_move_all_raises_with_its_axes(self) -> None: + def handler(m: bytes) -> List[bytes]: + axis = bytes([0x11, 0x0A, 0x00, m[3], 0x50, 0x02, 0x3C, 0x00, 0x01, 0x00, 0x00]) + return [accepted(m), axis, m[:5] + b"\x02\x38"] + + self.usb.handler = handler + with self.assertRaises(MotionError) as ctx: + await self.board.send(p.move_all(5000)) + self.assertEqual([e.device_error for e in ctx.exception.axis_errors], [0x100]) + self.assertIn("motion error window exceeded", str(ctx.exception)) + + async def test_interlock_on_completion(self) -> None: + self.usb.handler = lambda m: [accepted(m), m[:5] + b"\x02\x0f\x07\x04\x00\x00"] + with self.assertRaises(InterlockTrippedError) as ctx: + await self.board.send(p.move(1, 30000)) + self.assertEqual(ctx.exception.device_error, 0x407) + + async def test_timeout_releases_the_sequence(self) -> None: + self.usb.handler = lambda m: [] + with self.assertRaises(TimeoutError): + await self.board.send(p.get_module_id(), timeout=0.05) + self.assertEqual(self.board._pending, {}) + + async def test_sequence_wraps_past_zero_and_skips_waiting_ones(self) -> None: + self.board._sequence = 254 + seen_requests: List[bytes] = [] + self.usb.handler = recorder(seen_requests, lambda m: [done(m)]) + for _ in range(3): + await self.board.send(p.get_module_id()) + self.assertEqual([m[3] for m in seen_requests], [255, 1, 2]) + + held: List[bytes] = [] + self.usb.handler = recorder(held) + waiting = asyncio.create_task(self.board.send(p.get_module_id())) # takes 3 + await asyncio.sleep(0) + self.board._sequence = 2 + self.usb.handler = recorder(seen_requests, lambda m: [done(m)]) + await self.board.send(p.get_module_serial_number()) + self.assertEqual(seen_requests[-1][3], 4) + self.usb.push(done(held[0])) + await waiting + + async def test_stop_fails_waiting_requests(self) -> None: + self.usb.handler = lambda m: [] + task = asyncio.create_task(self.board.send(p.get_module_id())) + await asyncio.sleep(0.02) + await self.board.stop() + with self.assertRaises(ConnectionError): + await task + await self.board.setup() # so tearDown can stop it again + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py new file mode 100644 index 00000000000..2bd18e6f5df --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py @@ -0,0 +1,70 @@ +"""What the driver knows about an instrument: facts only (STAR design.md P3). + +What the boards answer about themselves at setup: each module's identity, its boards with their +application images and versions, and the names of its inputs and outputs (`ModuleConfiguration`, +`BoardInfo`). +""" + +from dataclasses import dataclass, field +from typing import Dict, List, Optional + +from pylabrobot.beckman_coulter.biomek_i7.driver.protocol import HardwareVersion, ModuleId + + +# The firmware this driver has been run against (one instrument, 2026-10-24 through 2026-11-10): +# every motion board and module the same image, and the other boards' application versions +# (chassis 0.2.4, SAGIAN Motion 0.3.14, LLS 0.7.8, syringe pump 5.0.9). The Master Controller +# flashes the boards when it brings other firmware, which would change what the boards answer. +TESTED_FIRMWARE_IMAGES = {(0x6D2DDB78, 266436)} +TESTED_APPLICATION_VERSIONS = {"0.2.4", "0.3.14", "0.7.8", "5.0.9"} + + +@dataclass +class BoardInfo: + """One board inside a module, as the module reports it.""" + + index: int + hardware: HardwareVersion + serial_number: Optional[str] = None + application_version: Optional[str] = None + application_crc: Optional[int] = None + application_length: Optional[int] = None + + +@dataclass +class ModuleConfiguration: + """One ACE module (the chassis, or an arm): its identity, its boards, and its inputs.""" + + module_id: ModuleId + usb_serial_number: Optional[str] + serial_number: str + hardware: HardwareVersion + application_crc: int + application_length: int + device_counts: Dict[int, int] + boards: List[BoardInfo] = field(default_factory=list) + analog_inputs: Dict[int, str] = field(default_factory=dict) + analog_units: Dict[int, str] = field(default_factory=dict) + digital_inputs: Dict[int, str] = field(default_factory=dict) + digital_outputs: Dict[int, str] = field(default_factory=dict) + + def untested_firmware(self) -> List[str]: + """What this module runs that the driver has not been run against: one line per image or + version, empty when everything is tested.""" + found = [] + if (self.application_crc, self.application_length) not in TESTED_FIRMWARE_IMAGES: + found.append( + f"module image CRC {self.application_crc:#010x}, {self.application_length} bytes" + ) + for b in self.boards: + image = (b.application_crc, b.application_length) + if b.application_crc is not None and image not in TESTED_FIRMWARE_IMAGES: + found.append( + f"board {b.index} image CRC {b.application_crc:#010x}, {b.application_length} bytes" + ) + if ( + b.application_version is not None + and b.application_version not in TESTED_APPLICATION_VERSIONS + ): + found.append(f"board {b.index} application {b.application_version}") + return found diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/errors.py b/pylabrobot/beckman_coulter/biomek_i7/driver/errors.py new file mode 100644 index 00000000000..dfe7c096599 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/errors.py @@ -0,0 +1,141 @@ +"""Biomek i7 error types, and the reply bytes that raise them.""" + +from typing import Dict, List, Mapping, Optional, Tuple + +# ACE error codes, the byte after a reply's status. The Master Controller names more, but their +# numbers are not guessed. +ACE_ERROR_NAMES: Dict[int, str] = { + 0x0F: "interlock tripped", + 0x30: "motion device not configured", + 0x31: "motion device not enabled", + 0x32: "motion device not homed", + 0x38: "coordinated motion failed", + 0x3C: "motion error window exceeded", +} + +# Device error codes: the drive's own reason, after the ACE error code of a failed move, and in an +# EMCY message. Each one here was seen in a reply or an EMCY message. +DEVICE_ERROR_NAMES: Dict[int, str] = { + 0x0100: "motion error window exceeded", + 0x0407: "interlock tripped", + 0x0416: "interlock active", + 0x0431: "servo home aborted", + 0x0437: "stepper glitch", +} + + +class FrameError(Exception): + """Bytes from a board that do not split into whole frames.""" + + +class AceError(Exception): + """A board refused a command or reported that it failed. + + Attributes: + code: the ACE error code. + device_error: the drive's own error code, when the reply carries one. + request: a short description of the command that failed. + axis_errors: for a failed Move All, the errors the axes that failed reported. + """ + + def __init__( + self, + code: int, + device_error: Optional[int], + request: str, + device: Optional[int] = None, + index: Optional[int] = None, + ): + self.code = code + self.device_error = device_error + self.request = request + # The device and index the reply came from, when known: which axis failed. + self.device = device + self.index = index + self.axis_errors: List["AceError"] = [] + self.reason = ACE_ERROR_NAMES.get(code, f"ACE error 0x{code:02X}") + name = ACE_ERROR_NAMES.get(code, f"ACE error 0x{code:02X}") + detail = "" + if device_error is not None: + device_name = DEVICE_ERROR_NAMES.get(device_error) + detail = f" (device error 0x{device_error:X}" + (f": {device_name})" if device_name else ")") + super().__init__(f"{request}: {name}{detail}") + + +class InterlockTrippedError(AceError): + """The interlock tripped (light curtain broken, or tripped by the host), so the board stopped or + refused the move.""" + + +class NotConfiguredError(AceError): + """The axis has no motor table loaded: the board was powered up, or the drive lost its + parameters, since the last Configure.""" + + +class NotEnabledError(AceError): + """The axis is configured but disabled (Set State ENABLED has not been sent since).""" + + +class NotHomedError(AceError): + """The axis has not been homed since the board started.""" + + +class MotionError(AceError): + """A move did not complete: the axis left its error window, or a coordinated move failed.""" + + +# The ACE error a board answers when the interlock is tripped. +INTERLOCK_TRIPPED_CODE = 0x0F + +_ERROR_CLASSES = { + INTERLOCK_TRIPPED_CODE: InterlockTrippedError, + 0x30: NotConfiguredError, + 0x31: NotEnabledError, + 0x32: NotHomedError, + 0x38: MotionError, + 0x3C: MotionError, +} + + +def ace_error( + code: int, + device_error: Optional[int], + request: str, + device: Optional[int] = None, + index: Optional[int] = None, +) -> AceError: + """Build the exception for an ACE error code.""" + return _ERROR_CLASSES.get(code, AceError)(code, device_error, request, device, index) + + +# The errors the Master Controller reports as one axis's motion failing (not enabled, homing failed, operational parameters exceeded, error window exceeded, framing +# error, controller error; only those with a known number here). +_MOTION_FAILED_CODES = {0x31, 0x3C} +COORDINATED_MOTION_FAILED_CODE = 0x38 + + +def english(error: AceError, axis_names: Mapping[Tuple[int, int], str]) -> str: + """What the Master Controller replies for a command that failed with `error`, as its logs show + it, with each axis named by `axis_names` ((device, index) -> + name): + + - not homed: "The instrument needs to be homed."; + - interlock tripped: "A light curtain violation has occurred."; + - a coordinated move failed: "The motion failed: ." for each axis that reported; + - an axis's own motion error: the same, for that axis; + - anything else: " failed: ". + """ + + def motion_failed(e: AceError) -> str: + name = axis_names.get((e.device, e.index)) if e.device is not None else None # type: ignore[arg-type] + return f"The {name or e.request} motion failed: {e.reason}." + + if isinstance(error, NotHomedError): + return "The instrument needs to be homed." + if isinstance(error, InterlockTrippedError): + return "A light curtain violation has occurred." + if error.code == COORDINATED_MOTION_FAILED_CODE and error.axis_errors: + return " ".join(motion_failed(e) for e in error.axis_errors) + if error.code in _MOTION_FAILED_CODES and error.device is not None: + return motion_failed(error) + return f"{error.request} failed: {error.reason}." diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/errors_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/errors_tests.py new file mode 100644 index 00000000000..fa88302e947 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/errors_tests.py @@ -0,0 +1,41 @@ +"""Board errors as the Master Controller words them in its replies, as its logs show them.""" + +import unittest + +from pylabrobot.beckman_coulter.biomek_i7.driver.errors import ace_error, english + +NAMES = {(0x11, 1): "left X", (0x11, 3): "left Z"} + + +class EnglishTests(unittest.TestCase): + def test_not_homed_and_interlock(self) -> None: + self.assertEqual( + english(ace_error(0x32, None, "Set X Move Parameters"), NAMES), + "The instrument needs to be homed.", + ) + self.assertEqual( + english(ace_error(0x0F, None, "Move All"), NAMES), + "A light curtain violation has occurred.", + ) + + def test_a_coordinated_move_names_each_axis_that_failed(self) -> None: + error = ace_error(0x38, None, "Move All", 0x10, 0) + error.axis_errors = [ + ace_error(0x3C, 0x0100, "device 0x11 index 1", 0x11, 1), + ace_error(0x3C, None, "device 0x11 index 3", 0x11, 3), + ] + self.assertEqual( + english(error, NAMES), + "The left X motion failed: motion error window exceeded. " + "The left Z motion failed: motion error window exceeded.", + ) + + def test_an_axis_error_and_anything_else(self) -> None: + self.assertEqual( + english(ace_error(0x31, None, "Move", 0x11, 1), NAMES), + "The left X motion failed: motion device not enabled.", + ) + self.assertEqual( + english(ace_error(0x0A, None, "Get Tip Status"), NAMES), + "Get Tip Status failed: ACE error 0x0A.", + ) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/features/__init__.py b/pylabrobot/beckman_coulter/biomek_i7/driver/features/__init__.py new file mode 100644 index 00000000000..fc83f97406e --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/features/__init__.py @@ -0,0 +1 @@ +"""What a Biomek i7 is fitted with: the chassis, and a pod per side (`pod.py`, STAR's X-arm).""" diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/features/chassis.py b/pylabrobot/beckman_coulter/biomek_i7/driver/features/chassis.py new file mode 100644 index 00000000000..df4974fd77a --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/features/chassis.py @@ -0,0 +1,67 @@ +"""The chassis module: its inputs and outputs, the legacy deck devices it lists, and the interlock's +state.""" + +from typing import Dict, List, Optional + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ModuleConfiguration +from pylabrobot.beckman_coulter.biomek_i7.driver.module import ( + read_analog_inputs, + read_module, +) + + +class Chassis: + """The chassis's ACE module. Reached as `driver.chassis`.""" + + def __init__(self, board: AceBoard): + self.board = board + self.configuration: Optional[ModuleConfiguration] = None + + async def discover(self) -> ModuleConfiguration: + """Read what the chassis says about itself. Moves nothing.""" + self.configuration = await read_module(self.board) + return self.configuration + + def _require_configuration(self) -> ModuleConfiguration: + if self.configuration is None: + raise RuntimeError("the chassis has not been read; call `discover()` or `setup()` first") + return self.configuration + + async def request_analog_inputs(self) -> Dict[str, float]: + """Every analog input (supply voltages, temperature...) by name, in its units.""" + return await read_analog_inputs(self.board, self._require_configuration()) + + async def request_digital_inputs(self) -> Dict[str, int]: + config = self._require_configuration() + replies = await self.board.send_many( + [p.read_input_output(p.Device.DIGITAL_INPUT, i) for i in config.digital_inputs] + ) + return {config.digital_inputs[i]: r.payload[0] for i, r in zip(config.digital_inputs, replies)} + + async def request_digital_outputs(self) -> Dict[str, int]: + config = self._require_configuration() + replies = await self.board.send_many( + [p.read_input_output(p.Device.DIGITAL_OUTPUT, i) for i in config.digital_outputs] + ) + return { + config.digital_outputs[i]: r.payload[0] for i, r in zip(config.digital_outputs, replies) + } + + async def request_legacy_alp_devices(self) -> List[bytes]: + """The legacy ALP devices the chassis lists, as the raw entries it answers.""" + payload = (await self.board.send(p.list_legacy_alp_devices())).payload + return [payload[i : i + 2] for i in range(0, len(payload), 2)] + + # -- interlock ------------------------------------------------------------- + # The interlock cuts the arms' drive power when the light curtain is broken or the host trips it; + # nothing moves while it is tripped. Here it is only read. + + async def request_interlock_state(self) -> p.InterlockState: + """`armed` (the drives may have power) or `tripped`. Moves nothing. + + Biomek's logs never show the Master Controller sending Get Interlock Status. The request only + reads the state; it changes nothing. + """ + return p.parse_interlock_status((await self.board.send(p.get_interlock_status())).payload) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py b/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py new file mode 100644 index 00000000000..d23b667f1fa --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py @@ -0,0 +1,77 @@ +"""One pod: an arm on the shared X rail, and its ACE module.""" + +from typing import Dict, Literal, Optional, Tuple + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ModuleConfiguration +from pylabrobot.beckman_coulter.biomek_i7.driver.module import ( + read_analog_inputs, + read_module, +) + +# How Biomek numbers its pods. Pod1 is the left pod and Pod2 the right on the instrument this +# driver was written against; whether that holds on every build is not established. +POD_NUMBERS = {"left": 1, "right": 2} +COMPONENT_PREFIXES = {"multichannel": "MC", "span8": "SPAN8"} + +# The arm board's analog input carrying the interlocked motor supply ("+36V Interlock"). +DRIVE_SUPPLY_INPUT = "+36V Interlock" + + +class Pod: + """One pod. Reached as `driver.left_x_arm` / `driver.right_x_arm`: it fills the slot of STAR's + `XArm`, though more of the instrument hangs on it. One board drives its X, Y and Z, its head + or channels and its gripper. + + `module_type` is what the board reports itself to be (Get Module ID): `multichannel` (a + 96-channel head) or `span8` (eight independent channels). + """ + + def __init__(self, board: AceBoard, side: Literal["left", "right"], module_type: str): + self.board = board + self.side = side + self.module_type = module_type + self.configuration: Optional[ModuleConfiguration] = None + + @property + def pod_number(self) -> int: + return POD_NUMBERS[self.side] + + def __str__(self) -> str: + return f"{self.side} pod (Pod{self.pod_number}, {self.module_type})" + + @property + def component(self) -> str: + """The name Biomek gives this pod's component in its logs (`host_command.component`): + `MC_1`, `SPAN8_2`.""" + return f"{COMPONENT_PREFIXES[self.module_type]}_{self.pod_number}" + + async def discover(self) -> ModuleConfiguration: + """Read what the pod's module says about itself. Moves nothing.""" + self.configuration = await read_module(self.board) + return self.configuration + + async def request_drive_supply(self) -> float: + """The pod's interlocked motor supply, in volts: about 36 with the interlock armed, about 0.1 + tripped. Moves nothing. + + Raises: + RuntimeError: if the pod has no input named for it. + """ + if self.configuration is None: + raise RuntimeError(f"{self} has not been read; call `discover()` or `setup()` first") + for index, name in self.configuration.analog_inputs.items(): + if name.startswith(DRIVE_SUPPLY_INPUT): + reply = await self.board.send(p.read_input_output(p.Device.ANALOG_INPUT, index)) + return p.parse_float(reply.payload) + raise RuntimeError(f"{self} has no {DRIVE_SUPPLY_INPUT!r} analog input") + + async def request_accuframe_offsets(self) -> Tuple[float, float, float]: + """The X, Y and Z offsets the pod's AccuFrame board holds.""" + return p.parse_accuframe_offsets((await self.board.send(p.get_accuframe_offsets())).payload) + + async def request_analog_inputs(self) -> Dict[str, float]: + if self.configuration is None: + raise RuntimeError(f"{self} has not been read; call `discover()` or `setup()` first") + return await read_analog_inputs(self.board, self.configuration) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/framing.py b/pylabrobot/beckman_coulter/biomek_i7/driver/framing.py new file mode 100644 index 00000000000..5407f0f16c6 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/framing.py @@ -0,0 +1,100 @@ +"""ACE framing: how messages travel in the Biomek i7's USB transfers. + +Every message travels as a frame, a length byte followed by that many message bytes:: + + length (1) | message (length) + +The host packs one or more frames into an interrupt OUT transfer on endpoint 0x02 (32-byte +packets) and sends no zero-length packet after one that fills its last packet. A board sends one +frame per interrupt IN transfer on endpoint 0x81 (16-byte packets); a frame longer than 15 bytes +spans several packets. Established on a cold start captured with USBPcap, 2026-10-24: all 3,507 +transfers split into whole frames. +""" + +from typing import Iterable, List + +from pylabrobot.beckman_coulter.biomek_i7.driver.errors import FrameError + +# The largest OUT transfer the Master Controller sent in the captured cold start. Larger ones are +# not known to be accepted, so frames are packed no further than this. +MAX_OUT_TRANSFER = 253 + +# The IN endpoint's packet size: one read returns at most one packet. +IN_PACKET_SIZE = 16 + + +def frame(message: bytes) -> bytes: + """Prefix one message with its length byte. + + Raises: + ValueError: if the message is empty or longer than 255 bytes. + """ + if not 0 < len(message) <= 0xFF: + raise ValueError(f"an ACE message is 1-255 bytes, got {len(message)}") + return bytes([len(message)]) + message + + +def pack(messages: Iterable[bytes], max_transfer: int = MAX_OUT_TRANSFER) -> List[bytes]: + """Pack messages, in order, into as few OUT transfers as fit `max_transfer` bytes each.""" + transfers: List[bytes] = [] + current = b"" + for message in messages: + framed = frame(message) + if len(framed) > max_transfer: + raise ValueError(f"a {len(framed)}-byte frame does not fit a {max_transfer}-byte transfer") + if len(current) + len(framed) > max_transfer: + transfers.append(current) + current = b"" + current += framed + if current: + transfers.append(current) + return transfers + + +def split(transfer: bytes) -> List[bytes]: + """Split one whole transfer into its messages. + + Raises: + FrameError: if the transfer does not end on a frame boundary, or holds an empty frame. + """ + reader = FrameReader() + messages = reader.feed(transfer) + if reader.pending: + raise FrameError(f"transfer ends inside a frame: {transfer.hex()}") + return messages + + +class FrameReader: + """Reassemble frames from IN packets, which may end anywhere inside a frame.""" + + def __init__(self) -> None: + self._buffer = bytearray() + + @property + def pending(self) -> int: + """How many bytes of an unfinished frame are held.""" + return len(self._buffer) + + def feed(self, data: bytes) -> List[bytes]: + """Take the next bytes read and return every message they complete. + + Raises: + FrameError: on a zero length byte, which no board sends and which would never advance. + """ + self._buffer += data + messages: List[bytes] = [] + while self._buffer: + length = self._buffer[0] + if length == 0: + bad = bytes(self._buffer) + self._buffer.clear() + raise FrameError(f"zero-length frame in {bad.hex()}") + if len(self._buffer) < length + 1: + break + messages.append(bytes(self._buffer[1 : length + 1])) + del self._buffer[: length + 1] + return messages + + def reset(self) -> None: + """Drop an unfinished frame, as after a read error.""" + self._buffer.clear() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/framing_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/framing_tests.py new file mode 100644 index 00000000000..bb4663ce5ee --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/framing_tests.py @@ -0,0 +1,118 @@ +"""ACE framing: length-prefixed messages, packed into OUT transfers and read back from 16-byte IN +packets.""" + +import random +import unittest +from typing import List + +from pylabrobot.beckman_coulter.biomek_i7.driver.errors import FrameError +from pylabrobot.beckman_coulter.biomek_i7.driver.framing import ( + IN_PACKET_SIZE, + MAX_OUT_TRANSFER, + FrameReader, + frame, + pack, + split, +) + +# Transfers from a captured cold start, each as it went over the wire: three Set Move Parameters +# packed into one OUT transfer, and three answers, each its own IN transfer, the last longer than a +# packet (an analog input's name, "Temperature"). +CAPTURED_OUT = ( + "1b1101001840150000001f0000003201000000000000038c00000000" + "1b1105001940030f0100298301009b1f0f000000000013f900000000" + "1b1102001a40b86f0200077b030044ce2200000000008a9100000000" +) +CAPTURED_IN = [ + "09000000010002008000", + "0902010007030200e500", + "122209000b01020054656d7065726174757265", +] + + +def messages(rng: random.Random, count: int) -> List[bytes]: + return [bytes(rng.randrange(256) for _ in range(rng.randrange(1, 256))) for _ in range(count)] + + +class CapturedTransferTests(unittest.TestCase): + def test_a_packed_out_transfer_splits_into_its_requests(self) -> None: + data = bytes.fromhex(CAPTURED_OUT) + requests = split(data) + self.assertEqual([(m[0], m[1], m[3], m[4]) for m in requests], + [(0x11, 1, 0x18, 0x40), (0x11, 5, 0x19, 0x40), (0x11, 2, 0x1A, 0x40)]) # fmt: skip + self.assertEqual(pack(requests), [data]) + + def test_in_transfers_hold_one_frame_each(self) -> None: + for hex_data in CAPTURED_IN: + data = bytes.fromhex(hex_data) + (message,) = split(data) + self.assertEqual(frame(message), data) + + +class InverseTests(unittest.TestCase): + """Framing and splitting undo each other, for any messages.""" + + def setUp(self) -> None: + self.rng = random.Random(11) + + def test_frame_then_split(self) -> None: + for message in messages(self.rng, 200) + [b"\x00", b"\xff" * 255]: + self.assertEqual(split(frame(message)), [message]) + + def test_pack_then_split_keeps_order_and_fits(self) -> None: + for _ in range(50): + batch = [m[: MAX_OUT_TRANSFER - 1] for m in messages(self.rng, self.rng.randrange(1, 12))] + transfers = pack(batch) + self.assertTrue(all(len(t) <= MAX_OUT_TRANSFER for t in transfers)) + self.assertEqual([m for t in transfers for m in split(t)], batch) + + def test_frames_reassemble_from_packets(self) -> None: + """Read packet by packet, as the board's reader does, the frames come out unchanged.""" + reader = FrameReader() + for message in messages(self.rng, 200): + data = frame(message) + out: List[bytes] = [] + for i in range(0, len(data), IN_PACKET_SIZE): + out += reader.feed(data[i : i + IN_PACKET_SIZE]) + self.assertEqual(out, [message]) + self.assertEqual(reader.pending, 0) + + def test_frames_reassemble_from_any_cut(self) -> None: + stream = b"".join(frame(m) for m in messages(self.rng, 20)) + for _ in range(20): + reader = FrameReader() + cuts = sorted(self.rng.sample(range(1, len(stream)), 15)) + out: List[bytes] = [] + for a, b in zip([0] + cuts, cuts + [len(stream)]): + out += reader.feed(stream[a:b]) + self.assertEqual(out, split(stream)) + + +class PackTests(unittest.TestCase): + def test_packs_in_order_until_the_transfer_is_full(self) -> None: + messages = [bytes([i]) * 100 for i in range(3)] + transfers = pack(messages) + self.assertEqual(transfers, [frame(messages[0]) + frame(messages[1]), frame(messages[2])]) + self.assertTrue(all(len(t) <= MAX_OUT_TRANSFER for t in transfers)) + + def test_rejects_empty_and_oversized_messages(self) -> None: + with self.assertRaises(ValueError): + frame(b"") + with self.assertRaises(ValueError): + frame(b"x" * 256) + with self.assertRaises(ValueError): + pack([b"x" * 255]) # a frame larger than a transfer + + def test_split_rejects_a_truncated_transfer(self) -> None: + with self.assertRaises(FrameError): + split(bytes([5, 1, 2])) + + def test_zero_length_frame_is_an_error(self) -> None: + reader = FrameReader() + with self.assertRaises(FrameError): + reader.feed(b"\x00\x01") + self.assertEqual(reader.pending, 0) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/master.py b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py new file mode 100644 index 00000000000..21b0e1b98b8 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py @@ -0,0 +1,225 @@ +"""BiomekI7Driver: finds the instrument's ACE boards, works out what each one is, and owns them. + +A Biomek i7 shows up as one USB device per ACE module: the chassis, and one per arm. Which is which +is not fixed by USB order or serial number, so setup opens every ACE device, asks each its module +ID (its type, and an arm's side), and builds the chassis and a pod per arm from the answers. Only one +program can hold an ACE board at a time: Biomek's Master Controller must not be running. +""" + +import logging +from typing import Dict, List, Optional, Sequence, Tuple, Union + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.board import ( + ACE_PRODUCT_ID, + ACE_VENDOR_ID, + AceBoard, +) +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ModuleConfiguration +from pylabrobot.beckman_coulter.biomek_i7.driver.features.chassis import Chassis +from pylabrobot.beckman_coulter.biomek_i7.driver.features.pod import Pod +from pylabrobot.io.usb import USB + +logger = logging.getLogger(__name__) + + +def find_ace_boards() -> Dict[str, int]: + """Every ACE board attached: its USB serial number and current USB address. + + Reading a serial number opens the device; the handle is released straight after, because a + WinUSB device admits one open handle at a time. + """ + import usb.util # optional dependency, as in pylabrobot.io.usb + + boards: Dict[str, int] = {} + for device in USB(ACE_VENDOR_ID, ACE_PRODUCT_ID, "ACE board").get_available_devices(): + try: + boards[str(device.serial_number)] = device.address + finally: + usb.util.dispose_resources(device) + return boards + + +class BiomekI7Driver: + """The Biomek i7's ACE boards, as a chassis and up to two pods.""" + + def __init__( + self, + serial_numbers: Optional[Sequence[str]] = None, + boards: Optional[Sequence[AceBoard]] = None, + ): + """ + Args: + serial_numbers: the ACE boards' USB serial numbers. Defaults to every ACE board attached. + boards: boards to use instead of opening USB devices: a simulated instrument + (`simulator.replay_boards`). + """ + self._serial_numbers = list(serial_numbers) if serial_numbers is not None else None + self._given_boards = list(boards) if boards is not None else None + self.boards: List[AceBoard] = [] + self._connected = False + self.chassis: Optional[Chassis] = None + # The pods, named as STAR names its X-arms: each fills an X-arm's slot (design.md, Feature map). + self.left_x_arm: Optional[Pod] = None + self.right_x_arm: Optional[Pod] = None + + # -- lifecycle ------------------------------------------------------------- + + async def setup(self) -> None: + """Connect to the instrument and find out what it is. Reads only: nothing is written to a + board and nothing moves. Repeatable: the boards stay open, and discovery reads them again. A + setup that fails part way releases the boards. + + Raises: + RuntimeError: if no chassis is found, or a board cannot be placed (`discover`). + """ + logger.warning( + "The Biomek i7 driver's discovery has run on one instrument; it is untested on other " + "instruments. Please report what works and what does not." + ) + if not self._connected: + await self._open() + try: + await self.discover() + except BaseException: + await self.stop() + raise + + async def _open(self) -> None: + """Open every ACE board and start reading it.""" + if self._given_boards is not None: + self.boards = list(self._given_boards) + else: + found = find_ace_boards() + if not found: + raise RuntimeError("no ACE boards (USB 0AB5:ACE0) found") + serials = self._serial_numbers or sorted(found) + missing = [s for s in serials if s not in found] + if missing: + raise RuntimeError(f"ACE boards {missing} not found; attached: {sorted(found)}") + # Opened by the address just enumerated: matching on serial number would open each device + # again to read its descriptor. + self.boards = [AceBoard(device_address=found[s], name=f"ACE {s}") for s in serials] + for board, serial in zip(self.boards, serials): + board.usb_serial_number = serial + self._connected = True + for board in self.boards: + await board.setup() + + async def discover(self) -> None: + """Work out which board is which, then read each module, chassis first. Moves nothing, arms + nothing and writes nothing: it opens the boards if `setup` has not, and can be called on its + own. + + Each board says what it is: Get Module ID answers a module type (`protocol.MODULE_TYPES`: + chassis, Multichannel, Span-8) and a side (left, right). That, not its USB serial number or + order, places it. Seen on one instrument; an unknown type or side, two boards claiming one + place, or no chassis is refused. + + Raises: + RuntimeError: for a board this driver cannot place, or no chassis. + """ + if not self._connected: + await self._open() + places: Dict[str, AceBoard] = {} + types: Dict[str, str] = {} + for board in self.boards: + module = p.parse_module_id((await board.send(p.get_module_id())).payload) + if module.type is None: + raise RuntimeError( + f"{board.name}: module type 0x{module.type_code:02X} is not one this driver knows" + ) + place = "chassis" if module.type == "chassis" else str(module.side) + if place in places: + raise RuntimeError( + f"{board.name} and {places[place].name} both report themselves as {place}" + ) + if place not in ("chassis", "left", "right"): + raise RuntimeError( + f"{board.name}: {module.type} module reports side 0x{module.side_code:02X}" + ) + places[place] = board + types[place] = module.type + if "chassis" not in places: + raise RuntimeError("no chassis module among the ACE boards") + self.chassis = Chassis(places["chassis"]) + self.left_x_arm = Pod(places["left"], "left", types["left"]) if "left" in places else None + self.right_x_arm = Pod(places["right"], "right", types["right"]) if "right" in places else None + modules: List[Tuple[str, ModuleConfiguration]] = [("chassis", await self.chassis.discover())] + for pod in self.arms: + modules.append((str(pod), await pod.discover())) + logger.info( + "found %s, module %s", pod, pod.configuration.serial_number if pod.configuration else "?" + ) + for name, found in modules: + untested = found.untested_firmware() + if untested: + logger.warning( + "%s runs firmware this driver has not been run against: %s", name, "; ".join(untested) + ) + + async def request_serial_numbers(self) -> Dict[str, Optional[str]]: + """The serial numbers the modules report: `chassis`, and `left` / `right` for each pod found. + Moves nothing. + + Raises: + RuntimeError: before discovery (`discover` or `setup`). + """ + return self._serial_numbers_found() + + def _serial_numbers_found(self) -> Dict[str, Optional[str]]: + if self.chassis is None or self.chassis.configuration is None: + raise RuntimeError("the modules have not been read; call `discover()` or `setup()` first") + found: Dict[str, Optional[str]] = {"chassis": self.chassis.configuration.serial_number} + for pod in self.arms: + found[pod.side] = pod.configuration.serial_number if pod.configuration else None + return found + + async def stop(self) -> None: + """Release every board. Writes nothing and moves nothing.""" + for board in self.boards: + try: + await board.stop() + except Exception: + logger.exception("failed to release %s", board.name) + self._connected = False + + # -- what the instrument has ------------------------------------------------ + + @property + def arms(self) -> List[Pod]: + """The pods this instrument has, left first (STAR's `arms`).""" + return [pod for pod in (self.left_x_arm, self.right_x_arm) if pod is not None] + + @property + def x_arm(self) -> Pod: + """The pod, on an instrument with one (STAR's `x_arm`). + + Raises: + RuntimeError: before discovery, when which pods are fitted is not yet known. + ValueError: with no pod, or two; reach two as `left_x_arm` and `right_x_arm`. + """ + if self.chassis is None: + raise RuntimeError("the instrument has not been read; call `discover()` or `setup()` first") + arms = self.arms + if not arms: + raise ValueError("this instrument has no pod") + if len(arms) > 1: + raise ValueError( + "this instrument has two pods, so `x_arm` is ambiguous - reach it through " + "`left_x_arm` or `right_x_arm`." + ) + return arms[0] + + def arm(self, name: Union[str, int]) -> Pod: + """A pod by any name it goes by: its side (`"left"`), Biomek's number (`1`, `"Pod1"`), or + Biomek's component name in its logs (`"MC_1"`). For porting Biomek methods and logs, which + name pods by number; the driver itself names them by side. + + Raises: + KeyError: if no pod goes by that name. + """ + for pod in self.arms: + if name in (pod.side, pod.pod_number, f"Pod{pod.pod_number}", pod.component): + return pod + raise KeyError(f"no pod {name!r}; have {[(p.side, p.component) for p in self.arms]}") diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/master_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/master_tests.py new file mode 100644 index 00000000000..2df0cea1da8 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/master_tests.py @@ -0,0 +1,218 @@ +"""Discovery on a replayed instrument: each board placed by what it says it is, then read.""" + +import asyncio +import itertools +import unittest +from typing import Any, Dict, List + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.features.chassis import Chassis +from pylabrobot.beckman_coulter.biomek_i7.driver.simulator import ReplayAceUSB +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import ( + generic_boards, + generic_driver, + generic_recording, +) + +# The commands that only read: discovery sends nothing else. +READS = {name for name in p.COMMANDS.values() if name.startswith(("Get ", "Read ", "List "))} + + +def answer(recording: Dict[str, Any], module: str, key: str, reply: str) -> None: + """Have `module` answer the request `key` (its bytes less the sequence) with `reply`.""" + entries: List[List[Any]] = recording["boards"][module] + for entry in entries: + if entry[0] == key: + entry[1] = [reply] + return + entries.append([key, [reply]]) + + +def module_id(recording: Dict[str, Any], module: str, type_code: int, side_code: int) -> None: + answer(recording, module, "00000000", f"00000000000200{type_code:02X}{side_code:02X}") + + +class ReplayedTestCase(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + asyncio.get_running_loop().set_debug(False) # the test loop's debug mode makes replays slow + + +class PlacementTests(ReplayedTestCase): + async def test_boards_are_placed_by_what_they_say_in_any_order(self) -> None: + for order in itertools.permutations(["chassis", "multichannel", "span8"]): + with self.subTest(order=order): + driver = generic_driver(generic_boards(modules=order)) + await driver.discover() + try: + self.assertIsNotNone(driver.chassis) + assert driver.chassis is not None and driver.left_x_arm and driver.right_x_arm + self.assertEqual(driver.chassis.board.name, "replayed chassis") + self.assertEqual(driver.left_x_arm.board.name, "replayed multichannel") + self.assertEqual(driver.right_x_arm.board.name, "replayed span8") + finally: + await driver.stop() + left, right = driver.left_x_arm, driver.right_x_arm + assert left is not None and right is not None + self.assertEqual(str(left), "left pod (Pod1, multichannel)") + self.assertEqual((left.component, left.pod_number), ("MC_1", 1)) + self.assertEqual((right.component, right.pod_number), ("SPAN8_2", 2)) + self.assertEqual(driver.arms, [left, right]) + + async def test_two_boards_in_one_place_are_refused(self) -> None: + recording = generic_recording() + module_id(recording, "span8", 0xFB, 0x01) # a second left pod + driver = generic_driver(generic_boards(recording)) + with self.assertRaisesRegex(RuntimeError, "replayed span8 and replayed multichannel both"): + await driver.discover() + await driver.stop() + + async def test_no_chassis_is_refused(self) -> None: + driver = generic_driver(generic_boards(modules=["multichannel", "span8"])) + with self.assertRaisesRegex(RuntimeError, "no chassis"): + await driver.discover() + await driver.stop() + + async def test_an_unknown_module_type_is_refused(self) -> None: + recording = generic_recording() + module_id(recording, "span8", 0x42, 0x02) + driver = generic_driver(generic_boards(recording)) + with self.assertRaisesRegex(RuntimeError, "module type 0x42"): + await driver.discover() + await driver.stop() + + async def test_an_unknown_side_is_refused(self) -> None: + recording = generic_recording() + module_id(recording, "span8", 0xFB, 0x07) + driver = generic_driver(generic_boards(recording)) + with self.assertRaisesRegex(RuntimeError, "side 0x07"): + await driver.discover() + await driver.stop() + + async def test_setup_releases_the_boards_when_discovery_fails(self) -> None: + boards = generic_boards(modules=["multichannel", "span8"]) + with self.assertRaisesRegex(RuntimeError, "no chassis"): + await generic_driver(boards).setup() + self.assertFalse(any(board.connected for board in boards)) + + +class PodNameTests(ReplayedTestCase): + async def test_one_pod(self) -> None: + driver = generic_driver(generic_boards(modules=["chassis", "span8"])) + with self.assertRaisesRegex(RuntimeError, "discover"): + driver.x_arm + await driver.discover() + self.assertIsNone(driver.left_x_arm) + self.assertIs(driver.x_arm, driver.right_x_arm) + await driver.stop() + + async def test_two_pods(self) -> None: + driver = generic_driver() + await driver.discover() + with self.assertRaisesRegex(ValueError, "left_x_arm"): + driver.x_arm + for name in ("left", 1, "Pod1", "MC_1"): + self.assertIs(driver.arm(name), driver.left_x_arm) + for name in ("right", 2, "Pod2", "SPAN8_2"): + self.assertIs(driver.arm(name), driver.right_x_arm) + with self.assertRaises(KeyError): + driver.arm("MC_2") + await driver.stop() + + +class ReadTests(ReplayedTestCase): + async def asyncSetUp(self) -> None: + await super().asyncSetUp() + self.boards = generic_boards() + self.driver = generic_driver(self.boards) + + async def asyncTearDown(self) -> None: + await self.driver.stop() + + async def test_discovery_on_its_own_opens_the_boards_and_only_reads(self) -> None: + await self.driver.discover() + self.assertTrue(all(board.connected for board in self.boards)) + for board in self.boards: + assert isinstance(board.io, ReplayAceUSB) + self.assertEqual(board.io.unanswered, [], board.name) + sent = {p.COMMANDS[(m[0], m[4])] for m in board.io.requests} + self.assertLessEqual(sent, READS, board.name) + + async def test_serial_numbers(self) -> None: + with self.assertRaisesRegex(RuntimeError, "discover"): + await self.driver.request_serial_numbers() + await self.driver.discover() + serials = await self.driver.request_serial_numbers() + self.assertEqual(set(serials), {"chassis", "left", "right"}) + for serial in serials.values(): + assert serial is not None + self.assertTrue(serial.startswith("SIMULATED"), serial) + self.assertEqual(len(set(serials.values())), 3) + + async def test_each_modules_boards_and_inputs(self) -> None: + await self.driver.discover() + chassis, left, right = self.driver.chassis, self.driver.left_x_arm, self.driver.right_x_arm + assert chassis and chassis.configuration and left and left.configuration + assert right and right.configuration + self.assertEqual(chassis.configuration.module_id.type, "chassis") + self.assertEqual(chassis.configuration.digital_inputs[1], "Door Sensor") + self.assertEqual(chassis.configuration.analog_units[9], "deg. C") + self.assertEqual( + [b.index for b in left.configuration.boards], + list(range(len(left.configuration.boards), 0, -1)), # highest index first + ) + self.assertTrue(any(b.hardware.name == "AccuFrame" for b in left.configuration.boards)) + self.assertEqual(right.configuration.untested_firmware(), []) + + async def test_sensor_reads(self) -> None: + await self.driver.discover() + chassis, left, right = self.driver.chassis, self.driver.left_x_arm, self.driver.right_x_arm + assert chassis and left and right + analog = await chassis.request_analog_inputs() + self.assertIn("Temperature", analog) + self.assertEqual(set(await chassis.request_digital_inputs()), {"Door Sensor"}) + self.assertEqual(len(await chassis.request_digital_outputs()), 1) + self.assertIsInstance(await chassis.request_legacy_alp_devices(), list) + for pod in (left, right): + # The recording answers as the instrument did when it was made, with the interlock armed. + self.assertGreater(await pod.request_drive_supply(), 30.0) + self.assertIn("+36V Interlock", await pod.request_analog_inputs()) + self.assertEqual(len(await left.request_accuframe_offsets()), 3) + + async def test_untested_firmware_is_warned_about(self) -> None: + with self.assertNoLogs("pylabrobot.beckman_coulter.biomek_i7.driver.master", "WARNING"): + await self.driver.discover() + recording = generic_recording() + answer(recording, "span8", "00000012", "000000001202" + "00EFBEADDE") + driver = generic_driver(generic_boards(recording)) + with self.assertLogs("pylabrobot.beckman_coulter.biomek_i7.driver.master", "WARNING") as logs: + await driver.discover() + await driver.stop() + self.assertIn("module image CRC 0xdeadbeef", "\n".join(logs.output)) + + async def test_stop_releases_the_boards_and_discovery_runs_again(self) -> None: + await self.driver.discover() + await self.driver.stop() + self.assertFalse(any(board.connected for board in self.boards)) + await self.driver.discover() + self.assertTrue(all(board.connected for board in self.boards)) + + +class InterlockStateTests(unittest.IsolatedAsyncioTestCase): + """Get Interlock Status, which the Master Controller never sends, answers the interlock's byte + (read on the instrument 2026-11-09: `FF` tripped, `00` armed).""" + + async def test_states(self) -> None: + for byte, state in (("FF", "tripped"), ("00", "armed")): + board = AceBoard( + io=ReplayAceUSB({"01010010": ["0101000010" + "0200" + byte]}), default_timeout=0.3 + ) + await board.setup() + try: + self.assertEqual(await Chassis(board).request_interlock_state(), state) + finally: + await board.stop() + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/module.py b/pylabrobot/beckman_coulter/biomek_i7/driver/module.py new file mode 100644 index 00000000000..3956e87bfd8 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/module.py @@ -0,0 +1,72 @@ +"""Reading what an ACE module says about itself: identity, its boards, and its inputs. + +The order follows the Master Controller's cold start: the module, then each of its boards from +the highest index down (a motion board's serial number and firmware image, any other board's +application version), then the names of its inputs and outputs. Nothing here moves or writes. +""" + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import BoardInfo, ModuleConfiguration + +# Board kinds whose identity is a serial number and firmware image; every other kind reports an +# application version. AccuFrame boards are left at their hardware version. +_IMAGE_BOARDS = {0x00} +_ACCUFRAME = 0xE3 + + +async def read_module(board: AceBoard) -> ModuleConfiguration: + """Read a module's identity, board inventory and input/output names.""" + module_id = p.parse_module_id((await board.send(p.get_module_id())).payload) + hardware = p.parse_hardware_version((await board.send(p.get_module_hardware_version())).payload) + serial = p.parse_string((await board.send(p.get_module_serial_number())).payload) + crc = p.parse_u32((await board.send(p.get_module_application_image_crc())).payload) + length = p.parse_u32((await board.send(p.get_module_application_image_length())).payload) + counts = p.parse_device_count((await board.send(p.get_module_device_count())).payload) + usb_serial = board.usb_serial_number + config = ModuleConfiguration(module_id, usb_serial, serial, hardware, crc, length, counts) + + for index in range(counts.get(p.Device.BOARD, 0), 0, -1): + info = BoardInfo( + index, + p.parse_hardware_version((await board.send(p.get_board_hardware_version(index))).payload), + ) + if info.hardware.type_code in _IMAGE_BOARDS: + info.serial_number = p.parse_string( + (await board.send(p.get_board_serial_number(index))).payload + ) + info.application_crc = p.parse_u32( + (await board.send(p.get_board_application_image_crc(index))).payload + ) + info.application_length = p.parse_u32( + (await board.send(p.get_board_application_image_length(index))).payload + ) + elif info.hardware.type_code != _ACCUFRAME: + info.application_version = p.parse_string( + (await board.send(p.get_board_application_version(index))).payload + ) + config.boards.append(info) + + io_counts = p.parse_device_count((await board.send(p.get_io_service_device_count())).payload) + for index in range(1, io_counts.get(p.Device.ANALOG_INPUT, 0) + 1): + name = await board.send(p.get_input_output_name(p.Device.ANALOG_INPUT, index)) + units = await board.send(p.get_analog_input_units(index)) + config.analog_inputs[index] = p.parse_string(name.payload) + config.analog_units[index] = p.parse_string(units.payload) + for index in range(1, io_counts.get(p.Device.DIGITAL_INPUT, 0) + 1): + name = await board.send(p.get_input_output_name(p.Device.DIGITAL_INPUT, index)) + config.digital_inputs[index] = p.parse_string(name.payload) + for index in range(1, io_counts.get(p.Device.DIGITAL_OUTPUT, 0) + 1): + name = await board.send(p.get_input_output_name(p.Device.DIGITAL_OUTPUT, index)) + config.digital_outputs[index] = p.parse_string(name.payload) + return config + + +async def read_analog_inputs(board: AceBoard, config: ModuleConfiguration) -> dict: + """Every analog input's value, by name, in its units.""" + replies = await board.send_many( + [p.read_input_output(p.Device.ANALOG_INPUT, i) for i in config.analog_inputs] + ) + return { + config.analog_inputs[i]: p.parse_float(r.payload) for i, r in zip(config.analog_inputs, replies) + } diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/protocol.py b/pylabrobot/beckman_coulter/biomek_i7/driver/protocol.py new file mode 100644 index 00000000000..63b78df4497 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/protocol.py @@ -0,0 +1,711 @@ +"""ACE messages: what the Biomek i7's boards are sent and what they answer. + +A request is a 5-byte header and its parameters, little-endian:: + + device (1) | index (1) | 0x00 | sequence (1) | opcode (1) | parameters + +`device` names the kind of thing addressed on the board (the module itself, one of its boards, a +motor, a syringe pump, an input...), `index` which one of them, and `opcode` the operation, whose +meaning depends on `device`. A board answers with the same header, then a status byte and the +status's data:: + + device | index | 0x00 | sequence | opcode | status (1) | data + +A command that starts something answers twice, ACCEPTED and then DONE; anything else answers +DONE once. Boards also send messages nobody asked for, with sequence 0: EVENT (an input changed, +the interlock tripped), NOTICE (the host-alive heartbeat, a move stopped by the interlock) and +EMERGENCY (CANopen EMCY from a drive, SAGIAN CAN traffic). + +The requests here are the ones the Master Controller was logged sending, plus the reads in +`FIRMWARE_READS`, and nothing else: `Request` refuses any device/opcode pair not in `COMMANDS`, +so firmware upgrade and flash commands cannot be sent through this module. A firmware read is one the Master Controller never sends, which only reads a state and changes +nothing. +""" + +import enum +import struct +from dataclasses import dataclass, field +from typing import Dict, List, Literal, Optional, Tuple + +from pylabrobot.beckman_coulter.biomek_i7.driver.errors import INTERLOCK_TRIPPED_CODE, ace_error + + +class Device(enum.IntEnum): + """The device byte: what kind of thing on a board a message addresses.""" + + MODULE = 0x00 + INTERLOCK = 0x01 + BOARD = 0x02 + MOTION_SERVICE = 0x10 + MOTOR = 0x11 + PUMP = 0x12 + TIP_SENSOR = 0x13 + IO_SERVICE = 0x20 + DIGITAL_INPUT = 0x21 + ANALOG_INPUT = 0x22 + DIGITAL_OUTPUT = 0x28 + STATUS_DISPLAY = 0x2D + ACCUFRAME = 0xAF + LEGACY_ALP = 0xFE + IO_BOX = 0xFF + + +class Status(enum.IntEnum): + """A reply's status byte.""" + + ERROR = 0x00 + ACCEPTED = 0x01 + DONE = 0x02 + EVENT = 0x03 + NOTICE = 0xFE + EMERGENCY = 0xFF + + +# Every request this driver may send, by (device, opcode). The names are the Master Controller's. +COMMANDS: Dict[Tuple[int, int], str] = { + (Device.MODULE, 0x00): "Get Module ID", + (Device.MODULE, 0x02): "Get Module Serial Number", + (Device.MODULE, 0x03): "Get Module Hardware Version", + (Device.MODULE, 0x08): "Get Module Device Count", + (Device.MODULE, 0x0F): "Stop Module Execution", + (Device.MODULE, 0x11): "Get Module Application Image Length", + (Device.MODULE, 0x12): "Get Module Application Image CRC", + (Device.BOARD, 0x02): "Get Board Serial Number", + (Device.BOARD, 0x03): "Get Board Hardware Version", + (Device.BOARD, 0x04): "Get Board Bootloader Version", + (Device.BOARD, 0x10): "Get Board Application Version", + (Device.BOARD, 0x11): "Get Board Application Image Length", + (Device.BOARD, 0x12): "Get Board Application Image CRC", + (Device.INTERLOCK, 0x11): "Notify On Interlock Trip", + (Device.INTERLOCK, 0x50): "Trip Interlock", + (Device.INTERLOCK, 0x51): "Re-Arm Interlock", + (Device.MOTION_SERVICE, 0x0F): "Stop Motion Service", + (Device.MOTION_SERVICE, 0x50): "Move All", + (Device.MOTOR, 0x10): "Configure", + (Device.MOTOR, 0x12): "Set State", + (Device.MOTOR, 0x21): "Get Homed State", + (Device.MOTOR, 0x24): "Get Current Position", + (Device.MOTOR, 0x31): "Get Control Effort", + (Device.MOTOR, 0x40): "Set Move Parameters", + (Device.MOTOR, 0x50): "Move", + (Device.MOTOR, 0x51): "Home", + (Device.PUMP, 0x10): "Configure", + (Device.PUMP, 0x12): "Set State", + (Device.PUMP, 0x21): "Get Homed State", + (Device.PUMP, 0x24): "Get Current Position", + (Device.PUMP, 0x40): "Set Move Parameters", + (Device.PUMP, 0x51): "Home", + (Device.TIP_SENSOR, 0x10): "Get Tip Status", + (Device.TIP_SENSOR, 0x41): "Set LLS/CD Sensitivity", + (Device.IO_SERVICE, 0x08): "Get IO Service Device Count", + (Device.DIGITAL_INPUT, 0x01): "Get Digital Input Name", + (Device.DIGITAL_INPUT, 0x10): "Read Digital Input", + (Device.DIGITAL_INPUT, 0x11): "Notify On Digital Input Change", + (Device.ANALOG_INPUT, 0x01): "Get Analog Input Name", + (Device.ANALOG_INPUT, 0x10): "Read Analog Input", + (Device.ANALOG_INPUT, 0x12): "Get Analog Input Units", + (Device.DIGITAL_OUTPUT, 0x01): "Get Digital Output Name", + (Device.DIGITAL_OUTPUT, 0x10): "Read Digital Output", + (Device.DIGITAL_OUTPUT, 0x11): "Notify On Digital Output Change", + (Device.STATUS_DISPLAY, 0x10): "Set Status Display", + (Device.ACCUFRAME, 0xF7): "Get AccuFrame Offsets", + (Device.LEGACY_ALP, 0x18): "List Legacy ALP Devices", + (Device.IO_BOX, 0x10): "Send Digital I/O Box", +} + +# Reads the Master Controller never sends. Get State answers an axis's state byte (`AxisState`) +# with no precondition, and changes nothing. Get Interlock Status answers the interlock's state +# byte; the Master Controller's log names it "Get Interlock Status". +FIRMWARE_READS: Dict[Tuple[int, int], str] = { + (Device.MOTOR, 0x11): "Get State", + (Device.PUMP, 0x11): "Get State", + (Device.INTERLOCK, 0x10): "Get Interlock Status", +} +COMMANDS.update(FIRMWARE_READS) + +# Requests that answer ACCEPTED before DONE. +TWO_STAGE: frozenset = frozenset( + {(Device.MOTION_SERVICE, 0x50), (Device.MOTOR, 0x50), (Device.MOTOR, 0x51), (Device.PUMP, 0x51)} +) + +# The opcode a board's unsolicited messages carry, by (device, opcode). +HOST_ALIVE = (Device.MODULE, 0x40) +EMCY = (Device.MODULE, 0x31) +SAGIAN_CAN = (Device.MODULE, 0x30) +INTERLOCK_TRIPPED = (Device.INTERLOCK, 0x10) +DIGITAL_INPUT_VALUE = (Device.DIGITAL_INPUT, 0x10) + +# A SAGIAN CAN message a Span-8 board passes up: the message's kind and status bytes, named as the +# Master Controller's log names them ("SAGIAN CAN TO_NODE 05:00 READ SUCCESS F7 ..."). The board +# shares the CAN bus with the SAGIAN devices behind it (the AccuFrame is node 05) and forwards what +# it sees there, the answers to the host's own requests included: reading the AccuFrame's offsets +# through the Multichannel's board brings the AccuFrame's answer back from the Span-8's as well. +# Every such message in the Master Controller's logs (2026-07-27 .. 10-27) is a success or a +# request; any other status is not known to be harmless. +SAGIAN_CAN_KINDS = {0x00: "ACTION", 0x01: "READ", 0x02: "WRITE", 0x03: "EVENT"} +SAGIAN_CAN_KNOWN_STATUSES = {0x00: "REQUEST", 0x01: "SUCCESS"} + + +def describe_sagian_can(data: bytes) -> Tuple[str, bool]: + """A forwarded SAGIAN CAN message as the Master Controller's log words it + (`TO_NODE 05:00 READ SUCCESS F7 28 0F BB 40`), and whether its status is one of those seen in + normal operation (`SAGIAN_CAN_KNOWN_STATUSES`).""" + if len(data) < 7: + return f"short message {data.hex()}", False + kind = SAGIAN_CAN_KINDS.get(data[5], f"kind 0x{data[5]:02X}") + status = SAGIAN_CAN_KNOWN_STATUSES.get(data[6]) + words = [ + "TO_NODE" if data[1] == 0x01 else f"direction 0x{data[1]:02X}", + f"{data[2]:02X}:{data[4]:02X}", + kind, + status or f"status 0x{data[6]:02X}", + ] + if len(data) > 7: + words.append(data[7:].hex(" ").upper()) + return " ".join(words), status is not None and data[1] == 0x01 + + +# A drive's own error code while its motor power is off, the interlock tripped ("interlock active"). +INTERLOCK_ACTIVE = 0x0416 + + +def describe_routine_unsolicited(reply: "Reply") -> Optional[str]: + """What an unsolicited message every session sees says, or None for one worth showing. + + Routine: a drive's EMCY with error 0000 (its fault cleared, as it is enabled), a drive's EMCY + naming `interlock active`, and a Move All notice ending in `interlock tripped`. The last two + follow every interlock trip, the driver's own at `stop` included. So does the chassis's trip event + (Notify On Interlock Trip), which is logged at INFO; `BiomekI7Driver` tells a trip it made from + one it did not.""" + if (reply.device, reply.opcode) == EMCY and reply.status == Status.EMERGENCY: + if len(reply.data) < 8: + return None + emcy = parse_emcy(reply.data) + if emcy.error_code == 0: + return f"drive node 0x{emcy.node:02X}: fault cleared (EMCY 0000)" + if emcy.device_error == INTERLOCK_ACTIVE: + return f"drive node 0x{emcy.node:02X}: interlock active (EMCY {emcy.error_code:04X})" + return None + if reply.status == Status.NOTICE and reply.error_code == INTERLOCK_TRIPPED_CODE: + return f"device 0x{reply.device:02X} index {reply.index}: move ended, interlock tripped" + return None + + +@dataclass(frozen=True) +class Request: + """One request, before a sequence number is given to it.""" + + device: int + index: int + opcode: int + params: bytes = b"" + + def __post_init__(self) -> None: + if (self.device, self.opcode) not in COMMANDS: + raise ValueError( + f"device 0x{self.device:02X} opcode 0x{self.opcode:02X} is not a command this driver sends" + ) + if not 0 <= self.index <= 0xFF: + raise ValueError(f"index must be 0-255, got {self.index}") + + @property + def name(self) -> str: + return COMMANDS[(self.device, self.opcode)] + + @property + def two_stage(self) -> bool: + """Whether the board answers ACCEPTED before DONE.""" + return (self.device, self.opcode) in TWO_STAGE + + def encode(self, sequence: int) -> bytes: + """The message bytes, with `sequence` (1-255; 0 is the boards' own).""" + if not 1 <= sequence <= 0xFF: + raise ValueError(f"sequence must be 1-255, got {sequence}") + return bytes([self.device, self.index, 0x00, sequence, self.opcode]) + self.params + + def __str__(self) -> str: + return f"{self.name} (device 0x{self.device:02X}, index {self.index})" + + +@dataclass(frozen=True) +class Reply: + """One message from a board.""" + + device: int + index: int + sequence: int + opcode: int + status: int + data: bytes + # Replies the board sent under this request's sequence for other devices: a Move All's axes + # report there when they end other than plainly. Set by `AceBoard` on the final reply. + related: Tuple["Reply", ...] = field(default=(), compare=False) + + @classmethod + def parse(cls, message: bytes) -> "Reply": + """Split a message into its header, status and data. + + Raises: + ValueError: if the message is shorter than a header and a status byte. + """ + if len(message) < 6: + raise ValueError(f"ACE reply too short: {message.hex()}") + device, index, _, sequence, opcode, status = message[:6] + return cls(device, index, sequence, opcode, status, bytes(message[6:])) + + @property + def key(self) -> Tuple[int, int, int, int]: + """What a reply shares with the request it answers.""" + return (self.device, self.index, self.sequence, self.opcode) + + @property + def unsolicited(self) -> bool: + return self.sequence == 0 + + @property + def error_code(self) -> Optional[int]: + """The ACE error code, or None when the reply reports success.""" + if self.status == Status.ERROR: + return self.data[0] if self.data else 0 + if self.status in (Status.ACCEPTED, Status.DONE, Status.NOTICE) and self.data and self.data[0]: + return self.data[0] + return None + + @property + def device_error(self) -> Optional[int]: + """The drive's own error code that follows the ACE error code, when there is one.""" + if self.error_code is None or len(self.data) < 2: + return None + return int.from_bytes(self.data[1:], "little") + + @property + def payload(self) -> bytes: + """What a successful reply returns, after its zero error byte.""" + return self.data[1:] + + def raise_for_error(self, request: str) -> None: + """Raise the `AceError` this reply reports, if it reports one.""" + code = self.error_code + if code is not None: + raise ace_error(code, self.device_error, request, self.device, self.index) + + def check(self, request: str) -> "Reply": + """Return this reply, or raise the `AceError` it reports.""" + self.raise_for_error(request) + return self + + +# -- requests ---------------------------------------------------------------- + + +def get_module_id() -> Request: + return Request(Device.MODULE, 0, 0x00) + + +def get_module_serial_number() -> Request: + return Request(Device.MODULE, 0, 0x02) + + +def get_module_hardware_version() -> Request: + return Request(Device.MODULE, 0, 0x03) + + +def get_module_device_count() -> Request: + return Request(Device.MODULE, 0, 0x08) + + +def get_module_application_image_length() -> Request: + return Request(Device.MODULE, 0, 0x11) + + +def get_module_application_image_crc() -> Request: + return Request(Device.MODULE, 0, 0x12) + + +def stop_module_execution() -> Request: + return Request(Device.MODULE, 0, 0x0F) + + +def get_board_serial_number(board: int) -> Request: + return Request(Device.BOARD, board, 0x02) + + +def get_board_hardware_version(board: int) -> Request: + return Request(Device.BOARD, board, 0x03) + + +def get_board_bootloader_version(board: int) -> Request: + return Request(Device.BOARD, board, 0x04) + + +def get_board_application_version(board: int) -> Request: + return Request(Device.BOARD, board, 0x10) + + +def get_board_application_image_length(board: int) -> Request: + return Request(Device.BOARD, board, 0x11) + + +def get_board_application_image_crc(board: int) -> Request: + return Request(Device.BOARD, board, 0x12) + + +def get_interlock_status(interlock: int = 1) -> Request: + return Request(Device.INTERLOCK, interlock, 0x10) + + +def notify_on_interlock_trip(interlock: int = 1, notify: bool = True) -> Request: + return Request(Device.INTERLOCK, interlock, 0x11, bytes([int(notify)])) + + +def trip_interlock(interlock: int = 1) -> Request: + return Request(Device.INTERLOCK, interlock, 0x50) + + +def rearm_interlock(interlock: int = 1) -> Request: + return Request(Device.INTERLOCK, interlock, 0x51) + + +def stop_motion_service() -> Request: + return Request(Device.MOTION_SERVICE, 0, 0x0F) + + +def move_all(timeout_ms: int) -> Request: + """Start every move whose parameters were set since the last move, together.""" + return Request(Device.MOTION_SERVICE, 0, 0x50, struct.pack(" Request: + """Load an axis's motor table. `payload` is the table exactly as the Master Controller sent it.""" + return Request(device, axis, 0x10, payload) + + +def set_state_enabled(device: int, axis: int) -> Request: + return Request(device, axis, 0x12, b"\x00") + + +def get_state(device: int, axis: int) -> Request: + """Ask a motor or pump for its state byte; see `AxisState`.""" + return Request(device, axis, 0x11) + + +def get_homed_state(device: int, axis: int) -> Request: + """Whether a motor or a pump (`device`) has been homed since the board started.""" + return Request(device, axis, 0x21) + + +def get_current_position(device: int, axis: int) -> Request: + return Request(device, axis, 0x24) + + +def get_control_effort(axis: int) -> Request: + return Request(Device.MOTOR, axis, 0x31) + + +# The largest force limit Set Move Parameters can carry: a u32 of the Master Controller's units x1000. +MAX_FORCE = 4294967.295 + + +def set_motor_move_parameters( + axis: int, + position: int, + velocity: int, + acceleration: int, + jerk: int, + force: int = 0, + sensor: int = 0, + trigger: int = 0, +) -> Request: + """Set a motor's next move, in counts, laid out as the Master Controller's logged requests lay + it out. `force` is the force limit x1000 (grip and tip loading), 0 for none. `sensor` + and `trigger` make the move stop where a sensor fires: liquid-level sensing on a Span-8 Z, the + AccuFrame when framing (0, 0: no sensor).""" + params = struct.pack(" Request: + """Set a syringe pump's next move, in counts, with the valve position it moves through.""" + params = struct.pack( + " Request: + """Start one motor's move on its own.""" + return Request(Device.MOTOR, axis, 0x50, struct.pack(" Request: + return Request(device, axis, 0x51) + + +def get_tip_status(sensor: int = 1) -> Request: + return Request(Device.TIP_SENSOR, sensor, 0x10) + + +def set_lls_cd_sensitivity(clot_detection: bool, value: int) -> Request: + """Liquid-level (or, with `clot_detection`, clot-detection) sensitivity, 0-4095, on the Span-8's + LLS/CD board (the device that also answers Get Tip Status): what the Master Controller sends + for `SS`.""" + if not 0 <= value <= 4095: + raise ValueError(f"sensitivity {value} is outside 0..4095") + return Request(Device.TIP_SENSOR, 1, 0x41, struct.pack(" Request: + return Request(Device.IO_SERVICE, 0, 0x08) + + +def get_input_output_name(device: int, index: int) -> Request: + return Request(device, index, 0x01) + + +def read_input_output(device: int, index: int) -> Request: + return Request(device, index, 0x10) + + +def notify_on_change(device: int, index: int, notify: bool = True) -> Request: + return Request(device, index, 0x11, bytes([int(notify)])) + + +def get_analog_input_units(index: int) -> Request: + return Request(Device.ANALOG_INPUT, index, 0x12) + + +# ERROR is what the Master Controller shows after a failed move (2026-07-31, `2D 01 00 seq 10 05`). +StatusDisplayState = Literal["ready", "running", "paused", "error"] +STATUS_DISPLAY_STATES = {"ready": 0x02, "running": 0x03, "paused": 0x04, "error": 0x05} + + +def set_status_display(state: StatusDisplayState, display: int = 1) -> Request: + return Request(Device.STATUS_DISPLAY, display, 0x10, bytes([STATUS_DISPLAY_STATES[state]])) + + +def get_accuframe_offsets(accuframe: int = 1) -> Request: + return Request(Device.ACCUFRAME, accuframe, 0xF7) + + +def list_legacy_alp_devices() -> Request: + return Request(Device.LEGACY_ALP, 0, 0x18) + + +def send_digital_io_box(params: bytes, box: int = 1) -> Request: + """Pass a command to the digital I/O box. Its bytes are the box's own and are not decoded here.""" + return Request(Device.IO_BOX, box, 0x10, params) + + +# -- replies ----------------------------------------------------------------- + +# Get Module ID's two bytes, as the Master Controller's log decodes them ("Chassis", "Left +# Multichannel", "Right Span-8"). Only these three were seen, on one instrument. +MODULE_TYPES = {0x80: "chassis", 0xFD: "multichannel", 0xFB: "span8"} +MODULE_SIDES = {0x00: None, 0x01: "left", 0x02: "right"} + +# Hardware version type codes, as the Master Controller names them. +HARDWARE_NAMES = { + 0x00: "Motion Board", + 0x01: "Transport Supervisor", + 0x02: "Chassis Supervisor", + 0xE0: "SAGIAN Motion Board", + 0xE1: "SAGIAN LLS Board", + 0xE2: "SAGIAN Syringe Pump Board", + 0xE3: "AccuFrame", + 0xE5: "Device Controller", +} + +# Tip sensor codes. 1 is "cannot determine" in the Master Controller's `VT` replies. +TIP_STATES = {0x00: "loaded", 0x01: "unknown", 0x02: "unloaded"} + +# What an axis reports when its part of a Move All ends other than plainly. A 1-byte report is +# one of the statuses; a 5-byte report is a type and the s32 position where its sensor fired. +LLS_LIQUID_SENSED = 69 +LLS_LIQUID_NOT_SENSED = 70 +CD_CLOT_NOT_DETECTED = 71 +CD_CLOT_DETECTED = 72 +ACCUFRAME = 175 +MotionOutcome = Literal[ + "done", "liquid-sensed", "accuframe", "liquid-not-sensed", "clot-not-detected", "clot-detected" +] +MOTION_OUTCOMES: Dict[int, MotionOutcome] = { + LLS_LIQUID_SENSED: "liquid-sensed", + LLS_LIQUID_NOT_SENSED: "liquid-not-sensed", + CD_CLOT_NOT_DETECTED: "clot-not-detected", + CD_CLOT_DETECTED: "clot-detected", + ACCUFRAME: "accuframe", +} + + +class AxisState(enum.IntEnum): + """A motor's or pump's state byte, as Get State answers it. + + An axis starts NOT_CONFIGURED at power-up, and goes back to it when Configure starts or a SAGIAN + drive reports it lost its parameters. Configure ends DISABLED; Set State moves between DISABLED + and ENABLED; Home and moves need ENABLED. FAULT follows a drive error. + """ + + ENABLED = 0x00 + DISABLED = 0x01 + NOT_CONFIGURED = 0xFE + FAULT = 0xFF + + +AxisStateName = Literal["enabled", "disabled", "not_configured", "fault"] +"""An `AxisState` as the public API gives it (`Pod.request_axis_states`): its name, lower case.""" + + +@dataclass(frozen=True) +class ModuleId: + """What Get Module ID answers: the kind of module and, for an arm's, its side.""" + + type_code: int + side_code: int + + @property + def type(self) -> Optional[str]: + """`chassis`, `multichannel` or `span8`; None for a code not seen yet.""" + return MODULE_TYPES.get(self.type_code) + + @property + def side(self) -> Optional[str]: + """`left` or `right` for an arm's module, None for the chassis.""" + return MODULE_SIDES.get(self.side_code) + + +@dataclass(frozen=True) +class HardwareVersion: + type_code: int + revision: int + + @property + def name(self) -> str: + return HARDWARE_NAMES.get(self.type_code, f"hardware 0x{self.type_code:02X}") + + def __str__(self) -> str: + return f"{self.name} {self.revision}" + + +@dataclass(frozen=True) +class Emcy: + """A CANopen emergency message a drive sent through its board.""" + + node: int + error_code: int + error_register: int + device_error: int + source: int + + +def parse_module_id(payload: bytes) -> ModuleId: + return ModuleId(payload[0], payload[1]) + + +def parse_string(payload: bytes) -> str: + return payload.decode("ascii") + + +def parse_hardware_version(payload: bytes) -> HardwareVersion: + return HardwareVersion(payload[0], payload[1]) + + +def parse_device_count(payload: bytes) -> Dict[int, int]: + """Each kind of device a module or service holds, by device byte, and how many.""" + if len(payload) % 3: + raise ValueError(f"device count is (device, u16 count) triples, got {payload.hex()}") + return { + payload[i]: int.from_bytes(payload[i + 1 : i + 3], "little") for i in range(0, len(payload), 3) + } + + +def parse_u32(payload: bytes) -> int: + return int(struct.unpack_from(" int: + return int(struct.unpack_from(" float: + return float(struct.unpack_from(" Tuple[float, float, float]: + x, y, z = struct.unpack_from(" InterlockState: + """Raises `ValueError` for a byte not seen.""" + state = INTERLOCK_STATES.get(payload[0]) + if state is None: + raise ValueError(f"interlock state 0x{payload[0]:02X} has not been seen") + return state # type: ignore[return-value] + + +def parse_axis_state(payload: bytes) -> AxisState: + """Raises `ValueError` for a state byte the firmware does not set.""" + return AxisState(payload[0]) + + +def parse_tip_status(payload: bytes) -> List[Optional[str]]: + """Each channel's tip, `loaded` or `unloaded`; None for a code not seen yet.""" + return [TIP_STATES.get(b) for b in payload] + + +@dataclass(frozen=True) +class MotionComplete: + """How one axis's part of a Move All ended: `done`, or a sensor outcome; `position` is where a + sensor stopped it (liquid sensed, AccuFrame), else None.""" + + device: int + index: int + outcome: MotionOutcome + position: Optional[int] = None + + +def parse_motion_complete(reply: Reply) -> MotionComplete: + """An axis's report inside a Move All.""" + payload = reply.payload + if len(payload) == 5: + (position,) = struct.unpack_from(" Emcy: + """Decode an EMERGENCY reply's data: node, CANopen error code and register, then the drive's own + error code and the source it names.""" + node = data[1] + error_code, error_register, device_error, source = struct.unpack_from(" (the request, its sequence, the frame's bytes, what the log says it is). +# The reads the Master Controller never sends (`FIRMWARE_READS`) were never logged; their frames +# follow the request layout. +FRAMES: Dict[Tuple[int, int], Tuple[Callable[[], p.Request], int, str, str]] = { + (0x00, 0x00): (p.get_module_id, 0x01, "0000000100", "Get Module ID"), + (0x00, 0x02): (p.get_module_serial_number, 0x03, "0000000302", "Get Module Serial Number"), + (0x00, 0x03): (p.get_module_hardware_version, 0x02, "0000000203", "Get Module Hardware Version"), + (0x00, 0x08): (p.get_module_device_count, 0x06, "0000000608", "Get Module Device Count"), + (0x00, 0x0F): (p.stop_module_execution, 0x75, "000000750F", "Stop Module Execution"), + (0x00, 0x11): ( + p.get_module_application_image_length, + 0x05, + "0000000511", + "Get Module Application Image Length", + ), + (0x00, 0x12): ( + p.get_module_application_image_crc, + 0x04, + "0000000412", + "Get Module Application Image CRC", + ), + (0x02, 0x02): ( + lambda: p.get_board_serial_number(6), + 0x0B, + "0206000B02", + "Get Board 6 Serial Number", + ), + (0x02, 0x03): ( + lambda: p.get_board_hardware_version(1), + 0x07, + "0201000703", + "Get Board 1 Hardware Version", + ), + (0x02, 0x04): ( + lambda: p.get_board_bootloader_version(7), + 0x31, + "0207003104", + "Get Board 7 Bootloader Version", + ), + (0x02, 0x10): ( + lambda: p.get_board_application_version(1), + 0x08, + "0201000810", + "Get Board 1 Application Version", + ), + (0x02, 0x11): ( + lambda: p.get_board_application_image_length(6), + 0x0D, + "0206000D11", + "Get Board 6 Application Image Length", + ), + (0x02, 0x12): ( + lambda: p.get_board_application_image_crc(6), + 0x0C, + "0206000C12", + "Get Board 6 Application Image CRC", + ), + (0x01, 0x10): (p.get_interlock_status, 0x09, "0101000910", "(never logged)"), + (0x01, 0x11): (p.notify_on_interlock_trip, 0x28, "010100281101", "Notify On Interlock Trip TRUE"), + (0x01, 0x50): (p.trip_interlock, 0xEA, "010100EA50", "Trip Interlock"), + (0x01, 0x51): (p.rearm_interlock, 0xE1, "010100E151", "Re-Arm Interlock"), + (0x10, 0x0F): (p.stop_motion_service, 0x67, "100000670F", "Stop Motion Service"), + (0x10, 0x50): (lambda: p.move_all(5000), 0x28, "100000285088130000", "Move All Timeout:5000"), + (0x11, 0x10): ( + lambda: p.configure(p.Device.MOTOR, 2, MOTOR_TABLE), + 0x2F, + "1102002F10" + MOTOR_TABLE.hex(), + "Configure Y1 Minimum Velocity:23 ...", + ), + (0x11, 0x11): (lambda: p.get_state(p.Device.MOTOR, 3), 0x07, "1103000711", "(never logged)"), + (0x11, 0x12): ( + lambda: p.set_state_enabled(p.Device.MOTOR, 3), + 0x76, + "110300761200", + "Set Z State ENABLED", + ), + (0x11, 0x21): ( + lambda: p.get_homed_state(p.Device.MOTOR, 1), + 0x3C, + "1101003C21", + "Get X Homed State", + ), + (0x11, 0x24): ( + lambda: p.get_current_position(p.Device.MOTOR, 7), + 0x80, + "1107008024", + "Get GZ Current Position", + ), + (0x11, 0x31): (lambda: p.get_control_effort(0x13), 0x96, "1113009631", "Get GG Control Effort"), + (0x11, 0x40): ( + lambda: p.set_motor_move_parameters( + 3, position=-1000, velocity=24320, acceleration=128000, jerk=698880 + ), + 0xAB, + "110300AB40005F000000F4010000AA0A000000000018FCFFFF0000", + "Set Z Move Parameters Position:-1000 Velocity:24320 Acceleration:128000 Jerk:698880", + ), + (0x11, 0x50): (lambda: p.move(3, 30000), 0xAC, "110300AC5030750000", "Move Z Timeout:30000"), + (0x11, 0x51): (lambda: p.home(p.Device.MOTOR, 3), 0xAD, "110300AD51", "Home Z"), + (0x12, 0x10): ( + lambda: p.configure(p.Device.PUMP, 1, PUMP_TABLE), + 0x3F, + "1201003F10" + PUMP_TABLE.hex(), + "Configure D1 Minimum Start Velocity:200 ...", + ), + (0x12, 0x11): (lambda: p.get_state(p.Device.PUMP, 1), 0x07, "1201000711", "(never logged)"), + (0x12, 0x12): ( + lambda: p.set_state_enabled(p.Device.PUMP, 8), + 0x6B, + "1208006B1200", + "Set D8 State ENABLED", + ), + (0x12, 0x21): ( + lambda: p.get_homed_state(p.Device.PUMP, 1), + 0xDB, + "120100DB21", + "Get D1 Homed State", + ), + (0x12, 0x24): ( + lambda: p.get_current_position(p.Device.PUMP, 8), + 0x88, + "1208008824", + "Get D8 Current Position", + ), + (0x12, 0x40): ( + lambda: p.set_pump_move_parameters( + 2, + position=0, + start_velocity=200, + max_velocity=23200, + cutoff_velocity=200, + acceleration=50000, + valve="input", + ), + 0x72, + "1202007240C8000000A05A0000C800000050C300000000000000", + "Set D2 Move Parameters Position:0 Valve:INPUT Start Velocity:200 Maximum Velocity:23200 " + "Cutoff Velocity:200 Acceleration:50000", + ), + (0x12, 0x51): (lambda: p.home(p.Device.PUMP, 1), 0x60, "1201006051", "Home D1"), + (0x13, 0x10): (p.get_tip_status, 0x95, "1301009510", "Get Tip Status"), + (0x13, 0x41): ( + lambda: p.set_lls_cd_sensitivity(False, 3500), + 0xA2, + "130100A24100AC0D", + "Set LLS Sensitivity 3500", + ), + (0x20, 0x08): (p.get_io_service_device_count, 0x0A, "2000000A08", "Get IO Service Device Count"), + (0x21, 0x01): ( + lambda: p.get_input_output_name(p.Device.DIGITAL_INPUT, 1), + 0x1E, + "2101001E01", + "Get Digital Input 1 Name", + ), + (0x21, 0x10): ( + lambda: p.read_input_output(p.Device.DIGITAL_INPUT, 1), + 0x20, + "2101002010", + "Read Digital Input 1", + ), + (0x21, 0x11): ( + lambda: p.notify_on_change(p.Device.DIGITAL_INPUT, 1), + 0x1F, + "2101001F1101", + "Notify On Digital Input 1 Change TRUE", + ), + (0x22, 0x01): ( + lambda: p.get_input_output_name(p.Device.ANALOG_INPUT, 9), + 0x0B, + "2209000B01", + "Get Analog Input 9 Name", + ), + (0x22, 0x10): ( + lambda: p.read_input_output(p.Device.ANALOG_INPUT, 1), + 0x65, + "2201006510", + "Read Analog Input 1", + ), + (0x22, 0x12): ( + lambda: p.get_analog_input_units(9), + 0x0C, + "2209000C12", + "Get Analog Input 9 Units", + ), + (0x28, 0x01): ( + lambda: p.get_input_output_name(p.Device.DIGITAL_OUTPUT, 1), + 0x22, + "2801002201", + "Get Digital Output 1 Name", + ), + (0x28, 0x10): ( + lambda: p.read_input_output(p.Device.DIGITAL_OUTPUT, 1), + 0x24, + "2801002410", + "Read Digital Output 1", + ), + (0x28, 0x11): ( + lambda: p.notify_on_change(p.Device.DIGITAL_OUTPUT, 1), + 0x23, + "280100231101", + "Notify On Digital Output 1 Change TRUE", + ), + (0x2D, 0x10): ( + lambda: p.set_status_display("running"), + 0xE2, + "2D0100E21003", + "Set Status Display RUNNING", + ), + (0xAF, 0xF7): (p.get_accuframe_offsets, 0x32, "AF010032F7", "Get AccuFrame Offsets"), + (0xFE, 0x18): (p.list_legacy_alp_devices, 0x26, "FE00002618", "List Legacy ALP Devices"), + (0xFF, 0x10): ( + lambda: p.send_digital_io_box(b"\x02\x01"), + 0xE0, + "FF0100E0100201", + "Send Digital I/O Box 00 WRITE 01", + ), +} + + +def decode(message: bytes) -> Tuple[int, int, int, int, bytes]: + """A request's header and parameters, by the layout in `protocol.py`'s docstring.""" + device, index, zero, sequence, opcode = message[:5] + assert zero == 0 + return device, index, sequence, opcode, message[5:] + + +class ExactFrameTests(unittest.TestCase): + def test_every_command_has_its_frame(self) -> None: + """A command added to `COMMANDS` needs its frame here.""" + self.assertEqual(set(FRAMES), set(p.COMMANDS)) + + def test_each_request_is_the_logged_frame(self) -> None: + for key, (build, sequence, frame_hex, logged) in FRAMES.items(): + with self.subTest(command=p.COMMANDS[key], logged=logged): + request = build() + self.assertEqual((request.device, request.opcode), key) + self.assertEqual(request.encode(sequence), bytes.fromhex(frame_hex)) + + def test_reads_never_logged_only_read(self) -> None: + for key, name in p.FIRMWARE_READS.items(): + self.assertTrue(name.startswith("Get "), name) + self.assertEqual(p.COMMANDS[key], name) + + def test_status_display_error_is_the_logged_frame(self) -> None: + # Log.db3, after a failed move: `2D 01 00 seq 10 05`. + self.assertEqual(p.set_status_display("error").encode(0x2E), bytes.fromhex("2D01002E1005")) + + def test_only_moves_and_homes_answer_twice(self) -> None: + two_stage = {key for key in FRAMES if FRAMES[key][0]().two_stage} + self.assertEqual(two_stage, {(0x10, 0x50), (0x11, 0x50), (0x11, 0x51), (0x12, 0x51)}) + + +class RoundTripTests(unittest.TestCase): + """Build, then parse: every field comes back out as it went in.""" + + def setUp(self) -> None: + self.random = random.Random(7) + + def test_header(self) -> None: + for key in FRAMES: + for _ in range(5): + index, sequence = self.random.randrange(256), self.random.randrange(1, 256) + params = bytes(self.random.randrange(256) for _ in range(self.random.randrange(4))) + message = p.Request(key[0], index, key[1], params).encode(sequence) + self.assertEqual(decode(message), (key[0], index, sequence, key[1], params)) + + def test_motor_move_parameters(self) -> None: + for _ in range(50): + values = dict( + velocity=self.random.randrange(2**32), + acceleration=self.random.randrange(2**32), + jerk=self.random.randrange(2**32), + force=self.random.randrange(2**32), + position=self.random.randrange(-(2**31), 2**31), + sensor=self.random.randrange(256), + trigger=self.random.randrange(256), + ) + axis = self.random.randrange(1, 32) + device, index, _, opcode, params = decode( + p.set_motor_move_parameters(axis, **values).encode(1) + ) + self.assertEqual((device, index, opcode), (p.Device.MOTOR, axis, 0x40)) + fields = struct.unpack(" None: + for valve, code in p.VALVE_POSITIONS.items(): + values = [self.random.randrange(2**32) for _ in range(4)] + position = self.random.randrange(-(2**31), 2**31) + request = p.set_pump_move_parameters( + 3, + position, + values[0], + values[1], + values[2], + values[3], + valve, # type: ignore[arg-type] + ) + _, index, _, opcode, params = decode(request.encode(1)) + self.assertEqual((request.device, index, opcode), (p.Device.PUMP, 3, 0x40)) + self.assertEqual(struct.unpack(" None: + for timeout in (0, 5000, 30000, 2**32 - 1): + self.assertEqual(struct.unpack(" None: + for table in (MOTOR_TABLE, PUMP_TABLE): + self.assertEqual(decode(p.configure(p.Device.MOTOR, 1, table).encode(1))[4], table) + + def test_lls_cd_sensitivity(self) -> None: + for clot in (False, True): + for value in (0, 1, 3500, 4095): + params = decode(p.set_lls_cd_sensitivity(clot, value).encode(1))[4] + self.assertEqual(struct.unpack(" None: + for _ in range(50): + header = [self.random.randrange(256) for _ in range(5)] + header[2] = 0 + status = self.random.choice(list(p.Status)) + data = bytes(self.random.randrange(256) for _ in range(self.random.randrange(8))) + reply = p.Reply.parse(bytes(header) + bytes([status]) + data) + self.assertEqual( + (reply.device, reply.index, reply.sequence, reply.opcode, reply.status, reply.data), + (header[0], header[1], header[3], header[4], status, data), + ) + self.assertEqual(reply.key, (header[0], header[1], header[3], header[4])) + self.assertEqual(reply.unsolicited, header[3] == 0) + + def test_numbers(self) -> None: + for _ in range(50): + s32 = self.random.randrange(-(2**31), 2**31) + u32 = self.random.randrange(2**32) + self.assertEqual(p.parse_s32(struct.pack(" None: + counts = {0x02: 6, 0x11: 21, 0x12: 8, 0x22: 300} + payload = b"".join(bytes([d]) + n.to_bytes(2, "little") for d, n in counts.items()) + self.assertEqual(p.parse_device_count(payload), counts) + with self.assertRaises(ValueError): + p.parse_device_count(payload[:-1]) + version = p.parse_hardware_version(bytes([0xE3, 4])) + self.assertEqual((version.type_code, version.revision, str(version)), (0xE3, 4, "AccuFrame 4")) + self.assertEqual(str(p.parse_hardware_version(bytes([0x7A, 1]))), "hardware 0x7A 1") + + +class RefusalTests(unittest.TestCase): + def test_unknown_commands_are_refused(self) -> None: + with self.assertRaises(ValueError): + p.Request(p.Device.BOARD, 1, 0x05) # not a logged opcode: other commands stay unsendable + + def test_index_and_sequence_ranges(self) -> None: + with self.assertRaises(ValueError): + p.Request(p.Device.MOTOR, 256, 0x24) + for sequence in (0, 256): + with self.assertRaises(ValueError): + p.get_module_id().encode(sequence) + + +class ReplyTests(unittest.TestCase): + """Replies as the boards send them (the header, status, then data).""" + + def test_module_id(self) -> None: + seen: List[Tuple[object, object]] = [] + for message in ("000000010002008000", "00000001000200FD01", "00000001000200FB02"): + module = p.parse_module_id( + p.Reply.parse(bytes.fromhex(message)).check("Get Module ID").payload + ) + seen.append((module.type, module.side)) + self.assertEqual(seen, [("chassis", None), ("multichannel", "left"), ("span8", "right")]) + unknown = p.parse_module_id(bytes([0x42, 0x07])) + self.assertEqual((unknown.type, unknown.side), (None, None)) + + def test_strings(self) -> None: + reply = p.Reply.parse(bytes.fromhex("0000000302020053494D554C41544544") + b"0" * 4) + self.assertEqual(p.parse_string(reply.payload), "SIMULATED0000") + reply = p.Reply.parse(bytes.fromhex("02010008100200302E322E34")) + self.assertEqual(p.parse_string(reply.payload), "0.2.4") + + def test_interlock_status(self) -> None: + self.assertEqual(p.parse_interlock_status(b"\x00"), "armed") + self.assertEqual(p.parse_interlock_status(b"\xff"), "tripped") + with self.assertRaisesRegex(ValueError, "not been seen"): + p.parse_interlock_status(b"\x01") + # The unsolicited trip event carries the same byte. + event = p.Reply.parse(bytes.fromhex("01010000100300FF")) + self.assertEqual((event.device, event.opcode), p.INTERLOCK_TRIPPED) + self.assertEqual(p.parse_interlock_status(event.payload), "tripped") + + def test_axis_state(self) -> None: + for code, state in [(0x00, "ENABLED"), (0x01, "DISABLED"), (0xFE, "NOT_CONFIGURED"), + (0xFF, "FAULT")]: # fmt: skip + self.assertEqual(p.parse_axis_state(bytes([code])).name, state) + with self.assertRaises(ValueError): + p.parse_axis_state(b"\x02") + + def test_tip_status(self) -> None: + states = p.parse_tip_status(bytes([0, 2, 1, 2, 0, 0, 2, 9])) + self.assertEqual( + states, ["loaded", "unloaded", "unknown", "unloaded", "loaded", "loaded", "unloaded", None] + ) + + def test_motion_complete(self) -> None: + sensed = p.Reply.parse( + bytes([0x11, 9, 0, 5, 0x50, 0x02, 0, p.LLS_LIQUID_SENSED]) + struct.pack(" None: + emcy = p.parse_emcy(bytes.fromhex("007700100116040100")) + self.assertEqual( + (emcy.node, emcy.error_code, emcy.error_register, emcy.device_error, emcy.source), + (0x77, 0x1000, 0x01, 0x0416, 0x01), + ) + + def test_success_has_no_error(self) -> None: + # Get Module ID's DONE; a Move's ACCEPTED and DONE; the host-alive NOTICE (sequence 0). + for message in ("000000010002" + "008000", "110300AC5001" + "00", "110300AC5002" + "00", + "0000000040FE" + "00"): # fmt: skip + self.assertIsNone(p.Reply.parse(bytes.fromhex(message)).error_code, message) + + def test_errors_raise_their_kind(self) -> None: + cases = { + "1103000712" + "0030": NotConfiguredError, + "1103000751" + "0031": NotEnabledError, + "1103000740" + "0032": NotHomedError, + "1003000750" + "000F": InterlockTrippedError, + "1003000750" + "0238": MotionError, + "110300075002" + "3C0001": MotionError, + "1103000750" + "0077": AceError, + } + for message, kind in cases.items(): + with self.subTest(message=message): + reply = p.Reply.parse(bytes.fromhex(message.replace(" ", ""))) + with self.assertRaises(kind): + reply.raise_for_error("request") + + def test_device_error_follows_the_ace_error(self) -> None: + # A Move whose axis left its error window: DONE, ACE error 0x3C, device error 0x0100. + reply = p.Reply.parse(bytes.fromhex("110300075002" + "3C0001")) + self.assertEqual((reply.error_code, reply.device_error), (0x3C, 0x0100)) + with self.assertRaisesRegex(MotionError, r"device error 0x100: motion error window exceeded"): + reply.raise_for_error("Move Z") + + +class SagianCanTests(unittest.TestCase): + """Forwarded SAGIAN CAN messages, worded as the Master Controller's log words them.""" + + # Every distinct pattern in the Master Controller's logs (2026-07-27 .. 10-27), with its words. + LOGGED = { + "00010500000101f7280fbb40": "TO_NODE 05:00 READ SUCCESS F7 28 0F BB 40", + "00010500000001f0": "TO_NODE 05:00 ACTION SUCCESS F0", + "0001050000020101": "TO_NODE 05:00 WRITE SUCCESS 01", + "000105000003016801": "TO_NODE 05:00 EVENT SUCCESS 68 01", + "00012300040300": "TO_NODE 23:04 EVENT REQUEST", + "00012a00080300": "TO_NODE 2A:08 EVENT REQUEST", + } + + def test_logged_messages_read_as_the_master_controller_reads_them(self) -> None: + for data, words in self.LOGGED.items(): + with self.subTest(data=data): + self.assertEqual(p.describe_sagian_can(bytes.fromhex(data)), (words, True)) + + def test_any_other_status_is_not_called_normal(self) -> None: + text, normal = p.describe_sagian_can(bytes.fromhex("00010500000102")) + self.assertFalse(normal) + self.assertIn("status 0x02", text) + self.assertFalse(p.describe_sagian_can(bytes([0, 1]))[1]) + + +class RoutineUnsolicitedTests(unittest.TestCase): + """Unsolicited messages every session sees, as the instrument sent them (2026-11-09).""" + + @staticmethod + def reply(message: str) -> p.Reply: + return p.Reply.parse(bytes.fromhex(message)) + + def test_a_drive_clearing_its_fault_is_routine(self) -> None: + text = p.describe_routine_unsolicited(self.reply("00000000 31ff 007e0000000000000000")) + self.assertEqual(text, "drive node 0x7E: fault cleared (EMCY 0000)") + + def test_a_drive_reporting_the_interlock_is_routine(self) -> None: + for source in ("01", "02"): + with self.subTest(source=source): + text = p.describe_routine_unsolicited( + self.reply(f"0000000031ff007700100116 04{source}0000") + ) + self.assertEqual(text, "drive node 0x77: interlock active (EMCY 1000)") + + def test_a_move_the_interlock_ended_is_routine(self) -> None: + text = p.describe_routine_unsolicited(self.reply("11120000 50fe 0f1604")) + self.assertEqual(text, "device 0x11 index 18: move ended, interlock tripped") + + def test_other_messages_are_shown(self) -> None: + for message in ( + "00000000 31ff 007e0010010704010000", # another drive error: interlock tripped (0407) + "11120000 50fe 3c0001", # a move ended by its error window + "01010000 1003 00ff", # the chassis: the interlock tripped + "21010000 1003 0001", # a digital input changed (the door) + "00000000 31ff 007e", # too short to read + ): + with self.subTest(message=message): + self.assertIsNone(p.describe_routine_unsolicited(self.reply(message.replace(" ", "")))) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/simulator.py b/pylabrobot/beckman_coulter/biomek_i7/driver/simulator.py new file mode 100644 index 00000000000..357375452b9 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/simulator.py @@ -0,0 +1,103 @@ +"""Simulated boards: boards that answer from what a real Biomek i7's boards answered. + +`ReplayAceUSB` replays a recording; nothing it does reaches a USB device. A replayed board holds a +recording of request -> replies, keyed on everything in a request but its sequence number, and +answers a request it has a recording for with those replies under the request's sequence number. +A request it has no recording for gets no answer, as a board that ignored it would, and is kept in +`unanswered`. +""" + +import asyncio +import gzip +import json +import os +from pathlib import Path +from typing import Any, Dict, List, Optional, Union + +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.framing import frame, split +from pylabrobot.io.usb import USB + +# Names the recording the simulator answers from (identity and sensor reads, recorded at an +# instrument's cold start) when no path is given. A generic one ships in `defaults/` +# (`biomek_i7_generic_coldstart.json`). +RECORDING_ENV = "BIOMEK_I7_SIMULATOR_RECORDING" + + +def recording_path(path: Optional[Union[str, Path]] = None) -> Path: + """`path`, else the file `$BIOMEK_I7_SIMULATOR_RECORDING` names. + + Raises: + ValueError: with neither. + """ + path = path or os.environ.get(RECORDING_ENV) + if not path: + raise ValueError( + f"no recording for the simulator to answer from: pass its path or set ${RECORDING_ENV}" + ) + return Path(path) + + +def load_recording(path: Optional[Union[str, Path]] = None) -> Dict[str, Any]: + """A recording (`recording_path`), gzipped (`.gz`) or not.""" + where = recording_path(path) + if where.suffix == ".gz": + with gzip.open(where, "rt", encoding="utf-8") as fh: + return dict(json.load(fh)) + with open(where, encoding="utf-8") as fh: + return dict(json.load(fh)) + + +def _request_key(message: bytes) -> str: + return (message[:3] + message[4:]).hex() + + +class ReplayAceUSB(USB): + """One board's USB link, answered from a recording.""" + + def __init__(self, recording: Dict[str, List[str]], name: str = "replayed ACE board"): + super().__init__(0x0AB5, 0xACE0, name) + self.recording = {k: [bytes.fromhex(r) for r in v] for k, v in recording.items()} + self.requests: List[bytes] = [] + self.unanswered: List[bytes] = [] + self._packets: "asyncio.Queue[bytes]" = asyncio.Queue() + + async def setup(self, empty_buffer=True): + pass + + async def stop(self): + pass + + async def write(self, data: bytes, timeout: Optional[float] = None): + for message in split(data): + self.requests.append(message) + replies = self.recording.get(_request_key(message)) + if replies is None: + self.unanswered.append(message) + continue + for reply in replies: + framed = frame(reply[:3] + message[3:4] + reply[4:]) + for i in range(0, len(framed), 16): + self._packets.put_nowait(framed[i : i + 16]) + + async def read(self, timeout=None, size=None, endpoint=None) -> bytes: + try: + return await asyncio.wait_for(self._packets.get(), timeout=0.05) + except asyncio.TimeoutError: + raise TimeoutError("no packet") from None + + +def replay_boards( + path: Optional[Union[str, Path]] = None, default_timeout: float = 1.0 +) -> List[AceBoard]: + """One replayed board per module in a recording (`recording_path`), as + `BiomekI7Driver(boards=...)` takes them.""" + data = load_recording(path) + return [ + AceBoard( + io=ReplayAceUSB(dict(entries), name=f"replayed {module}"), + name=f"replayed {module}", + default_timeout=default_timeout, + ) + for module, entries in data["boards"].items() + ] diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/simulator_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/simulator_tests.py new file mode 100644 index 00000000000..d8fcebca10c --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/simulator_tests.py @@ -0,0 +1,80 @@ +"""Replayed boards: what they answer, and what they do not.""" + +import gzip +import json +import os +import tempfile +import unittest +from pathlib import Path +from unittest import mock + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.simulator import ( + RECORDING_ENV, + ReplayAceUSB, + load_recording, + recording_path, + replay_boards, +) + +# Get Module ID answered once, and a Move answered twice (ACCEPTED, then DONE); keys leave out the +# sequence number, and the replies' sequence bytes are placeholders. +RECORDING = { + "00000000": ["000000000002008000"], + "1103005030750000": ["11030000500100", "11030000500200"], +} + + +class ReplayTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + self.io = ReplayAceUSB(RECORDING) + self.board = AceBoard(io=self.io, default_timeout=0.3) + await self.board.setup() + + async def asyncTearDown(self) -> None: + await self.board.stop() + + async def test_a_recorded_request_is_answered_under_its_own_sequence(self) -> None: + for _ in range(3): # each send takes the next sequence number; the recording ignores it + reply = await self.board.send(p.get_module_id()) + self.assertEqual(p.parse_module_id(reply.payload).type, "chassis") + self.assertEqual([m[3] for m in self.io.requests], [1, 2, 3]) + self.assertEqual(self.io.unanswered, []) + + async def test_replies_come_in_their_recorded_order(self) -> None: + reply = await self.board.send(p.move(3, 30000)) + self.assertEqual(reply.status, p.Status.DONE) + + async def test_an_unrecorded_request_gets_no_answer(self) -> None: + with self.assertRaises(TimeoutError): + await self.board.send(p.get_module_serial_number()) + self.assertEqual(self.io.unanswered, [p.get_module_serial_number().encode(1)]) + + +class RecordingFileTests(unittest.TestCase): + def test_gzipped_and_plain_recordings_load(self) -> None: + data = {"boards": {"chassis": [["00000000", ["000000000002008000"]]]}} + with tempfile.TemporaryDirectory() as folder: + plain = Path(folder) / "recording.json" + plain.write_text(json.dumps(data), encoding="utf-8") + packed = Path(folder) / "recording.json.gz" + with gzip.open(packed, "wt", encoding="utf-8") as fh: + json.dump(data, fh) + self.assertEqual(load_recording(plain), data) + self.assertEqual(load_recording(packed), data) + boards = replay_boards(packed) + self.assertEqual([b.name for b in boards], ["replayed chassis"]) + + def test_a_recording_must_be_named(self) -> None: + environment = {k: v for k, v in os.environ.items() if k != RECORDING_ENV} + with mock.patch.dict(os.environ, environment, clear=True): + with self.assertRaisesRegex(ValueError, RECORDING_ENV): + recording_path() + with mock.patch.dict(os.environ, {RECORDING_ENV: "from-the-environment.json"}): + self.assertEqual(recording_path(), Path("from-the-environment.json")) + self.assertEqual(recording_path("given.json"), Path("given.json")) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py b/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py new file mode 100644 index 00000000000..c07366257d4 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py @@ -0,0 +1,47 @@ +"""What the package's tests build their simulated Biomek i7 from: the generic one in `defaults/`, +named explicitly (never through `$BIOMEK_I7_SIMULATOR_RECORDING`). Not a test module itself.""" + +import copy +import json +from typing import Any, Dict, List, Optional, Sequence + +from pylabrobot.beckman_coulter.biomek_i7.defaults import GENERIC_RECORDING +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.master import BiomekI7Driver +from pylabrobot.beckman_coulter.biomek_i7.driver.simulator import ReplayAceUSB + +_GENERIC: Optional[Dict[str, Any]] = None + + +def generic_recording() -> Dict[str, Any]: + """The generic cold-start recording, a fresh copy a test may change: `boards` maps each module + (`chassis`, `multichannel`, `span8`) to its [request key, [replies]] pairs.""" + global _GENERIC + if _GENERIC is None: + with open(GENERIC_RECORDING, encoding="utf-8") as fh: + _GENERIC = json.load(fh) + return copy.deepcopy(_GENERIC) + + +def generic_boards( + recording: Optional[Dict[str, Any]] = None, + modules: Optional[Sequence[str]] = None, + default_timeout: float = 1.0, +) -> List[AceBoard]: + """A replayed board per module of `recording` (by default the generic one), as + `simulator.replay_boards` builds them; `modules` picks and orders them.""" + data = recording if recording is not None else generic_recording() + names = list(data["boards"]) if modules is None else list(modules) + return [ + AceBoard( + io=ReplayAceUSB(dict(data["boards"][module]), name=f"replayed {module}"), + name=f"replayed {module}", + default_timeout=default_timeout, + ) + for module in names + ] + + +def generic_driver(boards: Optional[Sequence[AceBoard]] = None) -> BiomekI7Driver: + """A driver over `boards`, by default the generic instrument replayed.""" + return BiomekI7Driver(boards=generic_boards() if boards is None else boards) From 9ed3216bcdfd53290dec92273d18cfb5da53c345 Mon Sep 17 00:00:00 2001 From: Cody Moore <46687103+cmoscy@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:56:32 +0000 Subject: [PATCH 07/11] `Biomek i7`: sort imports for ruff I001 --- pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py index 2bd18e6f5df..892bf89baeb 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py @@ -10,7 +10,6 @@ from pylabrobot.beckman_coulter.biomek_i7.driver.protocol import HardwareVersion, ModuleId - # The firmware this driver has been run against (one instrument, 2026-10-24 through 2026-11-10): # every motion board and module the same image, and the other boards' application versions # (chassis 0.2.4, SAGIAN Motion 0.3.14, LLS 0.7.8, syringe pump 5.0.9). The Master Controller From f0c0f35b17d4bb32c5fb08a5a6e7fae47c230a06 Mon Sep 17 00:00:00 2001 From: cmoscy <46687103+cmoscy@users.noreply.github.com> Date: Wed, 11 Nov 2026 00:00:48 -0800 Subject: [PATCH 08/11] `Biomek i7`: the declared configuration, motor tables and units What the boards cannot report about an instrument, declared per instrument in one JSON file given by path (`declared_configuration_json`, now required): - `driver/configuration.py`: `DeviceConfiguration`, the motor tables (the Master Controller's instrument record: each axis's Configure parameters, home position and measured hysteresis, and the modules' serial numbers) and per pod the conversions, travel limits, geometry and settings from Biomek's instrument file, with the default deck's calibrated positions and layout. Each source's values carry a fingerprint; a file changed after import is refused at load. `anonymized()` makes a generic one: no serial numbers, no measured hysteresis. - `driver/motors.py`: the axes of each arm type and the limits read from their Configure bytes. - `units.py`: the one place PyLabRobot's units (mm, uL, mm/s) meet Biomek's (cm, its frame, the speed field). - `defaults/`: the generic configuration, one instrument's physical values with every serial number removed. - Discovery refuses a pod type other than the declared one, and on the instrument a configuration whose serial numbers are not the modules', or the generic one. Each pod gets its type's axes and its declared values. Tests: conversions give the counts Biomek's logs show for the instrument file's targets, the bridges meet where Biomek's logged moves stopped, save / load and the changed-file refusal, anonymizing, declared against found, the serial-number check on the instrument's own path, every speed field round-tripping on every Z and pump, and the motor tables' limits. --- .../biomek_i7/defaults/__init__.py | 12 +- .../biomek_i7_generic_configuration.json | 2667 +++++++++++++++++ .../beckman_coulter/biomek_i7/design.md | 11 + .../biomek_i7/driver/configuration.py | 452 ++- .../biomek_i7/driver/configuration_tests.py | 184 ++ .../biomek_i7/driver/features/pod.py | 47 +- .../biomek_i7/driver/master.py | 119 +- .../biomek_i7/driver/motors.py | 150 + .../biomek_i7/driver/motors_tests.py | 85 + .../biomek_i7/driver/serial_numbers_tests.py | 104 + .../biomek_i7/simulation_tests_support.py | 64 +- pylabrobot/beckman_coulter/biomek_i7/units.py | 222 ++ .../beckman_coulter/biomek_i7/units_tests.py | 83 + 13 files changed, 4176 insertions(+), 24 deletions(-) create mode 100644 pylabrobot/beckman_coulter/biomek_i7/defaults/biomek_i7_generic_configuration.json create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/configuration_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/motors.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/motors_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/units.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/units_tests.py diff --git a/pylabrobot/beckman_coulter/biomek_i7/defaults/__init__.py b/pylabrobot/beckman_coulter/biomek_i7/defaults/__init__.py index b7118bd6e87..5521919f901 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/defaults/__init__.py +++ b/pylabrobot/beckman_coulter/biomek_i7/defaults/__init__.py @@ -1,13 +1,15 @@ -"""A generic Biomek i7's cold start: what a simulated instrument answers when given no instrument's -own recording. +"""A generic Biomek i7: what a simulation is given when it has no instrument's own files. -Made from one instrument's cold-start recording (the requests the Master Controller sent at a -start and the boards' replies), with every serial number replaced by a placeholder of the same -length. +Made from one instrument's declared configuration and cold-start recording, with every serial +number and name removed. Its physical values (motor tables, conversions, travel, geometry, +settings, the default deck's calibration and layout) are that instrument's, so another +instrument's differ: drive an instrument with its own files. The configuration is marked +`generic` and carries no serial numbers, so a live session refuses it (`BiomekI7Driver.discover`). """ from pathlib import Path HERE = Path(__file__).parent +GENERIC_CONFIGURATION = HERE / "biomek_i7_generic_configuration.json" GENERIC_RECORDING = HERE / "biomek_i7_generic_coldstart.json" diff --git a/pylabrobot/beckman_coulter/biomek_i7/defaults/biomek_i7_generic_configuration.json b/pylabrobot/beckman_coulter/biomek_i7/defaults/biomek_i7_generic_configuration.json new file mode 100644 index 00000000000..e33fd37ffb0 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/defaults/biomek_i7_generic_configuration.json @@ -0,0 +1,2667 @@ +{ + "generic": true, + "chassis_serial_number": null, + "instrument_serial_number": null, + "sources": { + "instrument_file": { + "fingerprint": "sha256:9cbfcd7168db1a0a0e9f6436c4d1479bc1664e1c39c7e4c125f5694b96dee046" + }, + "master_controller": { + "fingerprint": "sha256:f4aceddd504ac0579c6fee9dad49a9ec4a637f2bd538ae4cd9a8191445a0af07" + } + }, + "pods": { + "left": { + "component": "MC_1", + "module_type": "multichannel", + "module_serial_number": null, + "source": "bif:Devices/Pipettor1/Pod1", + "conversion": { + "D": { + "const": 229.932355946194, + "offset": 187.7766869, + "unit": "uL" + }, + "GG": { + "const": 18334.65, + "offset": -5.981, + "unit": "cm" + }, + "GR": { + "const": -376.2492651, + "offset": 376.295, + "unit": "deg" + }, + "GY": { + "const": 1982.2617, + "offset": -15.833, + "unit": "cm" + }, + "GZ": { + "const": 1591.549, + "offset": -37.949, + "unit": "cm" + }, + "X": { + "const": 2560.0, + "offset": -10.518999999999998, + "unit": "cm" + }, + "Y": { + "const": 2560.0, + "offset": -14.446000000000002, + "unit": "cm" + }, + "Z": { + "const": 2560.0, + "offset": -39.863, + "unit": "cm" + } + }, + "limits": { + "D": [ + -185.9935538, + 1200.0 + ], + "GG": [ + 5.981, + 15.681 + ], + "GR": [ + -370.0, + 190.0 + ], + "GY": [ + 15.834, + 62.683 + ], + "GZ": [ + 6.943, + 37.949 + ], + "X": [ + 10.52, + 108.7457 + ], + "Y": [ + 14.596, + 59.5976 + ], + "Z": [ + 11.153599999999999, + 39.863 + ] + }, + "geometry": { + "bridge_x_span": 39.0154, + "bridge_to_head_x_offset": 11.020399999999999, + "mandrel1_x_offset": 4.353700000000001, + "mandrel1_y_offset": 2.5650000000000004, + "mandrel_x_spacing": 0.9, + "mandrel_y_spacing": 0.9, + "avoidance_margin": 0.2164, + "pod_x_span": 18.606, + "pod_y_span": 11.43, + "gripper_x_offset": 0.309, + "gripper_y_offset": 0.206, + "gripper_z_offset": -7.304, + "frame_safety_left": 0.5, + "frame_safety_right": 1.5, + "additional_safe_height": 0.5336, + "additional_safe_height_gripper": 0.5336, + "mandrels_x": 12, + "mandrels_y": 8, + "sub_mandrel_safe_height": 0.2705 + }, + "park": { + "GG": 7.889, + "GR": 90.0, + "GY": 48.0, + "GZMargin": -0.1, + "XMargin": 14.0, + "Y": 29.0, + "ZMargin": -0.1 + }, + "settings": { + "AlwaysMaxZ": false, + "AStarSearchLimit": 10000, + "DAxisULPerCM": 178.139348120214, + "DiscardStackHeightThreshold": 5.6, + "DiscardWiderUnsqueeze": 10.326, + "Fixed": true, + "GlobalMinSafeHeight": -100000.0, + "HeadBodyXSpan": 13.0175, + "HeadBodyYSpan": 7.9375, + "HeadFlangeHeight": 1.0795, + "HeadHeight": 9.8171, + "HeadSerialNumber": null, + "HeadType": "MC96_1200", + "HeadTypeLabel": "1200 \u00b5L MC-96 Head", + "HomingTimeout": 300000, + "HysteresisX": 1.0, + "HysteresisY": 1.0, + "LeftPod": true, + "ManualControlSafety": 0.5, + "MaxAllowedPositionDiffAfterRetry": 0.05, + "Name": "Pod1", + "NotHomedCode": "needs to be homed", + "PerActionOverhead": 0.001, + "PerMoveActionOverhead": 0.005, + "PodName": "MC_1", + "PodToHeadBodyXOffset": 2.795000000000001, + "PodToHeadBodyYOffset": 1.7462500000000007, + "PodType": "MC", + "PodTypeLabel": "Multichannel Pod", + "PruneMoves": true, + "RetrySpeed": 20, + "RotationPenalty": 10.0, + "SensorEnabled": false, + "SpeedLimit": 100.0, + "TimeoutSlop": 25.0, + "TipLoadForceLimitOffset": 250.0, + "TipLoadForceLimitSlope": 2150, + "TipLoadOverheadTime": 5.2, + "TipLoadPushOffDistance": 0.292, + "TipLoadPushOffSpeed": 5, + "TipLoadRelieveSpeed": 5, + "TipLoadRelieveZOffset": -0.7, + "TipLoadSettlingTime": 2.0, + "TipLoadSpeed": 10, + "TipLoadStartZOffset": 0.0, + "TipLoadXRangePadding": 70.5978, + "TipLoadZOffset": -1.25, + "TipSeatingDepth": 0.7074, + "TipUnloadShuckSpeed": 100, + "TipUnloadZOffset": -0.661, + "Type": "Pod96", + "UI_CLSID": "{b6711077-a389-4d59-8f40-95c4129106da}", + "WarningThresholdAngleChange": 0.25, + "WarningThresholdGripChange": 0.01, + "Head/PodToMandrel1": { + "X": 2.0477, + "Y": -6.325, + "Z": -10.5245 + }, + "GripperSqueezeForce": 5.0 + }, + "gripper_model": { + "Finger": { + "Base": [ + { + "X": -1.45, + "Y": 0.778 + }, + { + "X": 3.894, + "Y": 0.778 + }, + { + "X": 3.894, + "Y": 0.27 + }, + { + "X": 11.668, + "Y": -5.946999999999999 + }, + { + "X": 13.316, + "Y": -5.946999999999999 + }, + { + "X": 13.316, + "Y": -7.279999999999999 + }, + { + "X": 9.544, + "Y": -7.279999999999999 + }, + { + "X": 9.544, + "Y": -5.566000000000001 + }, + { + "X": 3.574, + "Y": -0.619 + }, + { + "X": -1.45, + "Y": -0.619 + } + ], + "BaseWithProbes": [ + { + "X": -1.45, + "Y": 0.778 + }, + { + "X": 3.894, + "Y": 0.778 + }, + { + "X": 3.894, + "Y": 0.27 + }, + { + "X": 11.668, + "Y": -5.946999999999999 + }, + { + "X": 11.90625, + "Y": -5.946999999999999 + }, + { + "X": 11.90625, + "Y": -9.234 + }, + { + "X": 9.544, + "Y": -9.234 + }, + { + "X": 9.544, + "Y": -5.566000000000001 + }, + { + "X": 3.574, + "Y": -0.619 + }, + { + "X": -1.45, + "Y": -0.619 + } + ], + "BottomPart": { + "FingerwiseSpan": 9.421, + "TopSurface": -0.508, + "ZOffset": 0.27, + "ZSpan": 7.55 + }, + "ClipperThickness": 0.106, + "ExtensionSpan": 9.065, + "FingerCenterOffset": -0.003, + "FingerMountOriginSpanAtHardstop": 6.321, + "FingerwiseOffset": 0.6330000000000002, + "LWFingerSpacing": 0.191, + "OverallAngledThickness": 1.022, + "PadsCenterToRotationCenter": 11.443, + "Thickness": 0.635, + "TopPart": { + "FingerwiseSpan": 5.345, + "ZSpan": 0.619 + } + }, + "Lowerhand": { + "FingerwiseSpan": 4.166, + "YSpanNoFingerMountExtension": 9.525, + "ZSpan": 3.175 + }, + "Upperhand": { + "CenterXOffset": 0.0, + "CenterYOffset": 0.0, + "XSpan": 4.851, + "YSpan": 8.165, + "ZSpan": 8.949 + } + }, + "obstacles": [ + { + "name": "BackLeftTower", + "buffer": 0.2, + "x2": 3.117, + "y2": 12.177 + }, + { + "name": "LeftShield", + "buffer": 0.2, + "x2": -6.496, + "y2": 70.24600000000001 + }, + { + "name": "LightCurtain", + "buffer": 0.5, + "y1": 70.24600000000001 + }, + { + "name": "BackShield", + "buffer": 0.2, + "y2": -2.0920000000000005 + }, + { + "name": "IBeam", + "buffer": 0.2, + "y2": 11.091999999999999, + "z1": 37.069 + }, + { + "name": "RightShield", + "buffer": 0.2, + "x1": 158.41400000000002, + "y2": 70.24600000000001 + }, + { + "name": "Floor", + "buffer": 0.2, + "z1": -500.0, + "z2": 0.0 + }, + { + "name": "BackRightTower", + "buffer": 0.2, + "x1": 148.8, + "y2": 12.177 + }, + { + "name": "LeftCamera", + "buffer": 0.2, + "x2": -1.6689999999999998, + "y1": 65.561, + "z1": 32.078 + }, + { + "name": "RightCamera", + "buffer": 0.2, + "x1": 153.586, + "y1": 65.561, + "z1": 32.078 + }, + { + "name": "PumpBank", + "buffer": 0.2, + "x1": 121.044, + "y2": 13.447, + "z2": 37.069 + } + ] + }, + "right": { + "component": "SPAN8_2", + "module_type": "span8", + "module_serial_number": null, + "source": "bif:Devices/Pipettor1/Pod2", + "conversion": { + "D1": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "D2": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "D3": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "D4": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "D5": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "D6": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "D7": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "D8": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "D": { + "const": 24.0, + "offset": 0.0, + "unit": "uL" + }, + "GG": { + "const": 18334.65, + "offset": -5.987, + "unit": "cm" + }, + "GR": { + "const": -376.2492651, + "offset": 377.175, + "unit": "deg" + }, + "GY": { + "const": 1982.2617, + "offset": -15.901, + "unit": "cm" + }, + "GZ": { + "const": 1591.549, + "offset": -37.931, + "unit": "cm" + }, + "S": { + "const": 4713.0, + "offset": -6.3, + "unit": "cm" + }, + "X": { + "const": 2560.0, + "offset": -146.40669375, + "unit": "cm" + }, + "Y": { + "const": 4713.0, + "offset": -15.123735233662208, + "unit": "cm" + }, + "Z1": { + "const": 4823.423, + "offset": -37.235921235034354, + "unit": "cm" + }, + "Z2": { + "const": 4823.423, + "offset": -37.20402123503435, + "unit": "cm" + }, + "Z3": { + "const": 4823.423, + "offset": -37.23722123503438, + "unit": "cm" + }, + "Z4": { + "const": 4823.423, + "offset": -37.305421235034345, + "unit": "cm" + }, + "Z5": { + "const": 4823.423, + "offset": -37.27122123503436, + "unit": "cm" + }, + "Z6": { + "const": 4823.423, + "offset": -37.222921235034356, + "unit": "cm" + }, + "Z7": { + "const": 4823.423, + "offset": -37.21462123503436, + "unit": "cm" + }, + "Z8": { + "const": 4823.423, + "offset": -37.22662123503437, + "unit": "cm" + }, + "Z": { + "const": 4823.423, + "offset": -42.81242123503436, + "unit": "cm" + } + }, + "limits": { + "D": [ + 0.0, + 1000.0 + ], + "D1": [ + 0.0, + 1000.0 + ], + "D2": [ + 0.0, + 1000.0 + ], + "D3": [ + 0.0, + 1000.0 + ], + "D4": [ + 0.0, + 1000.0 + ], + "D5": [ + 0.0, + 1000.0 + ], + "D6": [ + 0.0, + 1000.0 + ], + "D7": [ + 0.0, + 1000.0 + ], + "D8": [ + 0.0, + 1000.0 + ], + "GG": [ + 5.987, + 15.687 + ], + "GR": [ + -370.0, + 190.0 + ], + "GY": [ + 15.902, + 62.966 + ], + "GZ": [ + 6.925, + 37.931 + ], + "Span": [ + 6.3, + 35.0 + ], + "X": [ + 48.199, + 146.406 + ], + "Y": [ + 15.274, + 66.455 + ], + "Z": [ + 22.635421235034357, + 39.52602123503435 + ], + "Z1": [ + 17.05892123503436, + 39.55792123503436 + ], + "Z2": [ + 17.05892123503436, + 39.52602123503435 + ], + "Z3": [ + 17.05892123503436, + 39.559221235034386 + ], + "Z4": [ + 17.05892123503436, + 39.62742123503435 + ], + "Z5": [ + 17.05892123503436, + 39.59322123503436 + ], + "Z6": [ + 17.05892123503436, + 39.54492123503436 + ], + "Z7": [ + 17.05892123503436, + 39.53662123503436 + ], + "Z8": [ + 17.05892123503436, + 39.548621235034375 + ] + }, + "geometry": { + "bridge_x_span": 25.7204, + "bridge_to_head_x_offset": 13.274799999999999, + "mandrel1_x_offset": 1.0, + "mandrel1_y_offset": 1.0, + "mandrel_x_spacing": 0.9, + "mandrel_y_spacing": 0.9, + "avoidance_margin": 0.2164, + "pod_x_span": 4.0, + "pod_y_span": 10.0, + "gripper_x_offset": 1.445, + "gripper_y_offset": 0.2, + "gripper_z_offset": -7.398, + "frame_safety_left": 1.0, + "frame_safety_right": 1.5, + "additional_safe_height": 1.0, + "additional_safe_height_gripper": 0.5336 + }, + "park": { + "GG": 7.889, + "GR": 90.0, + "GY": 48.0, + "GZMargin": -0.1, + "ZMargin": -0.1 + }, + "settings": { + "ADSlowMoveRange": 0.5, + "AlwaysMaxZ": false, + "AStarSearchLimit": 12500, + "CalibrateVolumeForProbes": false, + "D1SpeedLimit": 80.1724, + "D2SpeedLimit": 80.1724, + "D3SpeedLimit": 80.1724, + "D4SpeedLimit": 80.1724, + "D5SpeedLimit": 80.1724, + "D6SpeedLimit": 80.1724, + "D7SpeedLimit": 80.1724, + "D8SpeedLimit": 80.1724, + "DetectTips": true, + "DiscardHeight": 39.52602123503435, + "DiscardOffset": 0.35, + "DiscardOvershoot": 0.0, + "DiscardOvershootFixed": true, + "DiscardSpeed": 25, + "DiscardStackHeightThreshold": 5.6, + "DiscardWiderUnsqueeze": 10.326, + "DSpeedLimit": 100.0, + "Fixed": false, + "FixedHomingOffset": 0.2134, + "FixedProbeZOffset": 5.7899, + "GlobalMinSafeHeight": -100000.0, + "HeadSerialNumber": null, + "HeadType": "Unknown", + "HomingTimeout": 300000, + "HysteresisX": 1.0, + "HysteresisY": 1.0, + "LeftPod": false, + "LoadSpeed": 25, + "MandrelExtender": 5.7899, + "ManualControlSafety": 0.5, + "MaxAllowedPositionDiffAfterRetry": 0.05, + "MaxLoadingProbes": 2, + "MaxSafeDeltaY": 2.0, + "MaxSafeDeltaZ": 10.0, + "MaxUnloadingProbes": 4, + "MinLoadingInterval": 4, + "MinUnloadingInterval": 1, + "Name": "Pod2", + "NotHomedCode": "needs to be homed", + "OverrideRTSimulatedLLS": true, + "PerActionOverhead": 0.001, + "PerMoveActionOverhead": 0.005, + "PodName": "SPAN8_2", + "PodType": "SPAN8", + "PodTypeLabel": "Span Pod", + "PostClotDetectionPause": 0.1, + "PostRunWashVolume": 1.0, + "ProbeCount": 8, + "ProbeReservoirYMargin": 0.16256, + "ProbeSize": 0.9, + "ProbeSwitchPoint": 11.0, + "PruneMoves": true, + "realvsExpected1_7": -0.010500000000000398, + "RetrySpeed": 20, + "RH_Backoff": 50.0, + "RotationPenalty": 10.0, + "SensorEnabled": true, + "SpeedLimit": 100, + "STAGSpeed": 1, + "SystemTrailingAirgap": 20.0, + "TimeoutSlop": 25.0, + "TiploadExitZOffset": 2.0, + "TipLoadTime": 8.0, + "TipLoadZOffset": -0.77, + "TipShuckDiameter": 0.83, + "Type": "Pod8Span", + "UI_CLSID": "{fbe216b4-1c3a-4bac-91d0-53c036b3de70}", + "UISpanToRealSpan": 0.7, + "UnloadSpeed": 35, + "UseAccessPoints": false, + "ValveMoveTime": 0.35, + "ValveNoMoveTime": 0.045, + "WarningThresholdAngleChange": 0.25, + "WarningThresholdGripChange": 0.01, + "XShift1_7": -0.02970000000000539, + "BrokenTips": [ + false, + false, + false, + false, + false, + false, + false, + false + ], + "LoadingOffsets": [ + -0.05, + -0.05, + -0.05, + -0.05, + -0.05, + -0.05, + -0.05, + -0.05 + ], + "DefaultTipHubInfo": { + "Length": 0.9779, + "MaxRadius": 0.3429, + "MinRadius": 0.3302 + }, + "LLSWireModel": { + "AnchorCenterY": 40.721, + "AnchorHalfLength": 4.166, + "AnchorXOffset": 9.953, + "FixedTipZOriginToWireOffset": 3.371, + "WireBottomAtZMax": 29.78, + "WireStartXOffset": 2.6 + }, + "GripperSqueezeForce": 5.0 + }, + "gripper_model": { + "Finger": { + "Base": [ + { + "X": -1.45, + "Y": 0.778 + }, + { + "X": 3.894, + "Y": 0.778 + }, + { + "X": 3.894, + "Y": 0.27 + }, + { + "X": 11.668, + "Y": -5.946999999999999 + }, + { + "X": 13.316, + "Y": -5.946999999999999 + }, + { + "X": 13.316, + "Y": -7.279999999999999 + }, + { + "X": 9.544, + "Y": -7.279999999999999 + }, + { + "X": 9.544, + "Y": -5.566000000000001 + }, + { + "X": 3.574, + "Y": -0.619 + }, + { + "X": -1.45, + "Y": -0.619 + } + ], + "BaseWithProbes": [ + { + "X": -1.45, + "Y": 0.778 + }, + { + "X": 3.894, + "Y": 0.778 + }, + { + "X": 3.894, + "Y": 0.27 + }, + { + "X": 11.668, + "Y": -5.946999999999999 + }, + { + "X": 11.90625, + "Y": -5.946999999999999 + }, + { + "X": 11.90625, + "Y": -9.234 + }, + { + "X": 9.544, + "Y": -9.234 + }, + { + "X": 9.544, + "Y": -5.566000000000001 + }, + { + "X": 3.574, + "Y": -0.619 + }, + { + "X": -1.45, + "Y": -0.619 + } + ], + "BottomPart": { + "FingerwiseSpan": 9.421, + "TopSurface": -0.508, + "ZOffset": 0.27, + "ZSpan": 7.55 + }, + "ClipperThickness": 0.106, + "ExtensionSpan": 9.065, + "FingerCenterOffset": 0.014, + "FingerMountOriginSpanAtHardstop": 6.321, + "FingerwiseOffset": 0.6330000000000002, + "LWFingerSpacing": 0.191, + "OverallAngledThickness": 1.022, + "PadsCenterToRotationCenter": 11.42, + "Thickness": 0.635, + "TopPart": { + "FingerwiseSpan": 5.345, + "ZSpan": 0.619 + } + }, + "Lowerhand": { + "FingerwiseSpan": 4.166, + "YSpanNoFingerMountExtension": 9.525, + "ZSpan": 3.175 + }, + "Upperhand": { + "CenterXOffset": 0.0, + "CenterYOffset": 0.0, + "XSpan": 4.851, + "YSpan": 8.165, + "ZSpan": 8.949 + } + }, + "obstacles": [ + { + "name": "BackLeftTower", + "buffer": 0.2, + "x2": 3.117, + "y2": 12.177 + }, + { + "name": "LightCurtain", + "buffer": 0.5, + "y1": 70.246 + }, + { + "name": "BackShield", + "buffer": 0.2, + "y2": -2.092 + }, + { + "name": "IBeam", + "buffer": 0.2, + "y2": 11.092, + "z1": 37.069 + }, + { + "name": "Floor", + "buffer": 0.2, + "z1": -500.0, + "z2": 0.0 + }, + { + "name": "LeftCamera", + "buffer": 0.2, + "x2": -1.669, + "y1": 65.561, + "z1": 32.078 + }, + { + "name": "BackRightTower", + "buffer": 0.2, + "x1": 148.8, + "y2": 12.177 + }, + { + "name": "RightCamera", + "buffer": 0.2, + "x1": 153.586, + "y1": 65.561, + "z1": 32.078 + }, + { + "name": "RightShield", + "buffer": 0.2, + "x1": 158.414, + "y2": 70.246 + }, + { + "name": "PumpBank", + "buffer": 0.2, + "x1": 121.044, + "y2": 13.447, + "z2": 37.069 + }, + { + "name": "LeftShield", + "buffer": 0.2, + "x2": -7.874, + "y2": 70.246 + } + ] + } + }, + "deck_positions": { + "BS1": { + "corners": { + "1": [ + 40.3464, + 15.4873, + 16.0968 + ], + "2": [ + 40.423, + 15.474, + 16.1 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "CP1": { + "corners": { + "1": [ + 98.8117, + 15.3923, + 16.7973 + ], + "2": [ + 98.742, + 15.474, + 16.3 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "P1": { + "corners": { + "1": [ + 40.4144, + 25.8845, + 15.9601 + ], + "2": [ + 40.418, + 25.888, + 15.965 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "P10": { + "corners": { + "1": [ + 69.579, + 57.17080029449462, + 15.966 + ], + "2": [ + 69.58119999999998, + 57.16830029449462, + 15.9787 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Deck" + } + }, + "P11": { + "corners": { + "1": [ + 84.1574, + 36.3236, + 15.9652 + ], + "2": [ + 84.156, + 36.302, + 15.965 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "P12": { + "corners": { + "1": [ + 84.162, + 46.736, + 15.968 + ], + "2": [ + 84.1707, + 46.737, + 15.9679 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Position" + } + }, + "P13": { + "corners": { + "1": [ + 84.155, + 57.175900294494625, + 15.972 + ], + "2": [ + 84.15719999999999, + 57.17340029449463, + 15.9851 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Deck" + } + }, + "P14": { + "corners": { + "1": [ + 98.691, + 25.939, + 15.974 + ], + "2": [ + 98.7398, + 25.9237, + 15.9713 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Position" + } + }, + "P15": { + "corners": { + "1": [ + 98.715, + 36.324, + 15.975 + ], + "2": [ + 98.7468, + 36.3267, + 15.9744 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Position" + } + }, + "P16": { + "corners": { + "1": [ + 98.709, + 46.744, + 15.972 + ], + "2": [ + 98.7184, + 46.7501, + 15.9737 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Position" + } + }, + "P17": { + "corners": { + "1": [ + 98.723, + 57.177, + 15.964 + ], + "2": [ + 98.7366, + 57.1795, + 15.9766 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Position" + } + }, + "P18": { + "corners": { + "1": [ + 113.314, + 15.476, + 15.964 + ], + "2": [ + 113.3297, + 15.4973, + 15.9615 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Position" + } + }, + "P19": { + "corners": { + "1": [ + 113.314, + 25.89, + 15.964 + ], + "2": [ + 113.3246, + 25.9146, + 15.9659 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Position" + } + }, + "P2": { + "corners": { + "1": [ + 40.4558, + 36.313, + 16.0101 + ], + "2": [ + 40.418, + 36.302, + 15.965 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "P20": { + "corners": { + "1": [ + 113.314, + 36.304, + 15.964 + ], + "2": [ + 113.3359, + 36.3325, + 15.9708 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Position" + } + }, + "P21": { + "corners": { + "1": [ + 113.314, + 46.718, + 15.964 + ], + "2": [ + 113.3125, + 46.7644, + 15.9665 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Position" + } + }, + "P22": { + "corners": { + "1": [ + 113.314, + 57.132, + 15.964 + ], + "2": [ + 113.3238, + 57.181, + 15.9735 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Position" + } + }, + "P23": { + "corners": { + "1": [ + 127.893, + 46.718, + 15.964 + ], + "2": [ + 127.8847, + 46.7469, + 15.9565 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Position" + } + }, + "P24": { + "corners": { + "1": [ + 127.893, + 57.132, + 15.964 + ], + "2": [ + 127.8928, + 57.1835, + 15.9636 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Position" + } + }, + "P3": { + "corners": { + "1": [ + 40.4703, + 46.7005, + 16.0425 + ], + "2": [ + 40.418, + 46.716, + 15.965 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "P4": { + "corners": { + "1": [ + 40.4777, + 57.1474, + 16.0187 + ], + "2": [ + 40.418, + 57.13, + 15.965 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "P5": { + "corners": { + "1": [ + 55.0039, + 36.3134, + 15.9538 + ], + "2": [ + 54.997, + 36.302, + 15.965 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "P6": { + "corners": { + "1": [ + 54.996, + 46.729, + 15.969 + ], + "2": [ + 55.0004, + 46.7289, + 15.9686 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Position" + } + }, + "P7": { + "corners": { + "1": [ + 54.994, + 57.16830029449462, + 15.971 + ], + "2": [ + 54.99619999999999, + 57.16580029449462, + 15.9839 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Deck" + } + }, + "P8": { + "corners": { + "1": [ + 69.572, + 36.325, + 15.963 + ], + "2": [ + 69.6, + 36.3197, + 15.965 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Position" + } + }, + "P9": { + "corners": { + "1": [ + 69.584, + 46.737, + 15.962 + ], + "2": [ + 69.6464, + 46.7379, + 15.9609 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Position" + } + }, + "TA1": { + "corners": { + "1": [ + 129.977, + 36.098, + 15.959 + ], + "2": [ + 129.9485, + 36.3464, + 15.9532 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Not", + "2": "Position" + } + }, + "TL1": { + "corners": { + "1": [ + 11.2464, + 36.3048, + 16.1996 + ], + "2": [ + 11.259, + 36.302, + 16.219 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "TL10": { + "corners": { + "1": [ + 25.8297, + 15.4482, + 16.2324 + ], + "2": [ + 25.838, + 15.474, + 16.219 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "TL11": { + "corners": { + "1": [ + 25.8394, + 25.8775, + 16.209 + ], + "2": [ + 25.838, + 25.888, + 16.219 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "TL2": { + "corners": { + "1": [ + 11.2418, + 46.7271, + 16.2016 + ], + "2": [ + 11.259, + 46.716, + 16.219 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "TL3": { + "corners": { + "1": [ + 11.2511, + 57.1587, + 16.2016 + ], + "2": [ + 11.259, + 57.13, + 16.219 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "TL4": { + "corners": { + "1": [ + 25.8414, + 36.315, + 16.2141 + ], + "2": [ + 25.838, + 36.302, + 16.219 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "TL5": { + "corners": { + "1": [ + 25.8609, + 46.7377, + 16.211 + ], + "2": [ + 25.838, + 46.716, + 16.219 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "TL6": { + "corners": { + "1": [ + 25.8461, + 57.1603, + 16.2098 + ], + "2": [ + 25.838, + 57.13, + 16.219 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Position", + "2": "Deck" + } + }, + "TR1": { + "corners": { + "1": [ + 10.94730025939942, + 17.57920008850098, + 20.7014 + ], + "2": [ + 10.949500259399407, + 17.57670008850098, + 20.7016 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Deck" + } + }, + "TR2": { + "corners": { + "1": [ + 128.2010999909401, + 17.57920008850098, + 20.7014 + ], + "2": [ + 128.20329999094008, + 17.57670008850098, + 20.7016 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Deck" + } + }, + "W2": { + "corners": { + "1": [ + 142.26539992294312, + 56.92709994659424, + 22.2255 + ], + "2": [ + 142.26759992294313, + 56.92459994659424, + 22.2257 + ] + }, + "x_span": 3.175, + "y_span": 8.9992, + "framed": { + "1": "Deck", + "2": "Deck" + } + }, + "W3": { + "corners": { + "1": [ + 78.62710000000004, + 14.321300000000033, + 10.689400000000001 + ], + "2": [ + 78.62930000000003, + 14.318800000000035, + 10.839200000000002 + ] + }, + "x_span": 12.819, + "y_span": 8.59, + "framed": { + "1": "Deck", + "2": "Deck" + } + } + }, + "deck_layout": [ + { + "name": "TrashLeftBin_1", + "alp_type": "TrashLeftBin", + "column": 6, + "row": 12, + "positions": [ + "TR1" + ], + "x1": -7.5796997406005815 + }, + { + "name": "TipLoad1x1_1", + "alp_type": "TipLoad1x1", + "column": 6, + "row": 20, + "positions": [ + "TL1" + ], + "x1": 10.80570000190735 + }, + { + "name": "TipLoad1x1_2", + "alp_type": "TipLoad1x1", + "column": 6, + "row": 25, + "positions": [ + "TL2" + ], + "x1": 10.80110000190735 + }, + { + "name": "TipLoad1x1_3", + "alp_type": "TipLoad1x1", + "column": 6, + "row": 30, + "positions": [ + "TL3" + ], + "x1": 10.81040000190735 + }, + { + "name": "TipLoad1x1_10", + "alp_type": "TipLoad1x1", + "column": 13, + "row": 10, + "positions": [ + "TL10" + ], + "x1": 25.388600000000004 + }, + { + "name": "TipLoad1x1_11", + "alp_type": "TipLoad1x1", + "column": 13, + "row": 15, + "positions": [ + "TL11" + ], + "x1": 25.398300000000006 + }, + { + "name": "TipLoad1x1_6", + "alp_type": "TipLoad1x1", + "column": 13, + "row": 20, + "positions": [ + "TL4" + ], + "x1": 25.400300001907354 + }, + { + "name": "TipLoad1x1_5", + "alp_type": "TipLoad1x1", + "column": 13, + "row": 25, + "positions": [ + "TL5" + ], + "x1": 25.419800001907355 + }, + { + "name": "TipLoad1x1_4", + "alp_type": "TipLoad1x1", + "column": 13, + "row": 30, + "positions": [ + "TL6" + ], + "x1": 25.405000001907354 + }, + { + "name": "Static1x1_3", + "alp_type": "Static1x1", + "column": 20, + "row": 15, + "positions": [ + "P1" + ], + "x1": 39.97340000190736 + }, + { + "name": "Static1x1_25", + "alp_type": "Static1x1", + "column": 20, + "row": 20, + "positions": [ + "P2" + ], + "x1": 40.01430000000002 + }, + { + "name": "Static1x1_26", + "alp_type": "Static1x1", + "column": 20, + "row": 25, + "positions": [ + "P3" + ], + "x1": 40.02880000000002 + }, + { + "name": "Static1x1_27", + "alp_type": "Static1x1", + "column": 20, + "row": 30, + "positions": [ + "P4" + ], + "x1": 40.036200000000015 + }, + { + "name": "BioShake_1", + "alp_type": "BioShake", + "column": 21, + "row": 10, + "positions": [ + "BS1" + ], + "x1": 39.650700000000015 + }, + { + "name": "Static1x1_28", + "alp_type": "Static1x1", + "column": 27, + "row": 20, + "positions": [ + "P5" + ], + "x1": 54.56300000000002 + }, + { + "name": "Static1x1_6", + "alp_type": "Static1x1", + "column": 27, + "row": 25, + "positions": [ + "P6" + ], + "x1": 54.55550000190736 + }, + { + "name": "Static1x1_7", + "alp_type": "Static1x1", + "column": 27, + "row": 30, + "positions": [ + "P7" + ], + "x1": 54.55320000190736 + }, + { + "name": "ELx405DW_1", + "alp_type": "ELx405DW", + "column": 32, + "row": 11, + "positions": [ + "W3" + ], + "x1": 54.85710000000004 + }, + { + "name": "Static1x1_24", + "alp_type": "Static1x1", + "column": 34, + "row": 20, + "positions": [ + "P8" + ], + "x1": 69.13050000190735 + }, + { + "name": "Static1x1_9", + "alp_type": "Static1x1", + "column": 34, + "row": 25, + "positions": [ + "P9" + ], + "x1": 69.14280000190737 + }, + { + "name": "Static1x1_8", + "alp_type": "Static1x1", + "column": 34, + "row": 30, + "positions": [ + "P10" + ], + "x1": 69.13760000190736 + }, + { + "name": "Static1x1_29", + "alp_type": "Static1x1", + "column": 41, + "row": 20, + "positions": [ + "P11" + ], + "x1": 83.7167 + }, + { + "name": "Static1x1_10", + "alp_type": "Static1x1", + "column": 41, + "row": 25, + "positions": [ + "P12" + ], + "x1": 83.72100000190736 + }, + { + "name": "Static1x1_11", + "alp_type": "Static1x1", + "column": 41, + "row": 30, + "positions": [ + "P13" + ], + "x1": 83.71470000190736 + }, + { + "name": "Static1x1_14", + "alp_type": "Static1x1", + "column": 48, + "row": 15, + "positions": [ + "P14" + ], + "x1": 98.25030000190736 + }, + { + "name": "Static1x1_23", + "alp_type": "Static1x1", + "column": 48, + "row": 20, + "positions": [ + "P15" + ], + "x1": 98.27370000190736 + }, + { + "name": "Static1x1_13", + "alp_type": "Static1x1", + "column": 48, + "row": 25, + "positions": [ + "P16" + ], + "x1": 98.26750000190737 + }, + { + "name": "Static1x1_12", + "alp_type": "Static1x1", + "column": 48, + "row": 30, + "positions": [ + "P17" + ], + "x1": 98.28230000190736 + }, + { + "name": "ColdPlate_1", + "alp_type": "ColdPlate", + "column": 49, + "row": 10, + "positions": [ + "CP1" + ], + "x1": 98.11540000000001 + }, + { + "name": "Static1x1_16", + "alp_type": "Static1x1", + "column": 55, + "row": 10, + "positions": [ + "P18" + ], + "x1": 112.87250000190735 + }, + { + "name": "Static1x1_17", + "alp_type": "Static1x1", + "column": 55, + "row": 15, + "positions": [ + "P19" + ], + "x1": 112.87250000190735 + }, + { + "name": "Static1x1_18", + "alp_type": "Static1x1", + "column": 55, + "row": 20, + "positions": [ + "P20" + ], + "x1": 112.87250000190735 + }, + { + "name": "Static1x1_19", + "alp_type": "Static1x1", + "column": 55, + "row": 25, + "positions": [ + "P21" + ], + "x1": 112.87250000190735 + }, + { + "name": "Static1x1_20", + "alp_type": "Static1x1", + "column": 55, + "row": 30, + "positions": [ + "P22" + ], + "x1": 112.87250000190735 + }, + { + "name": "TrashRightBin_1", + "alp_type": "TrashRightBin", + "column": 62, + "row": 12, + "positions": [ + "TR2" + ], + "x1": 127.1010999909401 + }, + { + "name": "Static1x1_22", + "alp_type": "Static1x1", + "column": 62, + "row": 25, + "positions": [ + "P23" + ], + "x1": 127.45210000190735 + }, + { + "name": "Static1x1_21", + "alp_type": "Static1x1", + "column": 62, + "row": 30, + "positions": [ + "P24" + ], + "x1": 127.45210000190735 + }, + { + "name": "Tilting-ALP_1", + "alp_type": "Tilting-ALP", + "column": 63, + "row": 20, + "positions": [ + "TA1" + ], + "x1": 128.7869 + }, + { + "name": "WashStationSpan8_1", + "alp_type": "WashStationSpan8", + "column": 71, + "row": 30, + "positions": [ + "W2" + ], + "x1": 141.77009992294313 + } + ], + "modules": { + "multichannel": [ + { + "name": "X", + "device": 17, + "index": 1, + "configure": "0001000000807d02000100000000fc0300010000000088130000000000005a050003000300320000605b0300c8000000002d3101b80b0000000200000180ff800c0000b80b307532000000803801000a0000b80b000050000000000000fb1027000010270000000000000000000060ea000000000000800100000000f401a00f00000000000000ffffffff0a0064000000000000002f440000803f000000000000905f0100c94eaa3acea074395d1feb330000000000000000141b000014000000b1010000ea100000401f000000000000f4010000102700000f0000000000000000000000000000000000020000002c01000032000000", + "limits": { + "max_velocity": 163200, + "max_acceleration": 261120, + "max_jerk": 1280000, + "min_position": 0, + "max_position": 350720 + }, + "home_position": 35840, + "hysteresis": 0 + }, + { + "name": "Y", + "device": 17, + "index": 2, + "configure": "000100000000ee02000100000000b0040001000000001027000000000000e80300030003003200000071020064000000c0e1e400d007000000020000018000800c0000b80b307532000000803801000a0000b004000050000000000000fb1027000010270000000000000000000060ea000000000000800100000000f401a00f00000000000000ffffffff0a0064000000000000002f440000803f000000000000905f0100c94eaa3acea074395d1feb330000000000000000141b000014000000b1010000ea100000401f000000000000f4010000102700000f0000000000000000000000000000000000020000002c01000032000000", + "limits": { + "max_velocity": 192000, + "max_acceleration": 307200, + "max_jerk": 2560000, + "min_position": 0, + "max_position": 256000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "Z", + "device": 17, + "index": 3, + "configure": "0001000000005f00000100000000f401000100000000aa0a000018fcff0000000003000300140000a0860100e803000040420f00e80300008000000008800034080000800c0852d007000000000000010000f401000050000000000000fa1027000010270000c8000000000000003075000018fcffff800100000000e803881300000000000080ffffffff0a006400000000000000000000000000000000000000000000000000000000000000000000000000000050c3000000000000000000000000000000000000000000000000000000000000000000000fd007410000000000000002000000000000000000000000000000000000", + "limits": { + "max_velocity": 24320, + "max_acceleration": 128000, + "max_jerk": 698880, + "min_position": -256000, + "max_position": 0 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "D", + "device": 17, + "index": 4, + "configure": "0001000000000003000100000000c01200000000000000000000000000801a06000300000050000050c300006400000000000000c8000000b80b00000d00ff480d0000f00a3075b4000000000000000a0000c012000040010000000000fb10270000401f00000000000000000000a8610000a8a80000000000000000f401dc0500000000000080ffffffff0a00102700000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000000000000000000000000000000000", + "limits": { + "max_velocity": 196608, + "max_acceleration": 1228800, + "max_jerk": 0, + "min_position": 0, + "max_position": 400000 + }, + "home_position": 400, + "hysteresis": 0 + }, + { + "name": "GY", + "device": 17, + "index": 5, + "configure": "0001000000030f01000100000029830100010000009b1f0f000000000052060300030003f23d0000400d0300e80300000048e80194110000f30100000d0000b0040000dc05640018010000000000000a00298301006f4d000000000000fb10270000d6060a000000000000000000983a000000000000c60000000000f401a00f00000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000000000000000000000000000000000", + "limits": { + "max_velocity": 69379, + "max_acceleration": 99113, + "max_jerk": 991131, + "min_position": 0, + "max_position": 198226 + }, + "home_position": 47574, + "hysteresis": 0 + }, + { + "name": "GG", + "device": 17, + "index": 6, + "configure": "00010000001966010001000000f9f91b0001000000bac317010000000002f00200030003b735000050c30000e803000080841e00d0070000e10300000d0000bc020000dc056400fa000000e02e00000a00f9f91b001966010000000000fb4c1d000020030a000000000000000000a861000000000000290700000000f401d00700000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000d4feffff3705000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000dc0500000000000000000000000000000000", + "limits": { + "max_velocity": 91673, + "max_acceleration": 1833465, + "max_jerk": 18334650, + "min_position": 0, + "max_position": 192514 + }, + "home_position": 35753, + "hysteresis": 0 + }, + { + "name": "GZ", + "device": 17, + "index": 7, + "configure": "000a000000415d0000bc02000030b301000000000000000000d03effff00000000010003380600000000000000000000000000000000000000000000090000b80b0000dc05e8030000000000000000000030b30100161f000000000000fc1027000088130a000000000000000000c8af0000000000003e0158020000640000000000e803fa0000ffffffff0a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000000000000000000000000000000000", + "limits": { + "max_velocity": 23873, + "max_acceleration": 111408, + "max_jerk": 0, + "min_position": -49456, + "max_position": 0 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "GR", + "device": 17, + "index": 8, + "configure": "0001000000ebb8010001000000b9bd050001000000e5f61600c396c6ff000000000300039475000020a107006400000080841e00f40100004b0000000d0000bc020000dc05640004010000b03600000200b9bd050075dc000000000000fa4c1d000020030a000000000000000000983a000000000000f00200000000f401c40900000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000dc0500000000000000000000000000000000", + "limits": { + "max_velocity": 112875, + "max_acceleration": 376249, + "max_jerk": 1504997, + "min_position": -3762493, + "max_position": 0 + }, + "home_position": -141093, + "hysteresis": 0 + } + ], + "span8": [ + { + "name": "X", + "device": 17, + "index": 1, + "configure": "000100000000ee02000100000000b00400010000000010270000a6faff0000000003000300320000007102006400000080c3c901b80b0000000200000180ff800c0000b80b307532000000803801000a0000b80b000050000000000000fa1027000010270000000000000000000060ea000000000000800100000000f401a00f00000000000000ffffffff0a0064000000000000002f440000803f000000000000905f0100c94eaa3acea074395d1feb330000000000000000141b000014000000b1010000ea100000401f000000000000f4010000102700000f0000000000000000000000000000001800020000002c01000032000000", + "limits": { + "max_velocity": 192000, + "max_acceleration": 307200, + "max_jerk": 2560000, + "min_position": -350720, + "max_position": 0 + }, + "home_position": -2560, + "hysteresis": 0 + }, + { + "name": "Y1", + "device": 17, + "index": 2, + "configure": "ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + "limits": { + "max_velocity": 94275, + "max_acceleration": 193264, + "max_jerk": 10412672, + "min_position": 0, + "max_position": 471375 + }, + "home_position": 23569, + "hysteresis": 0 + }, + { + "name": "Y2", + "device": 17, + "index": 3, + "configure": "ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + "limits": { + "max_velocity": 94275, + "max_acceleration": 193264, + "max_jerk": 10412672, + "min_position": 0, + "max_position": 471375 + }, + "home_position": 27811, + "hysteresis": 0 + }, + { + "name": "Y3", + "device": 17, + "index": 4, + "configure": "ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + "limits": { + "max_velocity": 94275, + "max_acceleration": 193264, + "max_jerk": 10412672, + "min_position": 0, + "max_position": 471375 + }, + "home_position": 32053, + "hysteresis": 0 + }, + { + "name": "Y4", + "device": 17, + "index": 5, + "configure": "ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + "limits": { + "max_velocity": 94275, + "max_acceleration": 193264, + "max_jerk": 10412672, + "min_position": 0, + "max_position": 471375 + }, + "home_position": 36296, + "hysteresis": 0 + }, + { + "name": "Y5", + "device": 17, + "index": 6, + "configure": "ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + "limits": { + "max_velocity": 94275, + "max_acceleration": 193264, + "max_jerk": 10412672, + "min_position": 0, + "max_position": 471375 + }, + "home_position": 40538, + "hysteresis": 0 + }, + { + "name": "Y6", + "device": 17, + "index": 7, + "configure": "ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + "limits": { + "max_velocity": 94275, + "max_acceleration": 193264, + "max_jerk": 10412672, + "min_position": 0, + "max_position": 471375 + }, + "home_position": 44781, + "hysteresis": 0 + }, + { + "name": "Y7", + "device": 17, + "index": 8, + "configure": "ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + "limits": { + "max_velocity": 94275, + "max_acceleration": 193264, + "max_jerk": 10412672, + "min_position": 0, + "max_position": 471375 + }, + "home_position": 49023, + "hysteresis": 0 + }, + { + "name": "Y8", + "device": 17, + "index": 9, + "configure": "ff170000004370010074000000f0f20200bb01000080e29e00000000004f3107000200034925000078000000640000005e01000066660000ee02000001c4098a020000d0070000", + "limits": { + "max_velocity": 94275, + "max_acceleration": 193264, + "max_jerk": 10412672, + "min_position": 0, + "max_position": 471375 + }, + "home_position": 53265, + "hysteresis": 0 + }, + { + "name": "Z1", + "device": 17, + "index": 10, + "configure": "ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee020000ffc4098a02000088130000", + "limits": { + "max_velocity": 175782, + "max_acceleration": 1143151, + "max_jerk": 838190332, + "min_position": -482342, + "max_position": 48234 + }, + "home_position": -4823, + "hysteresis": 0 + }, + { + "name": "Z2", + "device": 17, + "index": 11, + "configure": "ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee02000001c4098a02000088130000", + "limits": { + "max_velocity": 175782, + "max_acceleration": 1143151, + "max_jerk": 838190332, + "min_position": -482342, + "max_position": 48234 + }, + "home_position": -4823, + "hysteresis": 0 + }, + { + "name": "Z3", + "device": 17, + "index": 12, + "configure": "ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee020000ffc4098a02000088130000", + "limits": { + "max_velocity": 175782, + "max_acceleration": 1143151, + "max_jerk": 838190332, + "min_position": -482342, + "max_position": 48234 + }, + "home_position": -4823, + "hysteresis": 0 + }, + { + "name": "Z4", + "device": 17, + "index": 13, + "configure": "ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee02000001c4098a02000088130000", + "limits": { + "max_velocity": 175782, + "max_acceleration": 1143151, + "max_jerk": 838190332, + "min_position": -482342, + "max_position": 48234 + }, + "home_position": -4823, + "hysteresis": 0 + }, + { + "name": "Z5", + "device": 17, + "index": 14, + "configure": "ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee020000ffc4098a02000088130000", + "limits": { + "max_velocity": 175782, + "max_acceleration": 1143151, + "max_jerk": 838190332, + "min_position": -482342, + "max_position": 48234 + }, + "home_position": -4823, + "hysteresis": 0 + }, + { + "name": "Z6", + "device": 17, + "index": 15, + "configure": "ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee02000001c4098a02000088130000", + "limits": { + "max_velocity": 175782, + "max_acceleration": 1143151, + "max_jerk": 838190332, + "min_position": -482342, + "max_position": 48234 + }, + "home_position": -4823, + "hysteresis": 0 + }, + { + "name": "Z7", + "device": 17, + "index": 16, + "configure": "ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee020000ffc4098a02000088130000", + "limits": { + "max_velocity": 175782, + "max_acceleration": 1143151, + "max_jerk": 838190332, + "min_position": -482342, + "max_position": 48234 + }, + "home_position": -4823, + "hysteresis": 0 + }, + { + "name": "Z8", + "device": 17, + "index": 17, + "configure": "ffe8010000a6ae0200890900006f71110061240000fcc4f531daa3f8ff6abc0000020043aa44000096000000780000005e010000ff7f0000ee02000001c4098a02000088130000", + "limits": { + "max_velocity": 175782, + "max_acceleration": 1143151, + "max_jerk": 838190332, + "min_position": -482342, + "max_position": 48234 + }, + "home_position": -4823, + "hysteresis": 0 + }, + { + "name": "D1", + "device": 18, + "index": 1, + "configure": "c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + "limits": { + "max_velocity": 23200, + "max_acceleration": 50000, + "min_position": 0, + "max_position": 24000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "D2", + "device": 18, + "index": 2, + "configure": "c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + "limits": { + "max_velocity": 23200, + "max_acceleration": 50000, + "min_position": 0, + "max_position": 24000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "D3", + "device": 18, + "index": 3, + "configure": "c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + "limits": { + "max_velocity": 23200, + "max_acceleration": 50000, + "min_position": 0, + "max_position": 24000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "D4", + "device": 18, + "index": 4, + "configure": "c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + "limits": { + "max_velocity": 23200, + "max_acceleration": 50000, + "min_position": 0, + "max_position": 24000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "D5", + "device": 18, + "index": 5, + "configure": "c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + "limits": { + "max_velocity": 23200, + "max_acceleration": 50000, + "min_position": 0, + "max_position": 24000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "D6", + "device": 18, + "index": 6, + "configure": "c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + "limits": { + "max_velocity": 23200, + "max_acceleration": 50000, + "min_position": 0, + "max_position": 24000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "D7", + "device": 18, + "index": 7, + "configure": "c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + "limits": { + "max_velocity": 23200, + "max_acceleration": 50000, + "min_position": 0, + "max_position": 24000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "D8", + "device": 18, + "index": 8, + "configure": "c8000000a00f000014000000a05a0000c8000000302a00001027000050c3000000000000c05d00005800", + "limits": { + "max_velocity": 23200, + "max_acceleration": 50000, + "min_position": 0, + "max_position": 24000 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "GY", + "device": 17, + "index": 18, + "configure": "0001000000030f01000100000029830100010000009b1f0f000000000052060300030003f23d0000400d0300e80300000048e80194110000f30100000d0000b0040000dc05640018010000000000000a00298301006f4d000000000000fb10270000d6060a000000000000000000983a000000000000c60000000000f401a00f00000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000001800000000000000000000000000", + "limits": { + "max_velocity": 69379, + "max_acceleration": 99113, + "max_jerk": 991131, + "min_position": 0, + "max_position": 198226 + }, + "home_position": 47574, + "hysteresis": 0 + }, + { + "name": "GG", + "device": 17, + "index": 19, + "configure": "00010000001966010001000000f9f91b0001000000bac317010000000002f00200030003b735000050c30000e803000080841e00d0070000e10300000d0000bc020000dc056400fa000000e02e00000a00f9f91b001966010000000000fb4c1d000020030a000000000000000000a861000000000000290700000000f401d00700000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000d4feffff3705000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000dc0500000000000000000000000000000000", + "limits": { + "max_velocity": 91673, + "max_acceleration": 1833465, + "max_jerk": 18334650, + "min_position": 0, + "max_position": 192514 + }, + "home_position": 35753, + "hysteresis": 0 + }, + { + "name": "GZ", + "device": 17, + "index": 20, + "configure": "000a000000415d0000bc02000030b301000000000000000000d03effff00000000010003380600000000000000000000000000000000000000000000090000b80b0000dc05e8030000000000000000000030b30100161f000000000000fc1027000088130a000000000000000000c8af0000000000003e0158020000640000000000e803fa0000ffffffff0a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000000000000000000000000000000000000000", + "limits": { + "max_velocity": 23873, + "max_acceleration": 111408, + "max_jerk": 0, + "min_position": -49456, + "max_position": 0 + }, + "home_position": 0, + "hysteresis": 0 + }, + { + "name": "GR", + "device": 17, + "index": 21, + "configure": "0001000000ebb8010001000000b9bd050001000000e5f61600c396c6ff000000000300039475000020a107006400000080841e00f40100004b0000000d0000bc020000dc05640004010000b03600000200b9bd050075dc000000000000fa4c1d000020030a000000000000000000983a000000000000f00200000000f401c40900000000000000ffffffff0a00640000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f0000000000000000000000dc0500000000000000000000000000000000", + "limits": { + "max_velocity": 112875, + "max_acceleration": 376249, + "max_jerk": 1504997, + "min_position": -3762493, + "max_position": 0 + }, + "home_position": -141093, + "hysteresis": 0 + } + ] + } +} diff --git a/pylabrobot/beckman_coulter/biomek_i7/design.md b/pylabrobot/beckman_coulter/biomek_i7/design.md index 6f5de098859..4aba0525520 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/design.md +++ b/pylabrobot/beckman_coulter/biomek_i7/design.md @@ -26,3 +26,14 @@ Each layer calls only the one below it. side; that places it, not the USB serial number or the enumeration order. An unknown type or side, two boards claiming one place, or no chassis is refused. `driver/simulator.py` simulates the boards at the wire, answering identity reads from a recording of a real instrument's. + +**I2. The configuration is declared.** What the boards cannot report (motor tables, each axis's home +position and hysteresis, per pod the counts conversions, limits, geometry, calibration and settings) +is a `DeviceConfiguration`, read only from `declared_configuration_json` and written by +`save_configuration`. It describes what is fitted; it never decides what is present. + +**I3. Units: a Biomek-unit core behind one boundary.** The public API is in PyLabRobot's units (mm, +uL, s, degrees, the deck's frame). Planning, recipes and the counts layer work in Biomek's (cm, its +frame with Y towards the front, the per-mille speed field), which is what its logs and files are +compared in. A public method converts its arguments once, in `units.py`, and calls its `_`-prefixed +Biomek-unit twin; nothing is converted back and forth inside. diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py index 892bf89baeb..605bd779f99 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py @@ -1,13 +1,33 @@ """What the driver knows about an instrument: facts only (STAR design.md P3). -What the boards answer about themselves at setup: each module's identity, its boards with their -application images and versions, and the names of its inputs and outputs (`ModuleConfiguration`, -`BoardInfo`). +Two kinds: + +- **What the boards answer** about themselves at setup (`ModuleConfiguration`, `BoardInfo`). +- **What they cannot answer**, declared per instrument (`DeviceConfiguration`): + - the motor tables loaded into the boards after every power-up; + - per pod, the counts conversions, travel limits, geometry and settings that Biomek keeps on + the host side. + + One JSON file per instrument, made from the instrument's two Biomek sources and given to the + driver by path; no instrument's own ships with the driver (the generic one in `defaults/`, + anonymized, is for simulation): + - Biomek's instrument file (`.bif`): the pods, the deck's calibrated positions and its layout; + - the Master Controller's instrument record: the motor tables (with each instrument's measured + hysteresis) and the modules' serial numbers. + + `sources` records, per source, where it was read, when, and a fingerprint of exactly the values + taken from it. Loading refuses a file whose values no longer match its fingerprints (changed + after it was imported). """ -from dataclasses import dataclass, field -from typing import Dict, List, Optional +import copy +import hashlib +import json +from dataclasses import asdict, dataclass, field +from pathlib import Path +from typing import Any, Dict, List, Literal, Optional, Tuple, Union +from pylabrobot.beckman_coulter.biomek_i7.driver.motors import MotorTables from pylabrobot.beckman_coulter.biomek_i7.driver.protocol import HardwareVersion, ModuleId # The firmware this driver has been run against (one instrument, 2026-10-24 through 2026-11-10): @@ -67,3 +87,425 @@ def untested_firmware(self) -> List[str]: ): found.append(f"board {b.index} application {b.application_version}") return found + + +# -- declared per instrument ------------------------------------------------------------------------- + +Side = Literal["left", "right"] + + +@dataclass(frozen=True) +class AxisConversion: + """How Biomek turns a value into counts for one axis or quantity: `counts = (value + offset) x + const`, rounded. `unit` is what `value` is in: Biomek's own units, `cm`, `deg` or `uL`. + + Read from the instrument file's `CmdGen/Conversion` (`Const`, `Offset`). Checked on + this instrument against positions it logged: + - the Multichannel's park GR, 90 deg, is -175,443 counts; + - its rest Z, 39.763 cm, is -256 counts; + - the Span-8 Z park, 39.1079 cm on Z1, is 9,029 counts. + """ + + const: float + offset: float + unit: str + + def to_counts(self, value: float) -> int: + return round((value + self.offset) * self.const) + + def to_value(self, counts: int) -> float: + return counts / self.const - self.offset + + +@dataclass(frozen=True) +class PodGeometry: + """A pod's dimensions as Biomek's collision model uses them, in cm. + + From the instrument file's per-device pod entry. That entry, not the pod type's defaults under + `HardwareSetupInfo/PodTypes`, is what reproduces the travel Biomek logged: + - BridgeXSpan is 39.0154 here, 12.7 in the type defaults; + - the bridges touch at left X + |right X| = 250,807 counts, and the most Biomek ever commanded + was 250,678. + + The optional fields are absent on a pod type that has no such part. + """ + + bridge_x_span: float + bridge_to_head_x_offset: float + mandrel1_x_offset: float + mandrel1_y_offset: float + mandrel_x_spacing: float + mandrel_y_spacing: float + avoidance_margin: float + pod_x_span: float + pod_y_span: float + gripper_x_offset: float + gripper_y_offset: float + gripper_z_offset: float + frame_safety_left: float + frame_safety_right: float + additional_safe_height: float + additional_safe_height_gripper: float + mandrels_x: Optional[int] = None + mandrels_y: Optional[int] = None + sub_mandrel_safe_height: Optional[float] = None + + +@dataclass(frozen=True) +class Obstacle: + """A fixed obstacle on the deck, as Biomek keeps it per pod (`Obstacles` in the instrument + file): a box in Biomek's frame (cm; Y towards the front, Z up from the deck surface), + a bound that is None open on that side, widened by `buffer`. Walls (the shields, the towers, the + light curtain) have no Z bounds; the pump bank is a floor up to `z2`; the I-beam a ceiling from + `z1`.""" + + name: str + buffer: float = 0.0 + x1: Optional[float] = None + x2: Optional[float] = None + y1: Optional[float] = None + y2: Optional[float] = None + z1: Optional[float] = None + z2: Optional[float] = None + + +# The settings the driver takes from a pod's entry in the instrument file, never assumed: a pod +# whose entry lacks one is refused (`PodConfiguration`). Every pod's; a gripper's; each pod type's. +POD_SETTINGS: Tuple[str, ...] = () +GRIPPER_SETTINGS: Tuple[str, ...] = () +TYPE_SETTINGS: Dict[str, Tuple[str, ...]] = { + "span8": ("ProbeSize",), + "multichannel": (), +} + + +def required_settings(module_type: str, gripper: bool) -> Tuple[str, ...]: + """The settings a pod of `module_type` (with a gripper or not) must have in its entry.""" + return ( + *POD_SETTINGS, + *(GRIPPER_SETTINGS if gripper else ()), + *TYPE_SETTINGS.get(module_type, ()), + ) + + +@dataclass +class PodConfiguration: + """One pod's facts the boards do not hold. + + - `conversion`: per axis or quantity, keyed by Biomek's own names (`X`, `Y`, `Z`, `D`, `GY`, + `GG`, `GZ`, `GR`; on a Span-8 also `S` for the span, `Z1`..`Z8`, `D1`..`D8`). + - `limits`: each axis's travel in those units, `(lowest, highest)`. + - `park`: Biomek's park location. + - `settings`: every other scalar Biomek keeps for the pod, and the Span-8's per-probe lists + (`LoadingOffsets`, `BrokenTips`) (tip loading, safe heights, speeds, + gripper squeeze) under its own name, for the features that will use them. + - `gripper_model`: the gripper's dimensions, as Biomek nests them; empty for a pod with no + gripper. + - `module_serial_number`: the serial number the pod's module reports, which ties these facts to + one module (`BiomekI7Driver.discover` checks it), from the Master Controller's record; None in + the generic configuration. + """ + + component: str + module_type: str + side: Side + conversion: Dict[str, AxisConversion] + limits: Dict[str, Tuple[float, float]] + geometry: PodGeometry + park: Dict[str, float] = field(default_factory=dict) + settings: Dict[str, Any] = field(default_factory=dict) + gripper_model: Dict[str, Any] = field(default_factory=dict) + obstacles: List[Obstacle] = field(default_factory=list) + source: str = "" + module_serial_number: Optional[str] = None + + def __post_init__(self) -> None: + missing = [ + k + for k in required_settings(self.module_type, bool(self.gripper_model)) + if k not in self.settings + ] + if missing: + raise ValueError( + f"{self.component}: the instrument file's entry for this pod has no {', '.join(missing)}; " + "the driver takes these from it and never assumes them" + ) + + def to_counts(self, axis: str, value: float) -> int: + """A value in Biomek's units for `axis` (see `conversion`) as counts. + + Raises: + ValueError: for an axis with no conversion. + """ + return self._conversion(axis).to_counts(value) + + def to_value(self, axis: str, counts: int) -> float: + """Counts on `axis` as a value in Biomek's units for it.""" + return self._conversion(axis).to_value(counts) + + def probe_spacing(self) -> float: + """A Span-8's probes' spacing at their narrowest (cm): the span axis's zero shared out between + the eight (`S` counts from that span, and each probe's Y counts from its narrowest place), or + `ProbeSize` without a span axis.""" + if "S" in self.conversion: + return -self.conversion["S"].offset / 7 + return float(self.settings["ProbeSize"]) + + def probe_y(self, probe: int, counts: int) -> float: + """Span-8 probe `probe`'s (1-8) Y in cm from its `Y` counts: the `Y` conversion is + probe 1's, and each next probe's counts start one narrowest spacing further on.""" + return self.to_value("Y", counts) + (probe - 1) * self.probe_spacing() + + def _conversion(self, axis: str) -> AxisConversion: + if axis not in self.conversion: + raise ValueError( + f"{self.component} has no conversion for {axis!r}; has {sorted(self.conversion)}" + ) + return self.conversion[axis] + + +@dataclass(frozen=True) +class DeckPosition: + """A deck position as Biomek calibrated it, in Biomek's frame (cm; Y towards the front, Z up + from the deck surface): a corner per pod, by Biomek's pod number, and the position's spans. + + Each pod moves to a position relative to its own corner: corner n is the one that shifts when + pod n's deck framing changes (`ShiftDeck` applied to `X`/`Y`/`Z`). `framed[n]` says + how corner n was obtained: `Position` (framed at this position) or `Deck` (from the deck's framing). + """ + + corners: Dict[int, Tuple[float, float, float]] + x_span: float + y_span: float + framed: Dict[int, str] = field(default_factory=dict) + + def corner(self, pod_number: int) -> Tuple[float, float, float]: + """Raises: + ValueError: for a pod with no corner here. + """ + if pod_number not in self.corners: + raise ValueError(f"no corner for pod {pod_number}; have {sorted(self.corners)}") + return self.corners[pod_number] + + +@dataclass(frozen=True) +class AlpPlacement: + """One ALP of a deck layout, as an instrument file places it (`Decks//Groups/`): its + name and Biomek type, the pin column of its left pins and the pin row of its front pins, the + names of its positions, and the X Biomek has its left edge at (`X1`, cm), which checks the + column.""" + + name: str + alp_type: str + column: int + row: int + positions: Tuple[str, ...] + x1: Optional[float] = None + + +SOURCES = ("instrument_file", "master_controller") + + +def source_parts(data: Dict[str, Any]) -> Dict[str, Dict[str, Any]]: + """A serialized configuration's values split by the source each comes from (`SOURCES`).""" + pods = data.get("pods", {}) + return { + "instrument_file": { + "instrument_serial_number": data.get("instrument_serial_number"), + "pods": { + side: {k: v for k, v in pod.items() if k != "module_serial_number"} + for side, pod in pods.items() + }, + "deck_positions": data.get("deck_positions", {}), + "deck_layout": data.get("deck_layout", []), + }, + "master_controller": { + "chassis_serial_number": data.get("chassis_serial_number"), + "module_serial_numbers": { + side: pod.get("module_serial_number") for side, pod in pods.items() + }, + "modules": data.get("modules", {}), + }, + } + + +def fingerprint(value: Any) -> str: + """A digest of `value`'s canonical JSON: equal values, equal fingerprints.""" + text = json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + return "sha256:" + hashlib.sha256(text.encode("ascii")).hexdigest() + + +@dataclass +class DeviceConfiguration: + """Everything declared about one instrument: its motor tables and its pods. + + `chassis_serial_number` and each pod's `module_serial_number` tie the file to the instrument it + describes: a live session refuses a file whose serial numbers are not the instrument's + (`BiomekI7Driver.discover`). `generic` marks a file that describes no instrument in particular + (the package's default, for simulation; `anonymized`): it carries no serial numbers and no + measured hysteresis, and a live session refuses it. `instrument_serial_number` is the instrument + file's own, for information only. `sources`: per source (`SOURCES`), its `fingerprint`, and for + an instrument's own file where (`path`, `kind`) and when (`read_at`) it was read.""" + + chassis_serial_number: Optional[str] + instrument_serial_number: Optional[str] + modules: Dict[str, Any] + pods: Dict[Side, PodConfiguration] + sources: Dict[str, Dict[str, str]] = field(default_factory=dict) + # The default deck's positions by Biomek's name (`P1`, `TL1`), as calibrated; empty if not + # imported. + deck_positions: Dict[str, DeckPosition] = field(default_factory=dict) + generic: bool = False + # The default deck's ALPs, as the instrument file places them; empty if not imported. + deck_layout: List[AlpPlacement] = field(default_factory=list) + + @property + def motor_tables(self) -> MotorTables: + return MotorTables.from_dict(self.modules) + + def pod(self, side: Side) -> PodConfiguration: + """Raises: + ValueError: if nothing is declared for that side. + """ + if side not in self.pods: + raise ValueError(f"no pod declared on the {side}; declared: {sorted(self.pods)}") + return self.pods[side] + + def fingerprints(self) -> Dict[str, str]: + """The fingerprint of the values taken from each source, as they are now.""" + parts = source_parts(self.to_dict()) + return {name: fingerprint(parts[name]) for name in SOURCES} + + def unrecorded_changes(self) -> List[str]: + """The sources whose values no longer match the fingerprints recorded at import: changed after + the file was made, by hand or otherwise.""" + now = self.fingerprints() + return [name for name in SOURCES if self.sources.get(name, {}).get("fingerprint") != now[name]] + + def anonymized(self) -> "DeviceConfiguration": + """This configuration as a generic Biomek i7: every serial number removed (any key naming one, + at any depth), the measured hysteresis zeroed, `generic` set, and the sources reduced to their + fingerprints (no path or date).""" + data = self.to_dict() + + def scrub(value: Any) -> Any: + if isinstance(value, dict): + return {k: None if "serial" in k.lower() else scrub(v) for k, v in value.items()} + if isinstance(value, list): + return [scrub(v) for v in value] + return value + + data = scrub(data) + for axes in data["modules"].values(): + for axis in axes: + axis["hysteresis"] = 0 + data["generic"] = True + data["sources"] = {} + generic = DeviceConfiguration.from_dict(data) + generic.sources = {name: {"fingerprint": f} for name, f in generic.fingerprints().items()} + return generic + + @classmethod + def load(cls, path: Union[str, Path]) -> "DeviceConfiguration": + """An instrument's declared configuration, from the file `save` wrote. + + Raises: + ValueError: if its values no longer match the fingerprints recorded at import: it was + changed afterwards. Import it again. + """ + with open(path, encoding="utf-8") as fh: + config = cls.from_dict(json.load(fh)) + changed = config.unrecorded_changes() + if changed: + raise ValueError( + f"{path}: the values from {' and '.join(changed)} are not the ones imported (changed " + "after import); import it again from the instrument's Biomek files" + ) + return config + + def save(self, path: Union[str, Path], indent: Optional[int] = 2) -> None: + """Write it as `load` reads it; `indent` as `json.dump`'s (None: one line).""" + Path(path).write_text(json.dumps(self.to_dict(), indent=indent) + "\n", encoding="utf-8") + + @classmethod + def from_dict(cls, data: Dict[str, Any]) -> "DeviceConfiguration": + pods: Dict[Side, PodConfiguration] = {} + for side, p in data.get("pods", {}).items(): + pods[side] = PodConfiguration( + component=p["component"], + module_type=p["module_type"], + side=side, + conversion={k: AxisConversion(**v) for k, v in p["conversion"].items()}, + limits={k: (v[0], v[1]) for k, v in p["limits"].items()}, + geometry=PodGeometry(**p["geometry"]), + park=dict(p.get("park", {})), + settings=dict(p.get("settings", {})), + gripper_model=dict(p.get("gripper_model", {})), + obstacles=[Obstacle(**o) for o in p.get("obstacles", [])], + source=p.get("source", ""), + module_serial_number=p.get("module_serial_number"), + ) + positions = { + name: DeckPosition( + corners={int(n): (c[0], c[1], c[2]) for n, c in p["corners"].items()}, + x_span=p["x_span"], + y_span=p["y_span"], + framed={int(n): v for n, v in p.get("framed", {}).items()}, + ) + for name, p in data.get("deck_positions", {}).items() + } + return cls( + chassis_serial_number=data.get("chassis_serial_number"), + instrument_serial_number=data.get("instrument_serial_number"), + modules=data["modules"], + pods=pods, + sources=copy.deepcopy(data.get("sources", {})), + deck_positions=positions, + generic=bool(data.get("generic", False)), + deck_layout=[ + AlpPlacement( + name=a["name"], + alp_type=a["alp_type"], + column=a["column"], + row=a["row"], + positions=tuple(a["positions"]), + x1=a.get("x1"), + ) + for a in data.get("deck_layout", []) + ], + ) + + def to_dict(self) -> Dict[str, Any]: + return { + "generic": self.generic, + "chassis_serial_number": self.chassis_serial_number, + "instrument_serial_number": self.instrument_serial_number, + "sources": self.sources, + "pods": { + side: { + "component": p.component, + "module_type": p.module_type, + "module_serial_number": p.module_serial_number, + "source": p.source, + "conversion": {k: asdict(c) for k, c in p.conversion.items()}, + "limits": {k: list(v) for k, v in p.limits.items()}, + "geometry": {k: v for k, v in asdict(p.geometry).items() if v is not None}, + "park": p.park, + "settings": p.settings, + "gripper_model": p.gripper_model, + "obstacles": [{k: v for k, v in asdict(o).items() if v is not None} for o in p.obstacles], + } + for side, p in self.pods.items() + }, + "deck_positions": { + name: { + "corners": {str(n): list(c) for n, c in p.corners.items()}, + "x_span": p.x_span, + "y_span": p.y_span, + "framed": {str(n): v for n, v in p.framed.items()}, + } + for name, p in self.deck_positions.items() + }, + "deck_layout": [{**asdict(a), "positions": list(a.positions)} for a in self.deck_layout], + "modules": self.modules, + } diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/configuration_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration_tests.py new file mode 100644 index 00000000000..d87feb86824 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration_tests.py @@ -0,0 +1,184 @@ +"""The declared configuration: how it converts, how it is kept, and how discovery checks it against +the boards. On the package's generic configuration, whose physical values are one instrument's.""" + +import asyncio +import dataclasses +import json +import os +import tempfile +import unittest + +from pylabrobot.beckman_coulter.biomek_i7.defaults import GENERIC_CONFIGURATION +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import DeviceConfiguration +from pylabrobot.beckman_coulter.biomek_i7.driver.master import BiomekI7Driver +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import ( + generic_configuration, + generic_driver, + sealed, +) + +MASTER_LOGGER = "pylabrobot.beckman_coulter.biomek_i7.driver.master" + + +class DeclaredConfigurationTests(unittest.TestCase): + def setUp(self) -> None: + self.config = generic_configuration() + self.left, self.right = self.config.pod("left"), self.config.pod("right") + + def test_pods_as_the_instrument_file_has_them(self) -> None: + self.assertEqual((self.left.component, self.left.module_type), ("MC_1", "multichannel")) + self.assertEqual((self.right.component, self.right.module_type), ("SPAN8_2", "span8")) + self.assertEqual(self.left.geometry.bridge_x_span, 39.0154) + self.assertEqual(self.right.geometry.bridge_x_span, 25.7204) + self.assertAlmostEqual(self.left.conversion["X"].offset, -10.519) + self.assertAlmostEqual(self.right.conversion["X"].offset, -146.40669375) + self.assertEqual(self.left.settings["TipLoadForceLimitSlope"], 2150) + + def test_conversions_give_the_counts_biomek_logged(self) -> None: + # Targets Biomek's instrument file holds, and the counts its logs show it sent for them. + self.assertEqual(self.left.to_counts("GR", self.left.park["GR"]), -175443) # the park's GR + self.assertEqual(self.left.to_counts("D", 0.0), 43176) # the plunger's home + self.assertEqual(self.left.to_counts("Z", 39.763), -256) # the rest Z + self.assertEqual(self.right.to_counts("Z1", 39.107921235034354), 9029) # the Span-8 Z park + self.assertEqual(self.right.to_counts("D1", 1000.0), 24000) # a pump's full stroke + self.assertAlmostEqual(self.left.to_value("X", self.left.to_counts("X", 42.0)), 42.0, 3) + + def test_the_bridges_meet_where_biomek_stopped(self) -> None: + """The left bridge's right edge meets the right bridge's left edge at left X + |right X| = + 250,807 counts. Biomek never commanded more than 250,678 in 20 days of logs.""" + lg, rg = self.left.geometry, self.right.geometry + left_reach = -lg.bridge_to_head_x_offset - lg.mandrel1_x_offset + lg.bridge_x_span + right_reach = -rg.bridge_to_head_x_offset - rg.mandrel1_x_offset + lx, rx = self.left.conversion["X"], self.right.conversion["X"] + # Deck X of a pod at `c` counts is c / const - offset; the edges meet when + # (L - R) / 2560 = (-rx.offset + right_reach) - (-lx.offset + left_reach). + combined = ((-rx.offset + right_reach) - (-lx.offset + left_reach)) * lx.const + self.assertEqual(round(combined), 250807) + self.assertLess(250678, combined) + + def test_each_pod_works_from_its_own_corner_of_a_position(self) -> None: + """Heights Biomek logged (Details, 2026-10-20), less the moving pod's corner: the same at every + position, as the labware there is the same. The Multichannel (Pod1) approaching four plates to + dispense, and the Span-8 (Pod2) pressing onto tips in four boxes. Against the other pod's + corner they spread by up to 0.01 cm.""" + positions = self.config.deck_positions + mc = {"P6": 27.757, "P9": 27.750, "P12": 27.756, "P16": 27.760} + span8 = {"P14": 20.741, "P15": 20.744, "P21": 20.737, "P23": 20.727} + for pod, logged, height in ((1, mc, 11.788), (2, span8, 4.770)): + for name, z in logged.items(): + with self.subTest(pod=pod, position=name): + self.assertAlmostEqual(z - positions[name].corner(pod)[2], height, delta=0.0011) + self.assertEqual(positions["P6"].framed, {1: "Position", 2: "Position"}) + with self.assertRaises(ValueError): + positions["P6"].corner(3) + + def test_unknown_axis_and_side(self) -> None: + with self.assertRaises(ValueError): + self.left.to_counts("Z1", 1.0) + config = generic_configuration() + del config.pods["right"] + with self.assertRaisesRegex(ValueError, "no pod declared on the right"): + config.pod("right") + + +class KeepingTests(unittest.TestCase): + def setUp(self) -> None: + self.folder = tempfile.TemporaryDirectory() + self.addCleanup(self.folder.cleanup) + self.path = os.path.join(self.folder.name, "configuration.json") + + def test_save_and_load_round_trip(self) -> None: + config = generic_configuration() + config.save(self.path) + self.assertEqual(DeviceConfiguration.load(self.path).to_dict(), config.to_dict()) + with open(GENERIC_CONFIGURATION, encoding="utf-8") as fh: + self.assertEqual(json.load(fh), config.to_dict()) + + def test_a_file_changed_after_import_is_refused_at_load(self) -> None: + for change in ( + lambda data: data["pods"]["left"]["conversion"]["X"].update(const=1.0), # instrument file + lambda data: data["modules"]["span8"][0].update(hysteresis=7), # Master Controller record + ): + config = generic_configuration() + data = config.to_dict() + change(data) + with open(self.path, "w", encoding="utf-8") as fh: + json.dump(data, fh) + with self.assertRaisesRegex(ValueError, "not the ones imported"): + DeviceConfiguration.load(self.path) + + def test_anonymized_keeps_no_serial_numbers_and_no_measured_hysteresis(self) -> None: + config = generic_configuration() + config.generic = False + config.chassis_serial_number = "A" * 32 + config.instrument_serial_number = "B" * 11 + for pod in config.pods.values(): + pod.module_serial_number = "C" * 32 + config.modules["span8"][0]["hysteresis"] = 12 + config.sources = { + name: {"path": "C:/somewhere", "kind": "file", "read_at": "2026-01-01", "fingerprint": f} + for name, f in config.fingerprints().items() + } + generic = config.anonymized() + text = json.dumps(generic.to_dict()) + for serial in ("A" * 32, "B" * 11, "C" * 32): + self.assertNotIn(serial, text) + self.assertTrue(generic.generic) + self.assertEqual({a["hysteresis"] for axes in generic.modules.values() for a in axes}, {0}) + self.assertEqual({k for s in generic.sources.values() for k in s}, {"fingerprint"}) + self.assertEqual(generic.unrecorded_changes(), []) + self.assertEqual(generic.to_dict(), generic_configuration().to_dict()) + + +class DeclaredAgainstFoundTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + asyncio.get_running_loop().set_debug(False) + + async def discover_with(self, configuration: DeviceConfiguration) -> BiomekI7Driver: + driver = generic_driver(configuration=sealed(configuration)) + self.addAsyncCleanup(driver.stop) + await driver.discover() + return driver + + async def test_the_generic_instrument_matches(self) -> None: + driver = generic_driver() + self.addAsyncCleanup(driver.stop) + with self.assertNoLogs(MASTER_LOGGER, level="WARNING"): + await driver.discover() + assert driver.left_x_arm and driver.left_x_arm.declared + self.assertEqual(driver.left_x_arm.declared.component, "MC_1") + + async def test_pods_swapped_are_refused(self) -> None: + config = generic_configuration() + left, right = config.pods["left"], config.pods["right"] + config.pods = { + "left": dataclasses.replace(right, side="left"), + "right": dataclasses.replace(left, side="right"), + } + with self.assertRaisesRegex(ValueError, "span8 pod on the left"): + await self.discover_with(config) + + async def test_a_pod_declared_but_not_found_is_only_logged(self) -> None: + config = generic_configuration() + del config.pods["right"] + with self.assertLogs(MASTER_LOGGER, level="WARNING") as logs: + driver = await self.discover_with(config) + self.assertIn("right pod: declared nothing, found span8", "\n".join(logs.output)) + assert driver.right_x_arm is not None + self.assertIsNone(driver.right_x_arm.declared) + + async def test_another_instruments_configuration_is_not_checked_on_given_boards(self) -> None: + # Refused on the instrument's own boards (`serial_numbers_tests.py`); simulated ones are not + # tied to an instrument. + config = generic_configuration() + config.chassis_serial_number = "0" * 32 + driver = await self.discover_with(config) + self.assertEqual(driver.declared.chassis_serial_number, "0" * 32) + + def test_a_declared_configuration_is_required(self) -> None: + with self.assertRaisesRegex(ValueError, "no declared configuration"): + BiomekI7Driver(boards=[]) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py b/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py index d23b667f1fa..c08056a6c9a 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py @@ -1,20 +1,28 @@ -"""One pod: an arm on the shared X rail, and its ACE module.""" +"""One pod: an arm on the shared X rail, its ACE module, and the axes that module drives.""" -from typing import Dict, Literal, Optional, Tuple +from typing import Dict, List, Literal, Optional, Tuple +from pylabrobot.beckman_coulter.biomek_i7 import units from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard -from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ModuleConfiguration +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ( + ModuleConfiguration, + PodConfiguration, +) from pylabrobot.beckman_coulter.biomek_i7.driver.module import ( read_analog_inputs, read_module, ) +from pylabrobot.beckman_coulter.biomek_i7.driver.motors import Axis, MotorTables # How Biomek numbers its pods. Pod1 is the left pod and Pod2 the right on the instrument this # driver was written against; whether that holds on every build is not established. POD_NUMBERS = {"left": 1, "right": 2} COMPONENT_PREFIXES = {"multichannel": "MC", "span8": "SPAN8"} +# Biomek's "Safe Height" (`GlobalMinSafeHeight`) at or below this is unset (it stores -100000). +UNSET_SAFE_HEIGHT = -1000.0 + # The arm board's analog input carrying the interlocked motor supply ("+36V Interlock"). DRIVE_SUPPLY_INPUT = "+36V Interlock" @@ -25,14 +33,37 @@ class Pod: or channels and its gripper. `module_type` is what the board reports itself to be (Get Module ID): `multichannel` (a - 96-channel head) or `span8` (eight independent channels). + 96-channel head) or `span8` (eight independent channels). Its axes are the motor tables' for + that type; what else is known of the pod (conversions, travel limits, geometry, settings) is the + declared configuration's. """ - def __init__(self, board: AceBoard, side: Literal["left", "right"], module_type: str): + def __init__( + self, + board: AceBoard, + side: Literal["left", "right"], + module_type: str, + motor_tables: MotorTables, + declared: Optional[PodConfiguration] = None, + ): self.board = board self.side = side self.module_type = module_type + self.axes: List[Axis] = motor_tables.axes(module_type) self.configuration: Optional[ModuleConfiguration] = None + # What the instrument's declared configuration says about this pod: its conversions, travel + # limits and geometry. None when nothing is declared for this side. + self.declared = declared + # The height the channels rise to before traveling over the deck, mm of the channels' bottom + # above the deck: STAR's `default_minimum_traverse_height`. Seeded from Biomek's "Safe Height" + # (`GlobalMinSafeHeight`) when it is set; None, as on an instrument where it is not (-100000), + # means the top of travel less the park margin, which is what Biomek does with Safe Height set + # to the top. + self.default_minimum_traverse_height: Optional[float] = None + if declared is not None: + safe = declared.settings.get("GlobalMinSafeHeight") + if isinstance(safe, (int, float)) and safe > UNSET_SAFE_HEIGHT: + self.default_minimum_traverse_height = units.to_mm(float(safe)) @property def pod_number(self) -> int: @@ -47,6 +78,12 @@ def component(self) -> str: `MC_1`, `SPAN8_2`.""" return f"{COMPONENT_PREFIXES[self.module_type]}_{self.pod_number}" + def axis(self, name: str) -> Axis: + for axis in self.axes: + if axis.name == name: + return axis + raise ValueError(f"{self} has no axis {name!r}; it has {[a.name for a in self.axes]}") + async def discover(self) -> ModuleConfiguration: """Read what the pod's module says about itself. Moves nothing.""" self.configuration = await read_module(self.board) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/master.py b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py index 21b0e1b98b8..75a257162e8 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/master.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py @@ -15,7 +15,10 @@ ACE_VENDOR_ID, AceBoard, ) -from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ModuleConfiguration +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ( + DeviceConfiguration, + ModuleConfiguration, +) from pylabrobot.beckman_coulter.biomek_i7.driver.features.chassis import Chassis from pylabrobot.beckman_coulter.biomek_i7.driver.features.pod import Pod from pylabrobot.io.usb import USB @@ -46,15 +49,44 @@ class BiomekI7Driver: def __init__( self, serial_numbers: Optional[Sequence[str]] = None, + declared_configuration_json: Optional[str] = None, boards: Optional[Sequence[AceBoard]] = None, ): """ Args: serial_numbers: the ACE boards' USB serial numbers. Defaults to every ACE board attached. + declared_configuration_json: path of the instrument's declared configuration (motor tables, + and per pod its conversions, limits, geometry and calibration), made from the instrument's + Biomek files. Required: the driver never falls back to another, the package's generic one + included. boards: boards to use instead of opening USB devices: a simulated instrument - (`simulator.replay_boards`). + (`simulator.replay_boards`). With them, the checks that tie the configuration to a real + instrument (`discover`) are not made. + + Raises: + ValueError: with no declared configuration, or one changed since it was imported + (`DeviceConfiguration.load`). """ + if declared_configuration_json is None: + raise ValueError( + "no declared configuration: pass `declared_configuration_json`, the instrument's own, made " + "from its Biomek files" + ) self._serial_numbers = list(serial_numbers) if serial_numbers is not None else None + self.declared_configuration_json = declared_configuration_json + self.declared = DeviceConfiguration.load(declared_configuration_json) + logger.info( + "declared configuration %s: chassis %s%s; %s", + declared_configuration_json, + self.declared.chassis_serial_number or "none", + " (generic)" if self.declared.generic else "", + "; ".join( + f"{name} {s.get('kind', '')} {s.get('path', '')} read {s.get('read_at', '?')} " + f"{s.get('fingerprint', '')[:19]}".replace(" ", " ") + for name, s in self.declared.sources.items() + ), + ) + self.motor_tables = self.declared.motor_tables self._given_boards = list(boards) if boards is not None else None self.boards: List[AceBoard] = [] self._connected = False @@ -72,6 +104,7 @@ async def setup(self) -> None: Raises: RuntimeError: if no chassis is found, or a board cannot be placed (`discover`). + ValueError: for a declared configuration that is not this instrument's (`discover`). """ logger.warning( "The Biomek i7 driver's discovery has run on one instrument; it is untested on other " @@ -114,10 +147,16 @@ async def discover(self) -> None: Each board says what it is: Get Module ID answers a module type (`protocol.MODULE_TYPES`: chassis, Multichannel, Span-8) and a side (left, right). That, not its USB serial number or order, places it. Seen on one instrument; an unknown type or side, two boards claiming one - place, or no chassis is refused. + place, no chassis, or a pod type other than the declared one is refused + (`_check_declared_against`). + + On the instrument (no `boards` given), the declared configuration must be this instrument's: + its chassis serial number and each declared pod's module serial number as the modules report + them, and not the generic one (`DeviceConfiguration.generic`). Otherwise it is refused. Raises: RuntimeError: for a board this driver cannot place, or no chassis. + ValueError: for a declared configuration that is not this instrument's. """ if not self._connected: await self._open() @@ -142,9 +181,20 @@ async def discover(self) -> None: types[place] = module.type if "chassis" not in places: raise RuntimeError("no chassis module among the ACE boards") + self._check_declared_against(types) self.chassis = Chassis(places["chassis"]) - self.left_x_arm = Pod(places["left"], "left", types["left"]) if "left" in places else None - self.right_x_arm = Pod(places["right"], "right", types["right"]) if "right" in places else None + self.left_x_arm = ( + Pod(places["left"], "left", types["left"], self.motor_tables, self.declared.pods.get("left")) + if "left" in places + else None + ) + self.right_x_arm = ( + Pod( + places["right"], "right", types["right"], self.motor_tables, self.declared.pods.get("right") + ) + if "right" in places + else None + ) modules: List[Tuple[str, ModuleConfiguration]] = [("chassis", await self.chassis.discover())] for pod in self.arms: modules.append((str(pod), await pod.discover())) @@ -157,6 +207,17 @@ async def discover(self) -> None: logger.warning( "%s runs firmware this driver has not been run against: %s", name, "; ".join(untested) ) + if self._given_boards is not None: + return # simulated: no instrument to tie the configuration to + mismatches = self._serial_number_mismatches() + if mismatches: + raise ValueError( + "the declared configuration is not this instrument's: " + + "; ".join(mismatches) + + ". Its motor tables, conversions, geometry and calibration may not fit. Pass this " + "instrument's own `declared_configuration_json`, made from its Biomek files." + ) + logger.info("the declared configuration is this instrument's: serial numbers match the modules") async def request_serial_numbers(self) -> Dict[str, Optional[str]]: """The serial numbers the modules report: `chassis`, and `left` / `right` for each pod found. @@ -167,6 +228,54 @@ async def request_serial_numbers(self) -> Dict[str, Optional[str]]: """ return self._serial_numbers_found() + def _serial_number_mismatches(self) -> List[str]: + """How the declared configuration's serial numbers differ from the modules' (read at discovery), + each as a sentence; empty when they are this instrument's.""" + found = self._serial_numbers_found() + d = self.declared + problems = ( + ["it is the generic configuration, which describes no instrument"] if d.generic else [] + ) + if d.chassis_serial_number != found["chassis"]: + problems.append( + f"chassis {d.chassis_serial_number or 'not recorded'}, found {found['chassis']}" + ) + for side, pod in d.pods.items(): + if side in found and pod.module_serial_number != found[side]: + problems.append( + f"{side} pod module {pod.module_serial_number or 'not recorded'}, found {found[side]}" + ) + return problems + + def _check_declared_against(self, types: Dict[str, str]) -> None: + """Refuse an instrument whose pods are not the ones declared: their motor tables and geometry + would be another arm's. A pod declared but not found, or found but not declared, is only + logged (a single-pod instrument, or one being configured). + + Raises: + ValueError: if a pod is declared on a side where the boards report another arm type. + """ + for side in ("left", "right"): + declared = self.declared.pods.get(side) + found = types.get(side) + if declared is not None and found is not None and declared.module_type != found: + raise ValueError( + f"the declared configuration has a {declared.module_type} pod on the {side}, but the " + f"boards report a {found}; pass this instrument's own `declared_configuration_json`" + ) + if (declared is None) != (found is None): + logger.warning( + "%s pod: declared %s, found %s", + side, + declared.module_type if declared else "nothing", + found or "nothing", + ) + + def save_configuration(self, path: str) -> None: + """Write the declared configuration to `path`, as loaded, for `declared_configuration_json` to + read back. Nothing found at discovery is written into it.""" + self.declared.save(path) + def _serial_numbers_found(self) -> Dict[str, Optional[str]]: if self.chassis is None or self.chassis.configuration is None: raise RuntimeError("the modules have not been read; call `discover()` or `setup()` first") diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/motors.py b/pylabrobot/beckman_coulter/biomek_i7/driver/motors.py new file mode 100644 index 00000000000..9287a7ad4b3 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/motors.py @@ -0,0 +1,150 @@ +"""Motor tables: the axes each arm's board drives, and the Configure parameters each one takes. + +A board does not keep its motor tables across a power cycle and cannot be asked for them, so the +host loads them at a cold start. Two more values per axis never reach a board: the Master +Controller keeps them in its own motor record and applies them itself. `home_position` is its +`phome`: where its Home All leaves X, the Multichannel's Y and the gripper axes (the Z channels, +the plunger and the Span-8 Y channels end elsewhere). +`hysteresis` is what it adds to an axis's targets; only the Span-8 Z channels have any, and it +differs channel by channel, measured per instrument. They are data, the Master Controller's own +record of the instrument (the `modules` section of its declared configuration, +`driver/configuration.py`), not something the driver works out. No instrument's tables ship with +the driver: they come with each instrument's declared configuration. + +Three layouts of Configure parameters were seen, each starting with the axis's limits: + + CiA 402 drive (X, Y, Z, D, grippers): 0x00 | 6 x u32 velocity/acceleration/jerk limits | + s32 min position | s32 max position | ... + SAGIAN drive (Span-8 Y1-Y8, Z1-Z8): 0xFF | the same limits | ... + syringe pump (Span-8 D1-D8): 8 x u32 velocity/acceleration limits | + s32 min position | s32 max position | u16 backlash +""" + +import struct +from dataclasses import dataclass +from typing import Any, Dict, List, Literal + +from pylabrobot.beckman_coulter.biomek_i7.driver.protocol import Device + +ModuleType = Literal["multichannel", "span8"] + + +@dataclass(frozen=True) +class AxisLimits: + """An axis's limits, as the Master Controller's motor record has them (`vmin` .. `jmax`). A + `max_jerk` of 0 means the axis takes no jerk (a trapezoidal profile: the Multichannel D and the + gripper Z, and the syringe pumps).""" + + min_position: int + max_position: int + max_velocity: int + max_acceleration: int + max_jerk: int + min_velocity: int = 1 + min_acceleration: int = 1 + min_jerk: int = 0 + + +@dataclass(frozen=True) +class PumpLimits: + """A syringe pump's own parameters (the Master Controller's ``), velocities in + counts/s and `backlash` in counts.""" + + min_start_velocity: int + max_start_velocity: int + min_cutoff_velocity: int + max_cutoff_velocity: int + backlash: int + + +@dataclass(frozen=True) +class Axis: + """One axis an arm's board drives, in the board's counts.""" + + name: str + device: int + index: int + configure: bytes + home_position: int = 0 + hysteresis: int = 0 + + @property + def is_pump(self) -> bool: + return self.device == Device.PUMP + + @property + def drive(self) -> Literal["cia402", "sagian", "pump"]: + """The kind of drive, read off the Configure layout. A CiA 402 drive reports a fault whenever + its motor power is off (interlock tripped); a SAGIAN drive or pump does not.""" + if self.is_pump: + return "pump" + return "sagian" if self.configure[0] == 0xFF else "cia402" + + @property + def limits(self) -> AxisLimits: + """The limits at the head of the axis's Configure parameters.""" + if self.is_pump: + values = struct.unpack_from("<8I2i", self.configure) + return AxisLimits(values[8], values[9], values[3], values[7], 0, values[2], values[6], 0) + values = struct.unpack_from("<6I2i", self.configure, 1) + return AxisLimits(values[6], values[7], values[1], values[3], values[5], *values[0:5:2]) + + @property + def pump_limits(self) -> PumpLimits: + """A syringe pump's start and cutoff velocity limits and backlash, from its Configure + parameters (min/max start velocity, min/max velocity, min/max cutoff velocity, min/max + acceleration, min/max position, backlash). + + Raises: + ValueError: if the axis is not a pump. + """ + if not self.is_pump: + raise ValueError(f"{self.name} is not a syringe pump") + values = struct.unpack_from("<8I2iH", self.configure) + return PumpLimits(values[0], values[1], values[4], values[5], values[10]) + + def check_position(self, position: int) -> None: + """Raise `ValueError` for a target outside the axis's position limits.""" + limits = self.limits + if not limits.min_position <= position <= limits.max_position: + raise ValueError( + f"{self.name} position {position} is outside ({limits.min_position}, {limits.max_position})" + ) + + +class MotorTables: + """The axes of every arm type of one instrument, in the order they are configured + (`DeviceConfiguration.motor_tables`).""" + + def __init__(self, modules: Dict[str, List[Axis]]): + self.modules = modules + + @classmethod + def from_dict(cls, modules: Dict[str, Any]) -> "MotorTables": + """From a declared configuration's `modules` section: per arm type, its axes.""" + return cls( + { + module: [ + Axis( + a["name"], + a["device"], + a["index"], + bytes.fromhex(a["configure"]), + a.get("home_position", 0), + a.get("hysteresis", 0), + ) + for a in axes + ] + for module, axes in modules.items() + } + ) + + def axes(self, module: str) -> List[Axis]: + """The axes of one arm type. + + Raises: + ValueError: if the recording has no tables for that type. + """ + if module not in self.modules: + raise ValueError(f"no motor tables recorded for a {module} arm; have {sorted(self.modules)}") + return self.modules[module] diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/motors_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/motors_tests.py new file mode 100644 index 00000000000..0e33306691d --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/motors_tests.py @@ -0,0 +1,85 @@ +"""Motor tables: each axis's Configure parameters and the limits read from them, and the axes a pod +gets from them. On the package's generic configuration.""" + +import asyncio +import unittest + +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import ( + generic_configuration, + generic_driver, + sealed, +) + + +class MotorTableTests(unittest.TestCase): + def setUp(self) -> None: + self.config = generic_configuration() + self.tables = self.config.motor_tables + + def test_limits_from_configure_parameters_match_the_logged_ones(self) -> None: + """The limits parsed from each axis's Configure bytes are the ones the Master Controller + logged for it.""" + for module, axes in self.config.modules.items(): + for axis, logged in zip(self.tables.axes(module), axes): + for name, value in logged["limits"].items(): + self.assertEqual(getattr(axis.limits, name), value, (module, axis.name, name)) + + def test_axes_in_configure_order(self) -> None: + mc = [a.name for a in self.tables.axes("multichannel")] + self.assertEqual(mc[:3], ["X", "Y", "Z"]) + self.assertIn("D", mc) + span8 = [a.name for a in self.tables.axes("span8")] + for n in range(1, 9): + self.assertIn(f"Z{n}", span8) + self.assertIn(f"D{n}", span8) + self.assertEqual( + {a.drive for a in self.tables.axes("span8") if a.name.startswith("D")}, {"pump"} + ) + self.assertTrue(all(a.is_pump for a in self.tables.axes("span8") if a.name.startswith("D"))) + + def test_position_check(self) -> None: + x = self.tables.axes("multichannel")[0] + x.check_position(350720) + with self.assertRaisesRegex(ValueError, "outside"): + x.check_position(350721) + + def test_an_unknown_module_has_no_axes(self) -> None: + with self.assertRaisesRegex(ValueError, "no motor tables recorded for a robot arm"): + self.tables.axes("robot") + + +class PodAxesTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + asyncio.get_running_loop().set_debug(False) + + async def test_each_pod_gets_its_types_axes_and_declaration(self) -> None: + driver = generic_driver() + self.addAsyncCleanup(driver.stop) + await driver.discover() + left, right = driver.left_x_arm, driver.right_x_arm + assert left is not None and right is not None + self.assertEqual( + [a.name for a in left.axes], [a.name for a in driver.motor_tables.axes("multichannel")] + ) + self.assertIs(left.declared, driver.declared.pods["left"]) + self.assertEqual(right.axis("Z8").name, "Z8") + with self.assertRaisesRegex(ValueError, "has no axis 'Z8'"): + left.axis("Z8") + + async def test_the_traverse_default_follows_biomeks_safe_height(self) -> None: + driver = generic_driver() # "Safe Height" unset (-100000), as on the instrument it came from + self.addAsyncCleanup(driver.stop) + await driver.discover() + assert driver.left_x_arm is not None + self.assertIsNone(driver.left_x_arm.default_minimum_traverse_height) + config = generic_configuration() + config.pods["left"].settings["GlobalMinSafeHeight"] = 30.0 + driver = generic_driver(configuration=sealed(config)) + self.addAsyncCleanup(driver.stop) + await driver.discover() + assert driver.left_x_arm is not None + self.assertEqual(driver.left_x_arm.default_minimum_traverse_height, 300.0) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py new file mode 100644 index 00000000000..ea1af8ca706 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py @@ -0,0 +1,104 @@ +"""The check that ties a declared configuration to one instrument: its serial numbers, on the +instrument's own path. The replayed generic cold start answers placeholder serial numbers, as long +as real ones; a configuration copy naming them stands for that instrument's own. + +The instrument's path (no `boards` given) is taken with the replayed boards attached where `_open` +would open the USB devices, so `discover` runs exactly as on the instrument.""" + +import asyncio +import dataclasses +import unittest +from typing import Iterator, List +from unittest import mock + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import DeviceConfiguration +from pylabrobot.beckman_coulter.biomek_i7.driver.master import BiomekI7Driver +from pylabrobot.beckman_coulter.biomek_i7.driver.simulator import ReplayAceUSB +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import ( + GENERIC_SERIAL_NUMBERS, + as_instrument, + configuration_file, + generic_boards, + generic_configuration, + generic_driver, + sealed, +) + +READS = {name for name in p.COMMANDS.values() if name.startswith(("Get ", "Read ", "List "))} + + +class InstrumentPathTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + asyncio.get_running_loop().set_debug(False) + self.boards: List[AceBoard] = [] + + def driver(self, configuration: DeviceConfiguration) -> BiomekI7Driver: + driver = BiomekI7Driver(declared_configuration_json=configuration_file(configuration)) + self.boards = boards = generic_boards() + + async def attach() -> None: + driver.boards = list(boards) + driver._connected = True + for board in driver.boards: + await board.setup() + + patcher = mock.patch.object(driver, "_open", attach) + patcher.start() + self.addCleanup(patcher.stop) + self.addAsyncCleanup(driver.stop) + return driver + + def requests(self) -> Iterator[str]: + for board in self.boards: + assert isinstance(board.io, ReplayAceUSB) + for message in board.io.requests: + yield p.COMMANDS[(message[0], message[4])] + + async def test_the_instruments_own_configuration_is_accepted(self) -> None: + driver = self.driver(as_instrument(generic_configuration())) + await driver.discover() + self.assertEqual(await driver.request_serial_numbers(), GENERIC_SERIAL_NUMBERS) + self.assertEqual(set(self.requests()) - READS, set()) + + async def test_another_instruments_serial_number_is_refused_before_anything_is_written( + self, + ) -> None: + config = as_instrument(generic_configuration()) + config.pods["right"] = dataclasses.replace(config.pods["right"], module_serial_number="X" * 32) + driver = self.driver(sealed(config)) + with self.assertRaisesRegex(ValueError, "right pod module X{32}, found SIMULATED009"): + await driver.setup() + self.assertEqual(set(self.requests()) - READS, set()) + + async def test_another_chassis_is_refused(self) -> None: + config = as_instrument(generic_configuration()) + config.chassis_serial_number = "Y" * 32 + with self.assertRaisesRegex(ValueError, "chassis Y{32}, found SIMULATED001"): + await self.driver(sealed(config)).discover() + + async def test_the_generic_configuration_is_refused_even_with_matching_numbers(self) -> None: + config = as_instrument(generic_configuration()) + config.generic = True + with self.assertRaisesRegex(ValueError, "generic"): + await self.driver(sealed(config)).discover() + + async def test_the_generic_configuration_is_refused(self) -> None: + with self.assertRaisesRegex(ValueError, "generic configuration.*chassis not recorded"): + await self.driver(generic_configuration()).discover() + + +class SimulationTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + asyncio.get_running_loop().set_debug(False) + + async def test_a_simulation_is_not_tied_to_an_instrument(self) -> None: + driver = generic_driver() # the generic configuration, no serial numbers + self.addAsyncCleanup(driver.stop) + await driver.discover() + self.assertTrue(driver.declared.generic) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py b/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py index c07366257d4..dc56c661fa4 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py +++ b/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py @@ -1,17 +1,29 @@ """What the package's tests build their simulated Biomek i7 from: the generic one in `defaults/`, named explicitly (never through `$BIOMEK_I7_SIMULATOR_RECORDING`). Not a test module itself.""" +import atexit import copy import json +import shutil +import tempfile +from pathlib import Path from typing import Any, Dict, List, Optional, Sequence -from pylabrobot.beckman_coulter.biomek_i7.defaults import GENERIC_RECORDING +from pylabrobot.beckman_coulter.biomek_i7.defaults import GENERIC_CONFIGURATION, GENERIC_RECORDING from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import DeviceConfiguration from pylabrobot.beckman_coulter.biomek_i7.driver.master import BiomekI7Driver from pylabrobot.beckman_coulter.biomek_i7.driver.simulator import ReplayAceUSB _GENERIC: Optional[Dict[str, Any]] = None +# The serial numbers the generic cold start answers: placeholders as long as real ones. +GENERIC_SERIAL_NUMBERS = { + "chassis": "SIMULATED00100000000000000000000", + "left": "SIMULATED00200000000000000000000", + "right": "SIMULATED00900000000000000000000", +} + def generic_recording() -> Dict[str, Any]: """The generic cold-start recording, a fresh copy a test may change: `boards` maps each module @@ -42,6 +54,50 @@ def generic_boards( ] -def generic_driver(boards: Optional[Sequence[AceBoard]] = None) -> BiomekI7Driver: - """A driver over `boards`, by default the generic instrument replayed.""" - return BiomekI7Driver(boards=generic_boards() if boards is None else boards) +def generic_configuration() -> DeviceConfiguration: + """The generic declared configuration, loaded afresh (a test may change its copy).""" + return DeviceConfiguration.load(GENERIC_CONFIGURATION) + + +def sealed(configuration: DeviceConfiguration) -> DeviceConfiguration: + """A test's changed copy, with its fingerprints recorded again so that it loads. Only tests do + this: the package makes a configuration from Biomek's files, never from another.""" + configuration.sources = { + name: {**configuration.sources.get(name, {}), "fingerprint": f} + for name, f in configuration.fingerprints().items() + } + return configuration + + +def as_instrument(configuration: DeviceConfiguration) -> DeviceConfiguration: + """`configuration` as the generic instrument's own: not generic, and naming the serial numbers + its cold start answers (sealed).""" + configuration.generic = False + configuration.chassis_serial_number = GENERIC_SERIAL_NUMBERS["chassis"] + for side, pod in configuration.pods.items(): + pod.module_serial_number = GENERIC_SERIAL_NUMBERS[side] + return sealed(configuration) + + +def configuration_file(configuration: DeviceConfiguration) -> str: + """`configuration` saved to a new temporary file, for `declared_configuration_json`; removed + when the tests end.""" + folder = Path(tempfile.mkdtemp(prefix="biomek_i7_test_")) + atexit.register(shutil.rmtree, folder, ignore_errors=True) + path = folder / "configuration.json" + configuration.save(path) + return str(path) + + +def generic_driver( + boards: Optional[Sequence[AceBoard]] = None, + configuration: Optional[DeviceConfiguration] = None, +) -> BiomekI7Driver: + """A driver over `boards` (by default the generic instrument replayed), declared by + `configuration` (by default the generic configuration's file).""" + return BiomekI7Driver( + declared_configuration_json=( + str(GENERIC_CONFIGURATION) if configuration is None else configuration_file(configuration) + ), + boards=generic_boards() if boards is None else boards, + ) diff --git a/pylabrobot/beckman_coulter/biomek_i7/units.py b/pylabrobot/beckman_coulter/biomek_i7/units.py new file mode 100644 index 00000000000..0372726e99a --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/units.py @@ -0,0 +1,222 @@ +"""Where PyLabRobot's units meet Biomek's: the one place they are converted. + +The public API takes and returns PyLabRobot's units: mm, mm/s, uL, uL/s, s, deg, in the deck's +frame (Y towards the back). Biomek works in its own, and so does the driver's planning (the +plans, the recipes): cm, its frame (X to the right, Y +towards the front), and a speed field, per mille of each axis's maximum velocity (1..1000). A +public method converts its arguments here once and hands them to its Biomek-unit counterpart; +nothing inside converts back and forth, so a run is the same request for request. + +Imports nothing of the package's, so every layer can use it. +""" + +import math +from dataclasses import dataclass +from typing import TYPE_CHECKING, Optional, Tuple + +from pylabrobot.resources.coordinate import Coordinate + +if TYPE_CHECKING: + from pylabrobot.beckman_coulter.biomek_i7.driver.features.pod import Pod + +MM_PER_CM = 10.0 + +# The deck's frame against Biomek's, chosen rather than measured: its left edge 10 cm left of +# Biomek's X origin, clear of the left trash bin, and its front edge 70 cm in front of Biomek's Y +# origin, clear of the front row of ALPs. x = X + FRAME_X, y = FRAME_Y - Y (mm). +FRAME_X = 10.0 * MM_PER_CM +FRAME_Y = 70.0 * MM_PER_CM + +FULL_SPEED = 1000 +"""The speed field's top: the axis's maximum velocity.""" + + +# -- lengths --------------------------------------------------------------------------------------- + + +def cm(value: float) -> float: + """A length Biomek states in centimetres, in millimetres. + + Every dimension transcribed from a Biomek definition goes through here, written as Biomek states + it, so the literal in the code can be compared against its source as it stands. + """ + return value * MM_PER_CM + + +def to_cm(mm: float) -> float: + """A length in mm, in Biomek's cm.""" + return mm / MM_PER_CM + + +def optional_cm(mm: Optional[float]) -> Optional[float]: + """`to_cm`, passing None through (an argument left to its default).""" + return None if mm is None else to_cm(mm) + + +def to_mm(cm_value: float) -> float: + """A length in Biomek's cm, in mm.""" + return cm_value * MM_PER_CM + + +# -- the frame ------------------------------------------------------------------------------------- + + +def biomek_x(x: float) -> float: + """A deck x, in mm, as Biomek's X in mm.""" + return x - FRAME_X + + +def biomek_y(y: float) -> float: + """A deck y, in mm, as Biomek's Y in mm (the flip is its own inverse: `deck_y`).""" + return FRAME_Y - y + + +def deck_x(x: float) -> float: + """Biomek's X, in mm, as a deck x in mm.""" + return x + FRAME_X + + +deck_y = biomek_y +"""Biomek's Y, in mm, as a deck y in mm.""" + + +@dataclass(frozen=True) +class BiomekPoint: + """A point in Biomek's frame, cm: X to the right, Y towards the front, Z up from the deck.""" + + x: float + y: float + z: float + + +def to_biomek(point: Coordinate) -> BiomekPoint: + """A deck coordinate (mm, PyLabRobot's frame) in Biomek's frame (cm).""" + return BiomekPoint( + biomek_x(point.x) / MM_PER_CM, biomek_y(point.y) / MM_PER_CM, point.z / MM_PER_CM + ) + + +def offset_to_biomek(x: float, y: float, offset: Coordinate) -> Tuple[float, float]: + """Biomek X/Y (cm) moved by a PyLabRobot `offset` (mm): Biomek's Y runs to the front.""" + return x + offset.x / MM_PER_CM, y - offset.y / MM_PER_CM + + +# -- axis values ----------------------------------------------------------------------------------- + + +def _is_y(axis: str) -> bool: + return axis == "GY" or (axis[0] == "Y" and (len(axis) == 1 or axis[1:].isdigit())) + + +def axis_to_biomek(axis: str, value: float) -> float: + """An axis's target in PyLabRobot's units as Biomek's value for it: + - X, Y, Y1-Y8, GY: a deck x / y, mm, in Biomek's frame, cm; + - Z, Z1-Z8, GZ (mm above the deck), GG, S (mm): cm; + - GR: degrees counterclockwise from +X seen from above (PyLabRobot's), as Biomek's, which turn + the other way (its 90 points the fingers to the front); + - the pumps (D, D1-D8): uL, as Biomek's. + """ + if axis == "X": + return to_cm(biomek_x(value)) + if _is_y(axis): + return to_cm(biomek_y(value)) + if axis == "GR": + return -value + if axis[0] == "D": + return value + return to_cm(value) + + +def axis_from_biomek(axis: str, value: float) -> float: + """`axis_to_biomek`'s inverse.""" + if axis == "X": + return deck_x(to_mm(value)) + if _is_y(axis): + return deck_y(to_mm(value)) + if axis == "GR": + return -value + if axis[0] == "D": + return value + return to_mm(value) + + +def axis_to_counts(pod: "Pod", axis: str, value: float) -> int: + """An axis's target in PyLabRobot's units (`axis_to_biomek`) in counts.""" + declared = pod.declared + if declared is None: + raise RuntimeError(f"{pod} has no declared configuration") + return declared.to_counts(axis, axis_to_biomek(axis, value)) + + +def counts_to_axis(pod: "Pod", axis: str, counts: int) -> float: + """An axis's position in counts in PyLabRobot's units (`axis_from_biomek`).""" + declared = pod.declared + if declared is None: + raise RuntimeError(f"{pod} has no declared configuration") + return axis_from_biomek(axis, declared.to_value(axis, counts)) + + +# -- speeds ---------------------------------------------------------------------------------------- + + +def percent_to_field(percent: float, truncate: bool = False) -> int: + """A speed Biomek states in percent of an axis's maximum, as the speed field, 1..1000. Biomek + rounds, except where it truncates (`truncate`: the Span-8 prime's `D1SpeedLimit`, 80.17 %, is + the logged 801).""" + field = int(percent * 10) if truncate else round(percent * 10) + return max(1, min(FULL_SPEED, field)) + + +def _per_unit(pod: "Pod", axis: str) -> float: + """Counts per PyLabRobot unit of `axis` (per mm, deg or uL).""" + declared = pod.declared + if declared is None: + raise RuntimeError(f"{pod} has no declared configuration") + conversion = declared.conversion[axis] + return abs(conversion.const) / (MM_PER_CM if conversion.unit == "cm" else 1.0) + + +def max_rate(pod: "Pod", axis: str) -> float: + """`axis`'s maximum velocity in PyLabRobot units per second (mm/s, deg/s, uL/s).""" + return pod.axis(axis).limits.max_velocity / _per_unit(pod, axis) + + +def rate_to_field(pod: "Pod", axis: str, rate: float, clamp: bool = False) -> int: + """The speed field that moves `axis` at `rate` PyLabRobot units per second (mm/s, deg/s, uL/s): + its peak velocity; the move's acceleration scales with it, as the instrument has one speed per + move. + + Raises: + ValueError: for a rate not above 0, or above the axis's maximum (unless `clamp`, which takes + it to 1..1000). + """ + field = round(rate * _per_unit(pod, axis) / pod.axis(axis).limits.max_velocity * FULL_SPEED) + if clamp: + return max(1, min(FULL_SPEED, field)) + if not rate > 0 or field > FULL_SPEED: + raise ValueError( + f"{pod}: {axis} moves at up to {max_rate(pod, axis):.4g} per second, not {rate}" + ) + return max(1, field) + + +def field_to_rate(pod: "Pod", axis: str, field: int) -> float: + """The rate (PyLabRobot units per second) the speed field `field` moves `axis` at.""" + return field / FULL_SPEED * max_rate(pod, axis) + + +def fraction_to_field(fraction: float) -> int: + """A speed as a fraction of each axis's maximum, (0, 1], as the speed field: for a move of + several axes, whose maxima differ, so that no single rate describes it. + + Raises: + ValueError: outside (0, 1]. + """ + if not 0 < fraction <= 1 or math.isnan(fraction): + raise ValueError(f"a speed fraction is above 0 and at most 1, not {fraction}") + return max(1, round(fraction * FULL_SPEED)) + + +def cutoff_to_counts(pod: "Pod", axis: str, rate: float) -> int: + """A pump's cutoff velocity, uL/s, in counts/s.""" + return round(rate * _per_unit(pod, axis)) diff --git a/pylabrobot/beckman_coulter/biomek_i7/units_tests.py b/pylabrobot/beckman_coulter/biomek_i7/units_tests.py new file mode 100644 index 00000000000..d455ba8c112 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/units_tests.py @@ -0,0 +1,83 @@ +"""The one place PyLabRobot's units meet Biomek's (`units.py`): exact where Biomek's logs are.""" + +import asyncio +import unittest + +from pylabrobot.beckman_coulter.biomek_i7 import units as u +from pylabrobot.resources.coordinate import Coordinate +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import generic_driver + + +class LengthAndFrameTests(unittest.TestCase): + def test_lengths_and_the_frame_round_trip(self) -> None: + for mm in (0.0, 1.0, 123.456, -7.5): + self.assertAlmostEqual(u.to_mm(u.to_cm(mm)), mm) + self.assertAlmostEqual(u.deck_x(u.biomek_x(mm)), mm) + self.assertAlmostEqual(u.deck_y(u.biomek_y(mm)), mm) + self.assertIsNone(u.optional_cm(None)) + point = u.to_biomek(Coordinate(100.0, 700.0, 25.0)) + self.assertEqual(point, u.BiomekPoint(0.0, 0.0, 2.5)) # the frame's origin, 2.5 cm up + + def test_an_offset_turns_with_biomeks_y(self) -> None: + self.assertEqual(u.offset_to_biomek(10.0, 20.0, Coordinate(5.0, 5.0, 0)), (10.5, 19.5)) + + def test_percent_is_biomeks_rounding_or_truncation(self) -> None: + self.assertEqual(u.percent_to_field(25), 250) + self.assertEqual(u.percent_to_field(80.1724), 802) + self.assertEqual(u.percent_to_field(80.1724, truncate=True), 801) # the logged prime speed + self.assertEqual(u.percent_to_field(0.01), 1) + self.assertEqual(u.percent_to_field(150), 1000) + + def test_a_fraction_is_refused_outside_zero_to_one(self) -> None: + self.assertEqual(u.fraction_to_field(1.0), 1000) + self.assertEqual(u.fraction_to_field(0.25), 250) + for bad in (0.0, 1.01, -0.5, float("nan")): + with self.assertRaises(ValueError): + u.fraction_to_field(bad) + + +class RateTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + asyncio.get_running_loop().set_debug(False) + self.driver = generic_driver() + await self.driver.discover() + self.addAsyncCleanup(self.driver.stop) + + def axes(self): + for pod in self.driver.arms: + assert pod.declared is not None + for axis in pod.axes: + if axis.name in pod.declared.conversion and (axis.name[0] in "ZD" or axis.name == "GZ"): + yield pod, axis.name + + def test_every_field_round_trips_on_every_z_and_pump(self) -> None: + checked = 0 + for pod, axis in self.axes(): + for field in range(1, 1001): + rate = u.field_to_rate(pod, axis, field) + self.assertEqual(u.rate_to_field(pod, axis, rate), field, f"{pod} {axis} {field}") + checked += 1 + self.assertGreaterEqual(checked, 20 * 1000) # Z, D, GZ; Z1-Z8, D1-D8, GZ + + def test_a_rate_above_the_maximum_is_refused_naming_it(self) -> None: + left = self.driver.left_x_arm + assert left is not None + top = u.max_rate(left, "Z") + self.assertAlmostEqual(top, 95.0) # mm/s: the Multichannel Z, 24320 counts/s at 2560 /cm + with self.assertRaisesRegex(ValueError, "Z moves at up to 95"): + u.rate_to_field(left, "Z", 125.0) # the STAR's default z speed + with self.assertRaises(ValueError): + u.rate_to_field(left, "Z", 0.0) + self.assertEqual(u.rate_to_field(left, "Z", 125.0, clamp=True), 1000) + + def test_the_flow_rate_is_the_old_plunger_arithmetic(self) -> None: + left = self.driver.left_x_arm + assert left is not None and left.declared is not None + for flow in (1.0, 50.0, 90.0, 100.0, 150.0, 400.0, 2000.0): + per_second = flow * left.declared.conversion["D"].const + old = max(1, min(1000, round(per_second / left.axis("D").limits.max_velocity * 1000))) + self.assertEqual(u.rate_to_field(left, "D", flow, clamp=True), old) + + +if __name__ == "__main__": + unittest.main() From 5bc4f1ff03e8cb1f6cd6ba5edd30b99c90e384d8 Mon Sep 17 00:00:00 2001 From: Cody Moore <46687103+cmoscy@users.noreply.github.com> Date: Tue, 17 Nov 2026 02:56:44 +0000 Subject: [PATCH 09/11] `Biomek i7`: sort imports for ruff I001 --- pylabrobot/beckman_coulter/biomek_i7/units_tests.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pylabrobot/beckman_coulter/biomek_i7/units_tests.py b/pylabrobot/beckman_coulter/biomek_i7/units_tests.py index d455ba8c112..9de769f9d66 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/units_tests.py +++ b/pylabrobot/beckman_coulter/biomek_i7/units_tests.py @@ -4,8 +4,8 @@ import unittest from pylabrobot.beckman_coulter.biomek_i7 import units as u -from pylabrobot.resources.coordinate import Coordinate from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import generic_driver +from pylabrobot.resources.coordinate import Coordinate class LengthAndFrameTests(unittest.TestCase): From f06ab9be711a5c27a52fb81c64229ba23e2e7694 Mon Sep 17 00:00:00 2001 From: cmoscy <46687103+cmoscy@users.noreply.github.com> Date: Wed, 11 Nov 2026 00:08:03 -0800 Subject: [PATCH 10/11] `Biomek i7`: the declared configuration made from Biomek's files, and checked against them `DeviceConfiguration.from_biomek` makes an instrument's declared configuration from its two Biomek sources, read-only, standard library only (`biomek_files/`): - `variant_tree.py`: Biomek's variant-tree files (the instrument file, `.bif`); a file with any byte it cannot account for is refused, not misread. - `instrument_file.py`: the pods (conversions, travel, geometry, settings, gripper, obstacles), the default deck's calibrated positions and layout; Biomek's runtime state in the same file is left out. - `master_controller.py`: the Master Controller's instrument record (its database's `instrument` table, or a text file of it): motor tables, home positions, measured hysteresis, the modules' serial numbers. - `importer.py`: the two put together and checked against each other, each source's path, kind, read time and fingerprint recorded; `check_sources` reads them again and lists what changed. On the instrument, discovery now also refuses a configuration whose sources have changed since it was imported (a re-framed position, a re-measured hysteresis), and warns where they cannot be found. Reading the database closes its connection. Tests: the readers on files written in the test from the generic configuration (a small variant-tree writer and a record writer, `files_tests_support.py`): every value kind and class body, the refusals, the round trip from configuration to files and back, inconsistent sources, changes found by `check_sources`, and the discovery check on the instrument's own path. --- .../biomek_i7/biomek_files/__init__.py | 5 + .../biomek_files/files_tests_support.py | 237 ++++++++++ .../biomek_i7/biomek_files/importer.py | 174 ++++++++ .../biomek_i7/biomek_files/importer_tests.py | 105 +++++ .../biomek_i7/biomek_files/instrument_file.py | 222 ++++++++++ .../biomek_files/instrument_file_tests.py | 84 ++++ .../biomek_files/master_controller.py | 218 +++++++++ .../biomek_files/master_controller_tests.py | 115 +++++ .../biomek_i7/biomek_files/variant_tree.py | 415 ++++++++++++++++++ .../biomek_files/variant_tree_tests.py | 165 +++++++ .../beckman_coulter/biomek_i7/design.md | 9 + .../biomek_i7/driver/configuration.py | 87 +++- .../biomek_i7/driver/master.py | 59 ++- .../biomek_i7/driver/serial_numbers_tests.py | 42 +- 14 files changed, 1914 insertions(+), 23 deletions(-) create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/__init__.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/files_tests_support.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/importer.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/importer_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/instrument_file.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/instrument_file_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/master_controller.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/master_controller_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/variant_tree.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/biomek_files/variant_tree_tests.py diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/__init__.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/__init__.py new file mode 100644 index 00000000000..77a9b218380 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/__init__.py @@ -0,0 +1,5 @@ +"""Reading an instrument's Biomek files into its declared configuration +(`DeviceConfiguration.from_biomek`): Biomek's instrument file (`instrument_file.py`, over the +variant-tree reader `variant_tree.py`) and the Master Controller's instrument record +(`master_controller.py`), put together and checked against each other by `importer.py`. Read-only +on every Biomek file, and standard library only.""" diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/files_tests_support.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/files_tests_support.py new file mode 100644 index 00000000000..37eb214676d --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/files_tests_support.py @@ -0,0 +1,237 @@ +"""Biomek files built for tests: a variant-tree writer, and an instrument file (`.bif`) and a +Master Controller instrument record written from a declared configuration, so the readers can be +checked against inputs made in the test. Not a test module itself, and not used by the driver.""" + +import struct +import zlib +from pathlib import Path +from typing import Any, Dict, List, Optional, Tuple, Union + +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.instrument_file import ( + GEOMETRY, + LIST_SETTINGS, + NESTED_SETTINGS, + OPTIONAL_GEOMETRY, +) +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.variant_tree import ( + DICTIONARY, + HEADER_SIZE, + LIST, + Ref, +) +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import DeviceConfiguration + + +class Array: + """An array variant: its vartype and its elements, as `variant_tree` reads them.""" + + def __init__(self, vartype: int, values: List[Any], fmt: Optional[str] = None): + self.vartype, self.values, self.fmt = vartype, values, fmt + + +class Writer: + """Writes Python values as a variant stream: dicts as dictionaries, lists as lists, `Ref` as a + reference, `Array` as an array; None, bools, ints (int32), floats (double) and strings.""" + + def __init__(self) -> None: + self.objects = 0 + + @staticmethod + def string(text: str) -> bytes: + return struct.pack(" bytes: + if value is None: + return b"\x01" + if value is True: + return b"\x02" + if value is False: + return b"\x03" + if isinstance(value, int): + return b"\x06" + struct.pack(" bytes: + """An object definition's start: its index (the objects so far) and class id.""" + head = b"\x0e" + struct.pack(" bytes: + """A decompressed variant-tree stream: its size, then `root`.""" + body = Writer().variant(root) + return struct.pack(" bytes: + """A variant-tree file's bytes: the header, then the stream compressed.""" + return b"\x00" * HEADER_SIZE + zlib.compress(data) + + +# -- an instrument file ---------------------------------------------------------------------------- + +PODS = {"left": "Pod1", "right": "Pod2"} +POD_TYPES = {"multichannel": "MC", "span8": "SPAN8"} + +# Runtime state an instrument file carries in a pod entry beside its configuration, which the +# reader leaves out. +STATE = {"XPosition": 12.5, "Tip1": "none", "Z3Position": 4.0, "RT_Speed": 3, "LastTips": "T230"} + + +def _pod_entry(side: str, pod: Dict[str, Any]) -> Dict[str, Any]: + settings = dict(pod["settings"]) + entry: Dict[str, Any] = { + "Name": PODS[side], + "PodName": pod["component"], + "PodType": POD_TYPES[pod["module_type"]], + "LeftPod": side == "left", + "CmdGen": { + "Conversion": { + f"{axis}{part}": c[key] + for axis, c in pod["conversion"].items() + for part, key in (("Const", "const"), ("Offset", "offset")) + } + }, + "Min": {axis: low for axis, (low, _) in pod["limits"].items()}, + "Max": {axis: high for axis, (_, high) in pod["limits"].items()}, + "ParkLocation": pod["park"], + "GripperModel": pod["gripper_model"], + "Obstacles": [ + { + "Name": o["name"], + "Buffer": o["buffer"], + **{k.upper(): o[k] for k in ("x1", "x2", "y1", "y2", "z1", "z2") if k in o}, + } + for o in pod["obstacles"] + ], + } + for name, key in GEOMETRY.items(): + entry[key] = pod["geometry"][name] + for name, key in OPTIONAL_GEOMETRY.items(): + if name in pod["geometry"]: + entry[key] = pod["geometry"][name] + if "GripperSqueezeForce" in settings: + entry["Gripper"] = {"SqueezeForce": settings.pop("GripperSqueezeForce")} + for path in NESTED_SETTINGS: + value = settings.pop("/".join(path), None) + if value is not None: + node = entry + for key in path[:-1]: + node = node.setdefault(key, {}) + node[path[-1]] = value + for key, value in settings.items(): + entry[key] = list(value) if key in LIST_SETTINGS else value + entry.update(STATE) + return entry + + +def instrument_file_tree(configuration: DeviceConfiguration, deck: str = "Deck1") -> Dict[str, Any]: + """What an instrument file holds for `configuration`, as plain values for `Writer`: the two pod + entries (with runtime state beside them) and the default deck, with another deck that is not the + default.""" + data = configuration.to_dict() + pipettor: Dict[str, Any] = {"SerialNumber": data["instrument_serial_number"]} + for side, pod in data["pods"].items(): + pipettor[PODS[side]] = _pod_entry(side, pod) + positions = { + name: { + **{f"{a}{n}": p["corners"][n][i] for n in p["corners"] for i, a in enumerate("XYZ")}, + "XSpan": p["x_span"], + "YSpan": p["y_span"], + **{f"Framed{n}": how for n, how in p["framed"].items()}, + } + for name, p in data["deck_positions"].items() + } + groups = { + a["name"]: { + "Type": a["alp_type"], + "column": a["column"], + "row": a["row"], + "Positions": {name: {} for name in a["positions"]}, + **({"X1": a["x1"]} if a.get("x1") is not None else {}), + } + for a in data["deck_layout"] + } + return { + "Devices": {"Pipettor1": pipettor}, + "Decks": { + "Other": {"IsDefault": False, "Positions": {}, "Groups": {}}, + deck: {"IsDefault": True, "Positions": positions, "Groups": groups}, + }, + } + + +def write_instrument_file(configuration: DeviceConfiguration, path: Union[str, Path]) -> None: + Path(path).write_bytes(container(stream(instrument_file_tree(configuration)))) + + +# -- a Master Controller instrument record ------------------------------------------------------- + +PUMP_CONFIGURE = "<8I2iH" # the pump's Configure layout, which its record packs + + +def _motor(axis: Dict[str, Any]) -> str: + limits = axis["limits"] + configure = bytes.fromhex(axis["configure"]) + vmin = amin = 0 + if axis["device"] == 0x12: + (min_start, max_start, vmin, _vmax, min_cutoff, max_cutoff, amin, _amax, _pmin, _pmax, + backlash) = struct.unpack(PUMP_CONFIGURE, configure) # fmt: skip + config = f"#( {min_start} {max_start} {min_cutoff} {max_cutoff} {backlash})" + jmax = "#f" + else: + config = "#vu8(" + " ".join(str(b) for b in configure) + ")" + jmax = str(limits["max_jerk"]) + fields = [ + "", axis["name"], axis["device"], axis["index"], 0, limits["min_position"], + limits["max_position"], axis["home_position"], axis["hysteresis"], vmin, + limits["max_velocity"], amin, limits["max_acceleration"], 0, jmax, "#f", config, + ] # fmt: skip + return "#(" + " ".join(str(f) for f in fields) + ")" + + +def record_text(configuration: DeviceConfiguration) -> str: + """The Master Controller's instrument record for `configuration`, as its database holds it.""" + arms: List[str] = [] + for side, pod in configuration.pods.items(): + kind = {"multichannel": "mc", "span8": "span8"}[pod.module_type] + motors = " ".join(_motor(a) for a in configuration.modules[pod.module_type]) + arms.append(f'#( "{pod.module_serial_number}" {side} {kind} #({motors}))') + return f'#( "{configuration.chassis_serial_number}" ' + " ".join(arms) + ")" + + +def write_record(configuration: DeviceConfiguration, path: Union[str, Path]) -> None: + Path(path).write_text(record_text(configuration) + "\n", encoding="utf-8") + + +def write_database(texts: List[Tuple[str, str]], path: Union[str, Path]) -> None: + """A Master Controller database holding only its `instrument` table: (name, record) rows.""" + import sqlite3 + + db = sqlite3.connect(str(path)) + try: + with db: + db.execute("CREATE TABLE instrument (name TEXT, definition TEXT)") + db.executemany("INSERT INTO instrument VALUES (?, ?)", texts) + finally: + db.close() diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/importer.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/importer.py new file mode 100644 index 00000000000..acc5c65a03b --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/importer.py @@ -0,0 +1,174 @@ +"""Make an instrument's declared configuration from its Biomek files, and check it against them. + +`import_configuration` is the one way a declared configuration is made +(`DeviceConfiguration.from_biomek`): +1. the instrument file gives the pods, the deck's positions and its layout + (`instrument_file.read_instrument_file`); +2. the Master Controller's instrument record gives the motor tables and the modules' serial + numbers (`master_controller.read_master_controller`); +3. the two must describe one instrument: an arm on the same sides in both, each pod's arm type in + the record, and every travel window the instrument file gives inside the motor's own limits; +4. `sources` records each source's path, kind, read time and the fingerprint of the values taken + from it. + +`check_sources` reads the recorded sources again and lists what changed since. +""" + +import datetime +from pathlib import Path +from typing import Any, Dict, List, Optional, Union + +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.instrument_file import read_instrument_file +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.master_controller import ( + read_master_controller, +) +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ( + SOURCES, + DeviceConfiguration, + SourcesCheck, + differences, + fingerprint, + source_parts, +) + + +def _inconsistencies( + instrument_file: Dict[str, Any], master_controller: Dict[str, Any] +) -> List[str]: + """How the two sources disagree about the instrument, one sentence each.""" + problems = [] + serials = master_controller["module_serial_numbers"] + for side in sorted(set(instrument_file["pods"]) | set(serials)): + pod = instrument_file["pods"].get(side) + if pod is None or side not in serials: + problems.append( + f"the {side} arm is in the {'Master Controller record' if pod is None else 'instrument file'}" + " only" + ) + continue + if pod["module_type"] not in master_controller["modules"]: + problems.append(f"the {side} pod is a {pod['module_type']}; the record has no such arm") + continue + axes = {a["name"]: a for a in master_controller["modules"][pod["module_type"]]} + for axis, (low, high) in pod["limits"].items(): + conversion = pod["conversion"].get(axis) + if conversion is None or axis not in axes: + continue + ends = sorted(round((v + conversion["offset"]) * conversion["const"]) for v in (low, high)) + limits = axes[axis]["limits"] + if ends[0] < limits["min_position"] or ends[1] > limits["max_position"]: + problems.append( + f"the {side} pod's {axis} travel, counts {ends}, is outside the motor's " + f"[{limits['min_position']}, {limits['max_position']}]" + ) + return problems + + +def _now() -> str: + return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds") + + +def import_configuration( + bif: Union[str, Path], + master_controller_db: Optional[Union[str, Path]] = None, + master_controller_record: Optional[Union[str, Path]] = None, + chassis_serial_number: Optional[str] = None, +) -> DeviceConfiguration: + """`DeviceConfiguration.from_biomek`. + + Raises: + ValueError: for files that do not describe one consistent instrument. + """ + instrument_file = read_instrument_file(bif) + master_controller = read_master_controller( + master_controller_db=master_controller_db, + master_controller_record=master_controller_record, + chassis_serial_number=chassis_serial_number, + ) + problems = _inconsistencies(instrument_file, master_controller) + if problems: + raise ValueError( + "the instrument file and the Master Controller's record do not describe one instrument: " + + "; ".join(problems) + ) + pods = { + side: {**pod, "module_serial_number": master_controller["module_serial_numbers"][side]} + for side, pod in instrument_file["pods"].items() + } + config = DeviceConfiguration.from_dict({ + "generic": False, + "chassis_serial_number": master_controller["chassis_serial_number"], + "instrument_serial_number": instrument_file["instrument_serial_number"], + "pods": pods, + "deck_positions": instrument_file["deck_positions"], + "deck_layout": instrument_file["deck_layout"], + "modules": master_controller["modules"], + }) # fmt: skip + fingerprints = config.fingerprints() + read_at = _now() + config.sources = { + "instrument_file": { + "kind": "bif", + "path": str(Path(bif).resolve()), + "read_at": read_at, + "fingerprint": fingerprints["instrument_file"], + }, + "master_controller": { + "kind": "database" if master_controller_db is not None else "record", + "path": str(Path(master_controller_db or master_controller_record).resolve()), # type: ignore[arg-type] + "read_at": read_at, + "fingerprint": fingerprints["master_controller"], + }, + } + return config + + +def _read_again(config: DeviceConfiguration, name: str, path: Path) -> Dict[str, Any]: + """The serialized configuration with the values from source `name` read again from `path`.""" + data = config.to_dict() + if name == "instrument_file": + fresh = read_instrument_file(path) + data["instrument_serial_number"] = fresh["instrument_serial_number"] + data["deck_positions"] = fresh["deck_positions"] + data["deck_layout"] = fresh["deck_layout"] + data["pods"] = { + side: {**pod, "module_serial_number": data["pods"].get(side, {}).get("module_serial_number")} + for side, pod in fresh["pods"].items() + } + else: + kind = config.sources[name].get("kind") + fresh = read_master_controller( + master_controller_db=path if kind == "database" else None, + master_controller_record=path if kind == "record" else None, + chassis_serial_number=config.chassis_serial_number, + ) + data["chassis_serial_number"] = fresh["chassis_serial_number"] + data["modules"] = fresh["modules"] + for side, pod in data["pods"].items(): + pod["module_serial_number"] = fresh["module_serial_numbers"].get(side) + # Through the dataclasses, so both sides are serialized the same way. + return DeviceConfiguration.from_dict(data).to_dict() + + +def check_sources(config: DeviceConfiguration) -> SourcesCheck: + """`DeviceConfiguration.check_sources`. + + Raises: + ValueError: for a source that is there but no longer reads as one (the reader's own error). + """ + changed: List[str] = [] + unavailable: List[str] = [] + for name in SOURCES: + source = config.sources.get(name, {}) + if "path" not in source: + unavailable.append(f"{name}: no path recorded") + continue + path = Path(source["path"]) + if not path.exists(): + unavailable.append(f"{name}: {path} not found") + continue + fresh = source_parts(_read_again(config, name, path))[name] + if fingerprint(fresh) != source["fingerprint"]: + declared = source_parts(config.to_dict())[name] + changed += [f"{name}: {line}" for line in differences(declared, fresh)] + return SourcesCheck(changed=changed, unavailable=unavailable) diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/importer_tests.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/importer_tests.py new file mode 100644 index 00000000000..bd69ce15b6d --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/importer_tests.py @@ -0,0 +1,105 @@ +"""`DeviceConfiguration.from_biomek` end to end, on an instrument file and a Master Controller record +written in the test, and `check_sources` finding what changed in them since.""" + +import dataclasses +import tempfile +import unittest +from pathlib import Path + +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.files_tests_support import ( + write_instrument_file, + write_record, +) +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ( + DeviceConfiguration, + differences, +) +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import ( + as_instrument, + generic_configuration, +) + + +def instrument() -> DeviceConfiguration: + """The generic configuration as one instrument's: serial numbers, a measured hysteresis.""" + config = as_instrument(generic_configuration()) + config.instrument_serial_number = "TEST0000001" + for side, pod in config.pods.items(): + pod.settings["HeadSerialNumber"] = f"HEAD-{side}" + next(a for a in config.modules["span8"] if a["name"] == "Z5")["hysteresis"] = 9 + return config + + +class ImportTests(unittest.TestCase): + def setUp(self) -> None: + folder = tempfile.TemporaryDirectory() + self.addCleanup(folder.cleanup) + self.bif = Path(folder.name) / "Biomek_i7.bif" + self.record = Path(folder.name) / "record.txt" + self.config = instrument() + write_instrument_file(self.config, self.bif) + write_record(self.config, self.record) + + def imported(self) -> DeviceConfiguration: + return DeviceConfiguration.from_biomek(self.bif, master_controller_record=self.record) + + def test_importing_gives_the_configuration_the_files_were_written_from(self) -> None: + imported = self.imported() + expected, got = self.config.to_dict(), imported.to_dict() + expected.pop("sources") + sources = got.pop("sources") + self.assertEqual(differences(expected, got), []) + self.assertEqual(sources["instrument_file"]["kind"], "bif") + self.assertEqual(sources["master_controller"]["kind"], "record") + self.assertEqual(Path(sources["instrument_file"]["path"]), self.bif.resolve()) + self.assertEqual(imported.unrecorded_changes(), []) + path = self.bif.parent / "configuration.json" + imported.save(path) + self.assertEqual(DeviceConfiguration.load(path).to_dict(), imported.to_dict()) + + def test_a_travel_window_outside_its_motors_limits_is_refused(self) -> None: + config = instrument() + low, high = config.pods["left"].limits["X"] + config.pods["left"].limits["X"] = (low, high + 1000.0) + write_instrument_file(config, self.bif) + with self.assertRaisesRegex(ValueError, "left pod's X travel.*outside the motor's"): + self.imported() + + def test_unchanged_sources_check_clean(self) -> None: + check = self.imported().check_sources() + self.assertEqual((check.changed, check.unavailable), ([], [])) + + def test_a_re_measured_hysteresis_is_found(self) -> None: + imported = self.imported() + remeasured = instrument() + next(a for a in remeasured.modules["span8"] if a["name"] == "Z5")["hysteresis"] = 10 + write_record(remeasured, self.record) + changed = imported.check_sources().changed + self.assertEqual(len(changed), 1) + self.assertRegex(changed[0], r"^master_controller: modules/span8\[\d+\]/hysteresis: 9 -> 10$") + + def test_a_re_framed_position_is_found(self) -> None: + imported = self.imported() + reframed = instrument() + position = reframed.deck_positions["P6"] + corners = dict(position.corners) + corners[1] = (corners[1][0] + 0.05, corners[1][1], corners[1][2]) + reframed.deck_positions["P6"] = dataclasses.replace(position, corners=corners) + write_instrument_file(reframed, self.bif) + changed = imported.check_sources().changed + self.assertEqual(len(changed), 1) + self.assertTrue(changed[0].startswith("instrument_file: deck_positions/P6/corners/1[0]")) + + def test_sources_not_found_are_unavailable(self) -> None: + imported = self.imported() + self.record.unlink() + check = imported.check_sources() + self.assertEqual(check.changed, []) + self.assertEqual(len(check.unavailable), 1) + self.assertIn("master_controller", check.unavailable[0]) + check = generic_configuration().check_sources() # fingerprints only: no paths + self.assertEqual(len(check.unavailable), 2) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/instrument_file.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/instrument_file.py new file mode 100644 index 00000000000..dc11ff06384 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/instrument_file.py @@ -0,0 +1,222 @@ +"""What a declared configuration takes from Biomek's instrument file (`.bif`). + +From the live pod entries `Devices/Pipettor1/Pod1` and `Pod2`, per pod: +- the counts conversions, travel limits and park location; +- the geometry (the collision model's dimensions); +- every other scalar setting, and the few kept as a dictionary (`NESTED_SETTINGS`); +- the gripper model; +- the deck obstacles Biomek keeps per pod (boxes, an absent bound open); + +and from the default deck, its positions with a corner per pod, and its ALPs. + +The per-device entries are used, not the pod-type defaults under `HardwareSetupInfo/PodTypes`: +they are what reproduces Biomek's logged travel (see `PodGeometry`). Runtime state the file also +carries (positions, tips, gripped labware, `RT_*`) is left out: Biomek rewrites it during ordinary +runs, and it is not configuration. +""" + +from pathlib import Path +from typing import Any, Dict, List, Tuple, Union + +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.variant_tree import Tree, parse_file, plain + +MODULE_TYPES = {"MC": "multichannel", "SPAN8": "span8"} + +# Geometry fields (driver `PodGeometry`) and the pod entry's keys they come from. +GEOMETRY = { + "bridge_x_span": "BridgeXSpan", + "bridge_to_head_x_offset": "BridgeToHeadXOffset", + "mandrel1_x_offset": "Mandrel1XOffset", + "mandrel1_y_offset": "Mandrel1YOffset", + "mandrel_x_spacing": "MandrelXSpacing", + "mandrel_y_spacing": "MandrelYSpacing", + "avoidance_margin": "AvoidanceMargin", + "pod_x_span": "PodXSpan", + "pod_y_span": "PodYSpan", + "gripper_x_offset": "GripperXOffset", + "gripper_y_offset": "GripperYOffset", + "gripper_z_offset": "GripperZOffset", + "frame_safety_left": "Frame_Safety_L", + "frame_safety_right": "Frame_Safety_R", + "additional_safe_height": "AdditionalSafeHeight", + "additional_safe_height_gripper": "AdditionalSafeHeightGripper", +} +OPTIONAL_GEOMETRY = { + "mandrels_x": "MandrelsX", + "mandrels_y": "MandrelsY", + "sub_mandrel_safe_height": "SubMandrelSafeHeight", +} + +# Runtime state Biomek writes back into the file: where things are and what is held. +STATE_KEYS = { + "CurrentSpeed", "DPosition", "GGPosition", "GRPosition", "GYPosition", "GZPosition", + "GripSide", "GrippedLabware", "GrippedLabwareOffsets", "HasGripperProbes", "LastOperation", + "LastTips", "LastValidation", "PositionSaved", "SPosition", "Squeeze", "SqueezeForce", "Tips", + "TipsFrom", "TipsFromLW", "TipsSelected", "XPosition", "YPosition", "ZPosition", +} # fmt: skip + +# Per-probe lists of numbers, kept as settings like the scalars (the seat per probe). +LIST_SETTINGS = {"LoadingOffsets", "BrokenTips"} + +# Settings Biomek keeps as a dictionary in the pod entry, taken as that dictionary under the key's +# path: a Multichannel's mandrel A1 from the pod (`Head/PodToMandrel1`: X, Y, Z in cm, Z the bare +# mandrels' end), a Span-8 probe's tip hub (`DefaultTipHubInfo`: Length, MinRadius, MaxRadius), a +# Span-8's tubing bundle (`LLSWireModel`: where it leaves the probes, its anchor, its lowest point). +NESTED_SETTINGS = (("Head", "PodToMandrel1"), ("DefaultTipHubInfo",), ("LLSWireModel",)) + + +def is_state(key: str) -> bool: + """Whether a pod entry's key is runtime state rather than configuration.""" + if key.startswith("RT_") or key in STATE_KEYS: + return True + # Per channel or pump: Tip1..Tip8, Z1Position.., D1Position.. + return (key.startswith("Tip") and key[3:].isdigit()) or ( + key.endswith("Position") and key[0] in "ZD" and key[1:-8].isdigit() + ) + + +def _plain_dict(tree: Tree, obj: Any) -> Dict[str, Any]: + """A dictionary as plain JSON values, without the reader's bookkeeping keys.""" + + def clean(v: Any) -> Any: + if isinstance(v, dict): + return {k: clean(x) for k, x in v.items() if not k.startswith("$")} + if isinstance(v, list): + return [clean(x) for x in v] + return v + + return clean(plain(obj, tree.objects, inline=False)) # type: ignore[no-any-return] + + +def _unit_of(axis: str) -> str: + if axis == "GR": + return "deg" + if axis[0] == "D": + return "uL" + return "cm" + + +def _pod(tree: Tree, pod: Any) -> Tuple[str, Dict[str, Any]]: + get = tree.deref + e = {k: get(v) for k, v in pod.entries.items()} + conversion_entries = get(get(e["CmdGen"]).entries["Conversion"]).entries + conversion = {} + for key, value in conversion_entries.items(): + if key.endswith("Const"): + axis = key[: -len("Const")] + conversion[axis] = { + "const": value, + "offset": conversion_entries[f"{axis}Offset"], + "unit": _unit_of(axis), + } + low, high = get(e["Min"]).entries, get(e["Max"]).entries + limits = {k: [low[k], high[k]] for k in high if k in low} + geometry: Dict[str, Any] = {name: e[key] for name, key in GEOMETRY.items()} + geometry.update({name: e[key] for name, key in OPTIONAL_GEOMETRY.items() if key in e}) + used = set(GEOMETRY.values()) | set(OPTIONAL_GEOMETRY.values()) + settings: Dict[str, Any] = { + k: v + for k, v in e.items() + if k not in used and not is_state(k) and isinstance(v, (bool, int, float, str)) + } + for k, v in e.items(): + items = getattr(v, "items", None) + if k not in used and not is_state(k) and k in LIST_SETTINGS and isinstance(items, list): + settings[k] = [get(x) for x in items] + for path in NESTED_SETTINGS: + node: Any = pod + for key in path: + entries = getattr(get(node), "entries", None) + node = entries.get(key) if entries is not None else None + if node is None: + break + if node is not None: + settings["/".join(path)] = _plain_dict(tree, get(node)) + # The force a grip closes with (`SF` on GG; Biomek sends it as is). The pod's own + # `SqueezeForce` is runtime state; the gripper's is the setting. + gripper = get(e["Gripper"]).entries if "Gripper" in e else {} + if "SqueezeForce" in gripper: + settings["GripperSqueezeForce"] = gripper["SqueezeForce"] + side = "left" if e["LeftPod"] else "right" + return side, { + "component": e["PodName"], + "module_type": MODULE_TYPES[e["PodType"]], + "source": f"bif:Devices/Pipettor1/{e['Name']}", + "conversion": conversion, + "limits": limits, + "geometry": geometry, + "park": _plain_dict(tree, e["ParkLocation"]), + "settings": settings, + "gripper_model": _plain_dict(tree, e["GripperModel"]), + "obstacles": [ + { + "name": o["Name"], + "buffer": o.get("Buffer", 0.0), + **{k.lower(): o[k] for k in ("X1", "X2", "Y1", "Y2", "Z1", "Z2") if k in o}, + } + for o in (_plain_dict(tree, get(item)) for item in get(e["Obstacles"]).items) + ], + } + + +def _default_deck(tree: Tree) -> Tuple[str, Any]: + get = tree.deref + decks = get(tree.root.entries["Decks"]) + name = next(k for k in decks.entries if get(decks.entries[k]).entries.get("IsDefault")) + return name, get(decks.entries[name]) + + +def _positions(tree: Tree) -> Dict[str, Dict[str, Any]]: + """The default deck's positions: each one's corner per pod (`X`/`Y`/`Z`), its spans and + how each corner was framed.""" + get = tree.deref + positions = {} + for name, ref in get(_default_deck(tree)[1].entries["Positions"]).entries.items(): + e = get(ref).entries + if not all(f"{a}{n}" in e for a in "XYZ" for n in (1, 2)): + continue + positions[name] = { + "corners": {str(n): [e[f"X{n}"], e[f"Y{n}"], e[f"Z{n}"]] for n in (1, 2)}, + "x_span": e["XSpan"], + "y_span": e["YSpan"], + "framed": {str(n): e[f"Framed{n}"] for n in (1, 2) if f"Framed{n}" in e}, + } + return dict(sorted(positions.items())) + + +def _layout(tree: Tree) -> List[Dict[str, Any]]: + """The default deck's ALPs (`Decks//Groups`): each one's name, `Type`, pin `column` and + `row`, its positions' names and its left edge `X1` (cm), left to right.""" + get = tree.deref + layout = [] + for name, ref in get(_default_deck(tree)[1].entries["Groups"]).entries.items(): + e = get(ref).entries + positions = get(e.get("Positions")) + layout.append({ + "name": name, + "alp_type": e["Type"], + "column": e["column"], + "row": e["row"], + "positions": list(positions.entries) if positions is not None and positions.entries else [], + "x1": e.get("X1"), + }) # fmt: skip + return sorted(layout, key=lambda a: (a["column"], a["row"])) + + +def read_instrument_file(path: Union[str, Path]) -> Dict[str, Any]: + """The part of a declared configuration an instrument file gives, as `DeviceConfiguration` + serializes it: `instrument_serial_number`, `pods` (without their module serial numbers, which + the Master Controller's record gives), `deck_positions` and `deck_layout`. + + Raises: + ParseError: for a file this reader cannot account for completely. + """ + tree = parse_file(str(path)) + pipettor = tree.deref(tree.deref(tree.root.entries["Devices"]).entries["Pipettor1"]) + pods = dict(_pod(tree, tree.deref(pipettor.entries[name])) for name in ("Pod1", "Pod2")) + return { + "instrument_serial_number": pipettor.entries.get("SerialNumber"), + "pods": pods, + "deck_positions": _positions(tree), + "deck_layout": _layout(tree), + } diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/instrument_file_tests.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/instrument_file_tests.py new file mode 100644 index 00000000000..1c739b202d2 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/instrument_file_tests.py @@ -0,0 +1,84 @@ +"""What a declared configuration takes from an instrument file, read from one written in the test +from the package's generic configuration.""" + +import tempfile +import unittest +from pathlib import Path + +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.files_tests_support import ( + STATE, + container, + instrument_file_tree, + stream, + write_instrument_file, +) +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.instrument_file import ( + is_state, + read_instrument_file, +) +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.variant_tree import ParseError +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import generic_configuration + + +def configuration(): # type: ignore[no-untyped-def] + config = generic_configuration() + config.instrument_serial_number = "TEST0000001" + for side, pod in config.pods.items(): + pod.settings["HeadSerialNumber"] = f"HEAD-{side}" + return config + + +class InstrumentFileTests(unittest.TestCase): + def setUp(self) -> None: + folder = tempfile.TemporaryDirectory() + self.addCleanup(folder.cleanup) + self.path = Path(folder.name) / "Biomek_i7.bif" + self.config = configuration() + write_instrument_file(self.config, self.path) + self.read = read_instrument_file(self.path) + self.expected = self.config.to_dict() + + def test_the_pods_come_back_as_written(self) -> None: + for side, pod in self.expected["pods"].items(): + with self.subTest(side=side): + # The module serial numbers are the Master Controller record's, not the instrument file's. + expected = {k: v for k, v in pod.items() if k != "module_serial_number"} + self.assertEqual(self.read["pods"][side], expected) + self.assertEqual(self.read["instrument_serial_number"], "TEST0000001") + + def test_the_default_deck_comes_back_as_written(self) -> None: + self.assertEqual(self.read["deck_positions"], self.expected["deck_positions"]) + self.assertEqual(self.read["deck_layout"], self.expected["deck_layout"]) + + def test_runtime_state_is_left_out(self) -> None: + for side in ("left", "right"): + for key in STATE: + self.assertNotIn(key, self.read["pods"][side]["settings"]) + for key in ("RT_Anything", "Tip8", "D3Position", "Z1Position", "GrippedLabware"): + self.assertTrue(is_state(key), key) + for key in ("TipLoadForceLimitSlope", "Tips2Load", "ZMargin"): + self.assertFalse(is_state(key), key) + + def test_settings_kept_as_dictionaries_and_lists(self) -> None: + for side, pod in self.expected["pods"].items(): + for key, value in pod["settings"].items(): + if isinstance(value, (dict, list)): + self.assertEqual(self.read["pods"][side]["settings"][key], value, (side, key)) + + def test_a_position_without_both_corners_is_left_out(self) -> None: + tree = instrument_file_tree(self.config) + positions = tree["Decks"]["Deck1"]["Positions"] + name = next(iter(positions)) + del positions[name]["Z2"] + self.path.write_bytes(container(stream(tree))) + self.assertNotIn(name, read_instrument_file(self.path)["deck_positions"]) + + def test_a_file_this_reader_cannot_account_for_is_refused(self) -> None: + data = stream(instrument_file_tree(self.config)) + self.path.write_bytes(container(data[:4] + data[4:] + b"\x01")) + with self.assertRaises(ParseError): + read_instrument_file(self.path) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/master_controller.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/master_controller.py new file mode 100644 index 00000000000..9c8bdc4184c --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/master_controller.py @@ -0,0 +1,218 @@ +"""What a declared configuration takes from Biomek's Master Controller: its instrument record. + +The Master Controller keeps one record per instrument it drives, in the `instrument` table of its +database (`C:\\ProgramData\\Beckman Coulter\\Biomek Master Controller\\Log.db3`; the same file +holds its logs). The record is the instrument's motor configuration, keyed by serial numbers: + + #( "" + #( "" left|right mc|span8 + #(#( ...) ...)) + ...) + +Each `` holds, in order: the axis's name, device byte, index and mask; its minimum and +maximum position; its home position (where Home All leaves it); its hysteresis (what the Master +Controller adds to its targets, measured per instrument: non-zero on the Span-8 Z channels); its +minimum and maximum velocity, acceleration and jerk (`#f` for none); a simulated flag; and its +Configure parameters as sent to its board (`#vu8(...)`), or for a syringe pump a `` +of its start and cutoff velocity limits and backlash, from which the pump's Configure parameters +are packed. Every value checks against the Configure bytes the Master Controller sends at a cold +start (the same limits; the same bytes). The record is rewritten only when the instrument's +motors are changed or measured, and carries no runtime state. + +The record is read in one of two ways, to the same result: +- from the database, read-only (`master_controller_db`), choosing the instrument by its chassis + serial number when the database holds more than one; +- from a text file holding the record (`master_controller_record`), for a computer without the + database, or a Python without `sqlite3`. +""" + +import re +import struct +from pathlib import Path +from typing import Any, Dict, List, Optional, Tuple, Union + +MODULE_TYPES = {"mc": "multichannel", "span8": "span8"} +PUMP_DEVICE = 0x12 + +_TOKEN = re.compile(r'\s*(#vu8\(|#\(|\(|\)|"(?:[^"\\]|\\.)*"|[^\s()"]+)') + + +class Symbol(str): + """A bare word of the record (a name, `left`, `#f`), as opposed to a string.""" + + +def parse_record(text: str) -> List[Any]: + """Every top-level value of a record's text: vectors and lists as Python lists, byte vectors as + `bytes`, integers as `int`, `#t` / `#f` as `True` / `False`, strings as `str`, other words as + `Symbol`. + + Raises: + ValueError: for text that is not a record. + """ + tokens = [] + at = 0 + while text[at:].strip(): + m = _TOKEN.match(text, at) + if m is None: + raise ValueError(f"the Master Controller record holds text this reader does not know at {at}") + tokens.append(m.group(1)) + at = m.end() + pos = 0 + + def value() -> Any: + nonlocal pos + token = tokens[pos] + pos += 1 + if token in ("#(", "("): + items = [] + while tokens[pos] != ")": + items.append(value()) + pos += 1 + return items + if token == "#vu8(": + data = [] + while tokens[pos] != ")": + data.append(int(tokens[pos])) + pos += 1 + pos += 1 + return bytes(data) + if token == ")": + raise ValueError("unbalanced ')' in the Master Controller record") + if token.startswith('"'): + return token[1:-1] + if token in ("#t", "#f"): + return token == "#t" + if re.fullmatch(r"-?\d+", token): + return int(token) + return Symbol(token) + + out = [] + try: + while pos < len(tokens): + out.append(value()) + except IndexError as e: + raise ValueError("the Master Controller record ends inside a value") from e + return out + + +def _axis(motor: List[Any]) -> Dict[str, Any]: + """One `` record as a declared configuration's axis.""" + (_, name, device, index, _mask, pmin, pmax, phome, hysteresis, vmin, vmax, amin, amax, _jmin, + jmax, _simulated, config) = motor # fmt: skip + limits: Dict[str, int] = {"max_velocity": vmax, "max_acceleration": amax} + if device == PUMP_DEVICE: + _, min_start, max_start, min_cutoff, max_cutoff, backlash = config + configure = struct.pack( + "<8I2iH", min_start, max_start, vmin, vmax, min_cutoff, max_cutoff, amin, amax, pmin, pmax, + backlash, + ) # fmt: skip + else: + configure = config + limits["max_jerk"] = jmax if jmax is not False else 0 + limits.update({"min_position": pmin, "max_position": pmax}) + return { + "name": str(name), + "device": device, + "index": index, + "configure": configure.hex(), + "limits": limits, + "home_position": phome, + "hysteresis": hysteresis, + } + + +def _instrument(record: List[Any]) -> Dict[str, Any]: + """One `` record as the part of a declared configuration it gives.""" + if not record or record[0] != "": + raise ValueError("not a Master Controller instrument record") + modules: Dict[str, List[Dict[str, Any]]] = {} + module_serial_numbers: Dict[str, str] = {} + for arm in record[2:]: + if not arm or arm[0] != "": + raise ValueError("an instrument record entry that is not an arm") + _, serial, side, arm_type, motors = arm + if arm_type not in MODULE_TYPES: + raise ValueError(f"a {arm_type} arm, which this driver has no tables for") + module = MODULE_TYPES[arm_type] + if module in modules: + raise ValueError(f"two {module} arms in one instrument record") + modules[module] = [_axis(m) for m in motors] + module_serial_numbers[str(side)] = serial.upper() + return { + "chassis_serial_number": record[1].upper(), + "module_serial_numbers": module_serial_numbers, + "modules": modules, + } + + +def _records( + master_controller_db: Optional[Union[str, Path]], + master_controller_record: Optional[Union[str, Path]], +) -> List[str]: + if (master_controller_db is None) == (master_controller_record is None): + raise ValueError("give one of master_controller_db and master_controller_record") + if master_controller_record is not None: + return [Path(master_controller_record).read_text(encoding="utf-8")] + import contextlib + import sqlite3 # standard library; only needed for this way of reading the record + + uri = Path(master_controller_db).resolve().as_uri() + "?mode=ro" # type: ignore[arg-type] + with contextlib.closing(sqlite3.connect(uri, uri=True)) as db: # closed, not only committed + return [row[0] for row in db.execute("SELECT definition FROM instrument ORDER BY name")] + + +def read_master_controller( + master_controller_db: Optional[Union[str, Path]] = None, + master_controller_record: Optional[Union[str, Path]] = None, + chassis_serial_number: Optional[str] = None, +) -> Dict[str, Any]: + """The part of a declared configuration the Master Controller's instrument record gives: + `chassis_serial_number`, `module_serial_numbers` (per side) and `modules` (the motor tables). + + Args: + master_controller_db: its database (`Log.db3`), opened read-only. + master_controller_record: a text file holding the record, instead of the database. + chassis_serial_number: which instrument, when more than one record is found. + + Raises: + ValueError: for neither or both sources, no record of that instrument, more than one record + and no chassis serial number to choose by, or a record this reader does not know. + """ + found = [ + _instrument(record) + for text in _records(master_controller_db, master_controller_record) + for record in parse_record(text) + ] + if chassis_serial_number is not None: + found = [r for r in found if r["chassis_serial_number"] == chassis_serial_number.upper()] + if len(found) != 1: + serials = [r["chassis_serial_number"] for r in found] + raise ValueError( + f"{len(found)} Master Controller instrument records" + + (f" for chassis {chassis_serial_number}" if chassis_serial_number else "") + + (f" ({', '.join(serials)}); pass chassis_serial_number" if len(found) > 1 else "") + ) + return found[0] + + +def write_record(text: str, path: Union[str, Path]) -> None: + """Write a record's text to a file `master_controller_record` reads, after checking it parses.""" + for record in parse_record(text): + _instrument(record) + Path(path).write_text(text + "\n", encoding="utf-8") + + +def record_text( + master_controller_db: Union[str, Path], chassis_serial_number: Optional[str] = None +) -> str: + """The record's text as the database holds it, for `write_record`: the one instrument, or the one + with that chassis serial number.""" + texts = _records(master_controller_db, None) + matches: List[Tuple[str, Dict[str, Any]]] = [ + (t, _instrument(r)) for t in texts for r in parse_record(t) + ] + if chassis_serial_number is not None: + matches = [m for m in matches if m[1]["chassis_serial_number"] == chassis_serial_number.upper()] + if len(matches) != 1: + raise ValueError(f"{len(matches)} matching Master Controller instrument records") + return matches[0][0] diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/master_controller_tests.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/master_controller_tests.py new file mode 100644 index 00000000000..0432c192110 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/master_controller_tests.py @@ -0,0 +1,115 @@ +"""What a declared configuration takes from the Master Controller's instrument record, read from a +record written in the test from the package's generic configuration, as text and as a database.""" + +import tempfile +import unittest +from pathlib import Path + +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.files_tests_support import ( + record_text, + write_database, + write_record, +) +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.master_controller import ( + Symbol, + parse_record, + read_master_controller, +) +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.master_controller import ( + write_record as save_record, +) +from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import DeviceConfiguration +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import ( + as_instrument, + generic_configuration, +) + + +def instrument(chassis: str = "simulated00100000000000000000000") -> DeviceConfiguration: + """The generic configuration as an instrument's, with a measured hysteresis on a Span-8 Z.""" + config = as_instrument(generic_configuration()) + config.chassis_serial_number = chassis + z2 = next(a for a in config.modules["span8"] if a["name"] == "Z2") + z2["hysteresis"] = 11 + return config + + +class RecordTextTests(unittest.TestCase): + def test_values_of_each_kind(self) -> None: + parsed = parse_record('#( "ab\\"c" left 12 -3 #t #f (1 2) #vu8(0 255 7))') + self.assertEqual( + parsed, [["", 'ab\\"c', "left", 12, -3, True, False, [1, 2], b"\x00\xff\x07"]] + ) + self.assertIsInstance(parsed[0][2], Symbol) + self.assertNotIsInstance(parsed[0][1], Symbol) + + def test_text_that_is_not_a_record_is_refused(self) -> None: + for text in ("#(1 2", ")", '#(1 "unclosed)'): + with self.subTest(text=text), self.assertRaises(ValueError): + parse_record(text) + + +class ReadTests(unittest.TestCase): + def setUp(self) -> None: + folder = tempfile.TemporaryDirectory() + self.addCleanup(folder.cleanup) + self.folder = Path(folder.name) + self.config = instrument() + + def test_the_record_gives_the_motor_tables_and_serial_numbers(self) -> None: + path = self.folder / "record.txt" + write_record(self.config, path) + read = read_master_controller(master_controller_record=path) + self.assertEqual( + read["modules"], self.config.modules + ) # pumps' Configure packed from the record + self.assertEqual( + read["chassis_serial_number"], "SIMULATED00100000000000000000000" + ) # upper case + self.assertEqual( + read["module_serial_numbers"], + {side: pod.module_serial_number for side, pod in self.config.pods.items()}, + ) + + def test_a_database_gives_the_same(self) -> None: + db = self.folder / "Log.db3" + write_database([("one", record_text(self.config))], db) + record = self.folder / "record.txt" + write_record(self.config, record) + self.assertEqual( + read_master_controller(master_controller_db=db), + read_master_controller(master_controller_record=record), + ) + + def test_an_instrument_is_chosen_by_its_chassis(self) -> None: + db = self.folder / "Log.db3" + other = instrument(chassis="B" * 32) + write_database([("a", record_text(self.config)), ("b", record_text(other))], db) + with self.assertRaisesRegex(ValueError, "2 Master Controller instrument records.*pass"): + read_master_controller(master_controller_db=db) + chosen = read_master_controller(master_controller_db=db, chassis_serial_number="b" * 32) + self.assertEqual(chosen["chassis_serial_number"], "B" * 32) + with self.assertRaisesRegex(ValueError, "0 Master Controller instrument records for chassis"): + read_master_controller(master_controller_db=db, chassis_serial_number="0" * 32) + + def test_one_source_exactly(self) -> None: + path = self.folder / "record.txt" + write_record(self.config, path) + with self.assertRaisesRegex(ValueError, "one of"): + read_master_controller() + with self.assertRaisesRegex(ValueError, "one of"): + read_master_controller(master_controller_db=path, master_controller_record=path) + + def test_records_this_reader_does_not_know_are_refused(self) -> None: + text = record_text(self.config) + for bad, message in ( + ("#( 1)", "not a Master Controller instrument record"), + (text.replace(" span8 #(", " span96 #("), "span96 arm"), + (text.replace(" span8 #(", " mc #("), "two multichannel arms"), + ): + with self.subTest(message=message), self.assertRaisesRegex(ValueError, message): + save_record(bad, self.folder / "record.txt") + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/variant_tree.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/variant_tree.py new file mode 100644 index 00000000000..6ea4b7d1b5f --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/variant_tree.py @@ -0,0 +1,415 @@ +"""Read Biomek's variant-tree files: the instrument file (`.bif`), and labware / tip class data. + +Container: 5 header bytes, then zlib. Inside is one int32 size and one variant. A variant starts +with one code byte; its low nibble is the type and bit 0x10 marks an interface reference: + + 0x00 empty 0x01 null 0x02 true 0x03 false 0x04 byte 0x05 int16 0x06 int32 + 0x07 single 0x08 double 0x09 currency (int64 / 10000) 0x0A date (double, days) + 0x0B string (int32 length, UTF-16LE) 0x0C error (int32) + 0x0D reference to an object defined earlier (int32 index) + 0x0E object definition: int32 index (= objects so far), 16-byte class id, then the object's body + 0x0F array: vartype byte, uint16 dims, dims x (uint32 count, int32 lbound), then the elements + +Two classes carry most of a file: + +- a dictionary: a flag byte; if non-zero a class id follows, and with flag 1 an extension body of + that class comes first; then an int32 count of (string key, variant value) entries; +- a list: an int32 count of variants. + +The other classes' bodies (`EXTENSIONS`, `OBJECTS`) were measured on the files in hand. `parse` +refuses to finish with any byte unaccounted for, so a file in a format not seen here is refused, +not misread. +""" + +import struct +import uuid +import zlib +from dataclasses import dataclass, field +from typing import Any, Callable, Dict, Iterator, List, Optional, Tuple + +HEADER_SIZE = 5 + + +def _class_id(text: str) -> bytes: + return uuid.UUID(text).bytes_le + + +DICTIONARY = _class_id("E4C29FFF-BCE3-44DB-BEB6-5B5B6EBC0DF1") +LIST = _class_id("62DBE1C1-B344-4AB4-804F-73722341CBE5") +DATA_SET_MANAGER = _class_id("B6D3BEC0-0085-4F00-A09A-C310B1DAFB72") +DATA_SET = _class_id("C025C3B2-323C-4AC8-B61D-1F13EFFFE37F") +LABWARE = _class_id("739C5987-FD91-4D70-82CB-2A5B768E3CCB") +WORKSPACE = _class_id("23008335-C70E-46F0-87A8-4948F25298E8") +DECK_POSITION = _class_id("0E7CDB5A-E774-4F1A-A72E-A013F06ED62A") +PROMISE = _class_id("FD7B3B46-B8DA-4E47-B7FF-51B975DE468D") +WELL_VALUES = _class_id("51297284-DD58-4725-A9B9-429BD5610D69") + +CLASS_NAMES = { + DICTIONARY: "dictionary", + LIST: "list", + DATA_SET_MANAGER: "data set manager", + DATA_SET: "data set", + LABWARE: "labware", + WORKSPACE: "workspace", + DECK_POSITION: "deck position", + PROMISE: "promise", + WELL_VALUES: "well values", +} + +# Array vartypes whose elements are fixed-size values, read as raw bytes. +_ARRAY_RAW = { + 0x02: "h", + 0x03: "i", + 0x04: "f", + 0x05: "d", + 0x06: "q", + 0x07: "d", + 0x0A: "i", + 0x0B: "h", + 0x11: "B", +} + + +class ParseError(Exception): + """The file is not a variant tree as this reader knows it.""" + + +@dataclass +class Obj: + """An object definition: its class, what its extension or own body read, and its entries.""" + + index: int + class_id: bytes + flag: Optional[int] = None + extension_class_id: Optional[bytes] = None + extension: Any = None + entries: Optional[Dict[str, Any]] = None + items: Optional[List[Any]] = None + + @property + def class_name(self) -> str: + return CLASS_NAMES.get(self.class_id, str(uuid.UUID(bytes_le=self.class_id))) + + @property + def extension_name(self) -> Optional[str]: + if self.extension_class_id is None: + return None + return CLASS_NAMES.get( + self.extension_class_id, str(uuid.UUID(bytes_le=self.extension_class_id)) + ) + + +@dataclass +class Ref: + """A reference to an object defined earlier in the stream.""" + + index: int + + +@dataclass +class Currency: + value: int # x 10000 + + +@dataclass +class Date: + days: float # since 1899-12-30 + + +@dataclass +class Tree: + root: Any + objects: List[Obj] = field(default_factory=list) + + def deref(self, value: Any) -> Any: + """`value`, or the object it refers to.""" + return self.objects[value.index] if isinstance(value, Ref) else value + + +class Reader: + def __init__(self, data: bytes): + self.data = data + self.pos = 0 + self.objects: List[Obj] = [] + + # -- primitives -------------------------------------------------------------------------------- + + def take(self, n: int) -> bytes: + if n < 0 or self.pos + n > len(self.data): + raise ParseError(f"read of {n} bytes past the end at {self.pos}") + chunk = self.data[self.pos : self.pos + n] + self.pos += n + return chunk + + def unpack(self, fmt: str) -> Any: + return struct.unpack("<" + fmt, self.take(struct.calcsize("<" + fmt)))[0] + + def string(self) -> str: + n = self.unpack("i") + if n < 0: + raise ParseError(f"negative string length at {self.pos - 4}") + return self.take(2 * n).decode("utf-16-le") + + # -- variants ---------------------------------------------------------------------------------- + + def variant(self) -> Any: + at = self.pos + code = self.unpack("B") + kind = code & 0x0F + if kind == 0x00: + if code not in (0x00, 0x10, 0x20): + raise ParseError(f"unknown stream code {code:#x} at {at}") + return None + if kind == 0x01: + return None + if kind == 0x02: + return True + if kind == 0x03: + return False + if kind == 0x04: + return self.unpack("B") + if kind == 0x05: + return self.unpack("h") + if kind == 0x06: + return self.unpack("i") + if kind == 0x07: + return self.unpack("f") + if kind == 0x08: + return self.unpack("d") + if kind == 0x09: + return Currency(self.unpack("q")) + if kind == 0x0A: + return Date(self.unpack("d")) + if kind == 0x0B: + return self.string() + if kind == 0x0C: + return ("error", self.unpack("i")) + if kind == 0x0D: + index = self.unpack("i") + if not 0 <= index < len(self.objects): + raise ParseError(f"undefined object reference {index} at {at}") + return Ref(index) + if kind == 0x0E: + return self.object(at) + if kind == 0x0F: + return self.array() + raise ParseError(f"unknown stream code {code:#x} at {at}") # pragma: no cover + + def array(self) -> List[Any]: + vartype = self.unpack("B") + dims = self.unpack("H") + counts = [] + for _ in range(dims): + counts.append(self.unpack("I")) + self.unpack("i") # lower bound + total = 1 + for c in counts: + total *= c + if vartype in _ARRAY_RAW: + fmt = _ARRAY_RAW[vartype] + return list(struct.unpack(f"<{total}{fmt}", self.take(total * struct.calcsize(fmt)))) + if vartype == 0x08: + return [self.string() for _ in range(total)] + if vartype in (0x09, 0x0C, 0x0D): + return [self.variant() for _ in range(total)] + raise ParseError(f"invalid array vartype {vartype:#x} at {self.pos}") + + def object(self, at: int) -> Obj: + index = self.unpack("i") + if index != len(self.objects): + raise ParseError(f"invalid object definition {index} (expected {len(self.objects)}) at {at}") + obj = Obj(index=index, class_id=self.take(16)) + self.objects.append(obj) + if obj.class_id == DICTIONARY: + self.dictionary(obj) + elif obj.class_id == LIST: + obj.items = [self.variant() for _ in range(self.unpack("i"))] + elif obj.class_id in OBJECTS: + obj.extension = OBJECTS[obj.class_id](self) + else: + raise ParseError(f"no reader for class {obj.class_name} at {at}") + return obj + + def dictionary(self, obj: Obj) -> None: + obj.flag = self.unpack("B") + if obj.flag: + obj.extension_class_id = self.take(16) + if obj.flag == 1: + loader = EXTENSIONS.get(obj.extension_class_id) + if loader is None: + raise ParseError(f"no reader for extension {obj.extension_name} at {self.pos}") + obj.extension = loader(self) + elif obj.flag != 4: + raise ParseError(f"unknown dictionary flag {obj.flag} at {self.pos}") + count = self.unpack("i") + if count < 0: + raise ParseError(f"negative dictionary count at {self.pos - 4}") + obj.entries = {} + for _ in range(count): + key = self.string() + obj.entries[key] = self.variant() + + +# -- class-specific bodies --------------------------------------------------------------------- + + +def _string_list(r: Reader) -> List[str]: + """Data set manager: the data set names in order, as a counted list of strings.""" + return [r.string() for _ in range(r.unpack("i"))] + + +def _nothing(r: Reader) -> None: + """Data set: nothing of its own before the dictionary's entries.""" + return None + + +def _labware(r: Reader) -> Dict[str, Any]: + """Labware: per-well state, as (array variant, int32 well count) pairs. + + Measured on 8-, 96- and 384-well labware: four pairs, a flag byte, six more pairs when it is + set, and a closing flag byte that has only been seen clear. + """ + + def pairs(n: int) -> List[Any]: + out = [] + for _ in range(n): + values = r.variant() + wells = r.unpack("i") + if not isinstance(values, list) or len(values) != wells: + raise ParseError(f"labware array of {wells} wells does not hold {wells} at {r.pos}") + out.append(values) + return out + + arrays = pairs(4) + more = r.unpack("B") + if more: + arrays += pairs(6) + last = r.unpack("B") + if last: + raise ParseError(f"labware closing flag {last} not seen before, at {r.pos - 1}") + return {"arrays": arrays} + + +def _well_values(r: Reader) -> Dict[str, Any]: + """Well values: one value per well of a labware, named (a string), as int32 columns and int32 + rows, then columns x rows variants. Measured on the per-well liquid names (`DataSets` / + `RuntimeDataSets` "Liquid") Biomek writes into the instrument file with the deck's labware after + a run: 24-, 96- and 8-well labware.""" + name = r.string() + columns, rows = r.unpack("i"), r.unpack("i") + if columns < 0 or rows < 0: + raise ParseError(f"well values of {columns} x {rows} wells at {r.pos - 8}") + return { + "name": name, + "columns": columns, + "rows": rows, + "values": [r.variant() for _ in range(columns * rows)], + } + + +def _workspace(r: Reader) -> Dict[str, Any]: + """Workspace root: an int32 version, then two (int32, int32, int32, int32) records. Measured.""" + version = r.unpack("i") + records = [tuple(r.unpack("i") for _ in range(4)) for _ in range(2)] + return {"version": version, "records": records} + + +def _promise(r: Reader) -> Dict[str, Any]: + """Promise: three doubles, then a variant, then int32 and a byte. Measured.""" + values = [r.unpack("d") for _ in range(3)] + status = r.variant() + tail = (r.unpack("i"), r.unpack("B")) + return {"values": values, "status": status, "tail": tail} + + +EXTENSIONS: Dict[bytes, Callable[[Reader], Any]] = { + DATA_SET_MANAGER: _string_list, + DATA_SET: _nothing, + LABWARE: _labware, + WORKSPACE: _workspace, + WELL_VALUES: _well_values, +} + +OBJECTS: Dict[bytes, Callable[[Reader], Any]] = { + PROMISE: _promise, +} + + +# -- entry points ------------------------------------------------------------------------------ + + +def decompress(blob: bytes) -> bytes: + return zlib.decompress(blob[HEADER_SIZE:]) + + +def parse(data: bytes) -> Tree: + """Parse a decompressed stream completely: one int32 size, then one variant, nothing after. + + Raises: + ParseError: for anything else. + """ + r = Reader(data) + size = r.unpack("i") + if size != len(data) - 4: + raise ParseError(f"stream says {size} bytes, holds {len(data) - 4}") + root = r.variant() + if r.pos != len(data): + raise ParseError(f"{len(data) - r.pos} bytes left unparsed at {r.pos}") + return Tree(root=root, objects=r.objects) + + +def parse_file(path: str) -> Tree: + with open(path, "rb") as f: + return parse(decompress(f.read())) + + +def plain(value: Any, objects: List[Obj], inline: bool = False, _open: Optional[set] = None) -> Any: + """The tree as JSON-ready values: dictionaries as dicts, lists as lists, refs as {"$ref": n}. + + With `inline`, a reference is replaced by the object it names, except inside that same object + (a cycle), where it stays {"$ref": n}. + """ + _open = set() if _open is None else _open + if isinstance(value, Ref) and inline and value.index not in _open: + return plain(objects[value.index], objects, inline, _open) + if isinstance(value, Obj): + _open = _open | {value.index} + + def sub(v: Any) -> Any: + return plain(v, objects, inline, _open) + + if value.entries is not None: + out: Dict[str, Any] = {} + if value.extension_class_id is not None: + out["$class"] = value.extension_name + if value.extension is not None: + out["$extension"] = sub(value.extension) + out["$id"] = value.index + out.update({k: sub(v) for k, v in value.entries.items()}) + return out + if value.items is not None: + return [sub(v) for v in value.items] + return {"$class": value.class_name, "$id": value.index, "$body": sub(value.extension)} + if isinstance(value, Ref): + return {"$ref": value.index} + if isinstance(value, Currency): + return value.value / 10000 + if isinstance(value, Date): + return {"$date": value.days} + if isinstance(value, dict): + return {k: plain(v, objects, inline, _open) for k, v in value.items()} + if isinstance(value, (list, tuple)): + return [plain(v, objects, inline, _open) for v in value] + return value + + +def walk(value: Any, path: str = "") -> Iterator[Tuple[str, Any]]: + """Every leaf value with its path (`/Decks/Standard/Groups/...`), over a `plain` tree.""" + if isinstance(value, dict): + for k, v in value.items(): + yield from walk(v, f"{path}/{k}") + elif isinstance(value, list): + for i, v in enumerate(value): + yield from walk(v, f"{path}[{i}]") + else: + yield path, value diff --git a/pylabrobot/beckman_coulter/biomek_i7/biomek_files/variant_tree_tests.py b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/variant_tree_tests.py new file mode 100644 index 00000000000..b6d31ef978f --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/biomek_files/variant_tree_tests.py @@ -0,0 +1,165 @@ +"""The variant-tree reader on streams built in the test: every value kind, objects and references, +the class bodies it knows, and the refusals that keep a file of another format from being misread.""" + +import struct +import unittest +import uuid + +from pylabrobot.beckman_coulter.biomek_i7.biomek_files import variant_tree as vt +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.files_tests_support import ( + Array, + Writer, + container, + stream, +) + + +def parse_root(value: object) -> object: + tree = vt.parse(stream(value)) + return vt.plain(tree.root, tree.objects, inline=True) + + +def without_ids(value: object) -> object: + if isinstance(value, dict): + return {k: without_ids(v) for k, v in value.items() if k != "$id"} + if isinstance(value, list): + return [without_ids(v) for v in value] + return value + + +class ValueTests(unittest.TestCase): + def test_scalars_round_trip(self) -> None: + for value in (None, True, False, 0, -7, 2**31 - 1, 1.5, -0.001, "", "Pod1", "µL ≤ 1"): + with self.subTest(value=value): + self.assertEqual(parse_root(value), value) + + def test_fixed_size_codes(self) -> None: + cases = [ + (b"\x04\x2a", 42), + (b"\x05" + struct.pack(" None: + value = {"Devices": {"Pipettor1": {"Pod1": {"Name": "Pod1", "X": [1, 2.5, "three"]}}}} + self.assertEqual(without_ids(parse_root(value)), value) + paths = dict(vt.walk(without_ids(parse_root(value)))) + self.assertEqual(paths["/Devices/Pipettor1/Pod1/X[2]"], "three") + + def test_references_name_objects_defined_earlier(self) -> None: + shared = {"a": 1} + tree = vt.parse(stream([shared, vt.Ref(1)])) + self.assertIsInstance(tree.root.items[1], vt.Ref) + self.assertIs(tree.deref(tree.root.items[1]), tree.objects[1]) + plain = vt.plain(tree.root, tree.objects, inline=True) + self.assertEqual(without_ids(plain), [shared, shared]) + + def test_arrays(self) -> None: + self.assertEqual(parse_root(Array(0x03, [1, -2, 3], "i")), [1, -2, 3]) + self.assertEqual(parse_root(Array(0x05, [0.25, 2.0], "d")), [0.25, 2.0]) + self.assertEqual(parse_root(Array(0x08, ["a", "bc"])), ["a", "bc"]) + self.assertEqual(parse_root(Array(0x0C, [1, "x", None])), [1, "x", None]) + + def test_the_container_is_a_header_then_zlib(self) -> None: + data = stream({"k": "v"}) + self.assertEqual(vt.decompress(container(data)), data) + + +class ClassBodyTests(unittest.TestCase): + """The bodies of the classes besides dictionaries and lists, as `EXTENSIONS` / `OBJECTS` read + them, on bodies laid out as each reader states.""" + + @staticmethod + def extended(class_id: bytes, body: bytes) -> object: + """A dictionary with an extension of `class_id`, its body `body`, and one entry.""" + w = Writer() + data = w.define(vt.DICTIONARY) + b"\x01" + class_id + body + struct.pack(" None: + w = Writer() + body = struct.pack(" None: + w = Writer() + body = w.string("Liquid") + struct.pack(" None: + w = Writer() + pair = w.variant(Array(0x05, [0.0, 1.0], "d")) + struct.pack(" None: + plain = self.extended(vt.WORKSPACE, struct.pack("<9i", 3, *range(8))) + assert isinstance(plain, dict) + self.assertEqual(plain["$extension"], {"version": 3, "records": [[0, 1, 2, 3], [4, 5, 6, 7]]}) + w = Writer() + data = w.define(vt.PROMISE) + struct.pack("<3d", 1.0, 2.0, 3.0) + w.variant(5) + data += struct.pack(" bytes: + return struct.pack(" None: + good = stream({"a": 1}) + with self.assertRaisesRegex(vt.ParseError, "stream says"): + vt.parse(good + b"\x00") + with self.assertRaisesRegex(vt.ParseError, "left unparsed"): + vt.parse(self.body(good[4:] + b"\x01")) + with self.assertRaisesRegex(vt.ParseError, "past the end"): + vt.parse(self.body(b"\x0b" + struct.pack(" None: + with self.assertRaisesRegex(vt.ParseError, "unknown stream code"): + vt.parse(self.body(b"\x30")) + with self.assertRaisesRegex(vt.ParseError, "undefined object reference"): + vt.parse(self.body(b"\x0d" + struct.pack(" str: return "sha256:" + hashlib.sha256(text.encode("ascii")).hexdigest() +def differences(old: Any, new: Any, path: str = "") -> List[str]: + """Where two JSON values differ, one line per leaf (`pods/left/limits/X: [..] -> [..]`).""" + if isinstance(old, dict) and isinstance(new, dict): + lines = [] + for key in sorted(set(old) | set(new), key=str): + sub = f"{path}/{key}" if path else str(key) + if key not in old: + lines.append(f"{sub}: added") + elif key not in new: + lines.append(f"{sub}: removed") + else: + lines += differences(old[key], new[key], sub) + return lines + if isinstance(old, list) and isinstance(new, list) and len(old) == len(new): + return [ + line for i, (a, b) in enumerate(zip(old, new)) for line in differences(a, b, f"{path}[{i}]") + ] + return [] if old == new else [f"{path}: {old!r} -> {new!r}"] + + +@dataclass(frozen=True) +class SourcesCheck: + """How a configuration's sources compare with it now (`DeviceConfiguration.check_sources`): + `changed` lists each value that differs, `unavailable` each source that could not be found.""" + + changed: List[str] + unavailable: List[str] + + @dataclass class DeviceConfiguration: """Everything declared about one instrument: its motor tables and its pods. @@ -371,6 +402,45 @@ def pod(self, side: Side) -> PodConfiguration: raise ValueError(f"no pod declared on the {side}; declared: {sorted(self.pods)}") return self.pods[side] + @classmethod + def from_biomek( + cls, + bif: Union[str, Path], + master_controller_db: Optional[Union[str, Path]] = None, + master_controller_record: Optional[Union[str, Path]] = None, + chassis_serial_number: Optional[str] = None, + ) -> "DeviceConfiguration": + """An instrument's declared configuration, from its Biomek files: the only way one is made. + + Args: + bif: Biomek's instrument file (on the instrument's computer, + `C:\\Users\\Public\\Documents\\Biomek5\\Biomek_i7.bif`). + master_controller_db: the Master Controller's database (`C:\\ProgramData\\Beckman + Coulter\\Biomek Master Controller\\Log.db3`), read-only. + master_controller_record: instead of the database, a text file holding its instrument + record (`biomek_files.master_controller.write_record`). + chassis_serial_number: which instrument's record, when the database holds more than one. + + Raises: + ValueError: for files that do not describe one consistent instrument (see + `biomek_files.importer`). + """ + from pylabrobot.beckman_coulter.biomek_i7.biomek_files.importer import import_configuration + + return import_configuration( + bif, + master_controller_db=master_controller_db, + master_controller_record=master_controller_record, + chassis_serial_number=chassis_serial_number, + ) + + def check_sources(self) -> SourcesCheck: + """Read this configuration's sources again (read-only) and say what has changed since it was + imported, and which sources cannot be found here.""" + from pylabrobot.beckman_coulter.biomek_i7.biomek_files.importer import check_sources + + return check_sources(self) + def fingerprints(self) -> Dict[str, str]: """The fingerprint of the values taken from each source, as they are now.""" parts = source_parts(self.to_dict()) @@ -378,7 +448,7 @@ def fingerprints(self) -> Dict[str, str]: def unrecorded_changes(self) -> List[str]: """The sources whose values no longer match the fingerprints recorded at import: changed after - the file was made, by hand or otherwise.""" + the file was made, by hand or by anything but `from_biomek`.""" now = self.fingerprints() return [name for name in SOURCES if self.sources.get(name, {}).get("fingerprint") != now[name]] @@ -407,11 +477,11 @@ def scrub(value: Any) -> Any: @classmethod def load(cls, path: Union[str, Path]) -> "DeviceConfiguration": - """An instrument's declared configuration, from the file `save` wrote. + """An instrument's declared configuration, from the file `from_biomek` made and `save` wrote. Raises: ValueError: if its values no longer match the fingerprints recorded at import: it was - changed afterwards. Import it again. + changed afterwards. Make it again with `from_biomek`. """ with open(path, encoding="utf-8") as fh: config = cls.from_dict(json.load(fh)) @@ -419,7 +489,8 @@ def load(cls, path: Union[str, Path]) -> "DeviceConfiguration": if changed: raise ValueError( f"{path}: the values from {' and '.join(changed)} are not the ones imported (changed " - "after import); import it again from the instrument's Biomek files" + "after import, or not made by `DeviceConfiguration.from_biomek`); import it again from " + "the instrument's Biomek files" ) return config diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/master.py b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py index 75a257162e8..f7aeab409b6 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/master.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py @@ -56,9 +56,9 @@ def __init__( Args: serial_numbers: the ACE boards' USB serial numbers. Defaults to every ACE board attached. declared_configuration_json: path of the instrument's declared configuration (motor tables, - and per pod its conversions, limits, geometry and calibration), made from the instrument's - Biomek files. Required: the driver never falls back to another, the package's generic one - included. + and per pod its conversions, limits, geometry and calibration), as + `DeviceConfiguration.from_biomek` makes it from the instrument's Biomek files. Required: + the driver never falls back to another, the package's generic one included. boards: boards to use instead of opening USB devices: a simulated instrument (`simulator.replay_boards`). With them, the checks that tie the configuration to a real instrument (`discover`) are not made. @@ -70,7 +70,7 @@ def __init__( if declared_configuration_json is None: raise ValueError( "no declared configuration: pass `declared_configuration_json`, the instrument's own, made " - "from its Biomek files" + "by `DeviceConfiguration.from_biomek` from its Biomek files" ) self._serial_numbers = list(serial_numbers) if serial_numbers is not None else None self.declared_configuration_json = declared_configuration_json @@ -150,13 +150,17 @@ async def discover(self) -> None: place, no chassis, or a pod type other than the declared one is refused (`_check_declared_against`). - On the instrument (no `boards` given), the declared configuration must be this instrument's: - its chassis serial number and each declared pod's module serial number as the modules report - them, and not the generic one (`DeviceConfiguration.generic`). Otherwise it is refused. + On the instrument (no `boards` given), two checks follow, each refusing: + - the declared configuration must be this instrument's: its chassis serial number and each + declared pod's module serial number as the modules report them, and not the generic one + (`DeviceConfiguration.generic`); + - it must still match the Biomek files it was imported from, where they can be found + (`DeviceConfiguration.check_sources`): a re-framed deck or re-measured motors there make it + stale. Where they cannot be found (another computer), a warning says so. Raises: RuntimeError: for a board this driver cannot place, or no chassis. - ValueError: for a declared configuration that is not this instrument's. + ValueError: for a declared configuration that is not this instrument's, or is stale. """ if not self._connected: await self._open() @@ -215,9 +219,32 @@ async def discover(self) -> None: "the declared configuration is not this instrument's: " + "; ".join(mismatches) + ". Its motor tables, conversions, geometry and calibration may not fit. Pass this " - "instrument's own `declared_configuration_json`, made from its Biomek files." + "instrument's own `declared_configuration_json`, made by " + "`DeviceConfiguration.from_biomek` from its Biomek files." ) - logger.info("the declared configuration is this instrument's: serial numbers match the modules") + sources = self.declared.check_sources() + if sources.changed: + shown = sources.changed[:20] + more = len(sources.changed) - len(shown) + raise ValueError( + "the declared configuration no longer matches the Biomek files it was imported from (" + + "; ".join(shown) + + (f"; and {more} more" if more else "") + + "): the instrument was re-calibrated or re-configured since. Import it again: " + "`DeviceConfiguration.from_biomek(...).save(path)`." + ) + if sources.unavailable: + logger.warning( + "the declared configuration's sources cannot be read here (%s): whether the instrument " + "was re-calibrated since %s cannot be checked", + "; ".join(sources.unavailable), + self.declared.sources.get("instrument_file", {}).get("read_at", "it was imported"), + ) + logger.info( + "the declared configuration is this instrument's: serial numbers match the modules; " + "sources %s", + "unchanged since import" if not sources.unavailable else "partly not checked (above)", + ) async def request_serial_numbers(self) -> Dict[str, Optional[str]]: """The serial numbers the modules report: `chassis`, and `left` / `right` for each pod found. @@ -271,10 +298,16 @@ def _check_declared_against(self, types: Dict[str, str]) -> None: found or "nothing", ) - def save_configuration(self, path: str) -> None: + def save_configuration(self, path: str, indent: Optional[int] = 2) -> None: """Write the declared configuration to `path`, as loaded, for `declared_configuration_json` to - read back. Nothing found at discovery is written into it.""" - self.declared.save(path) + read back. A configuration is made only from the instrument's Biomek files + (`DeviceConfiguration.from_biomek`), so nothing found at discovery is written into it. + + Args: + path: where to write it. + indent: how far to indent the JSON, or None to write it on one line. + """ + self.declared.save(path, indent=indent) def _serial_numbers_found(self) -> Dict[str, Optional[str]]: if self.chassis is None or self.chassis.configuration is None: diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py index ea1af8ca706..f77e3888fc4 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py @@ -1,5 +1,5 @@ -"""The check that ties a declared configuration to one instrument: its serial numbers, on the -instrument's own path. The replayed generic cold start answers placeholder serial numbers, as long +"""The checks that tie a declared configuration to one instrument, on the instrument's own path: +its serial numbers, and its Biomek files still matching. The replayed generic cold start answers placeholder serial numbers, as long as real ones; a configuration copy naming them stands for that instrument's own. The instrument's path (no `boards` given) is taken with the replayed boards attached where `_open` @@ -7,10 +7,16 @@ import asyncio import dataclasses +import tempfile import unittest +from pathlib import Path from typing import Iterator, List from unittest import mock +from pylabrobot.beckman_coulter.biomek_i7.biomek_files.files_tests_support import ( + write_instrument_file, + write_record, +) from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import DeviceConfiguration @@ -26,6 +32,7 @@ sealed, ) +MASTER_LOGGER = "pylabrobot.beckman_coulter.biomek_i7.driver.master" READS = {name for name in p.COMMANDS.values() if name.startswith(("Get ", "Read ", "List "))} @@ -89,6 +96,37 @@ async def test_the_generic_configuration_is_refused(self) -> None: await self.driver(generic_configuration()).discover() +class SourcesTests(InstrumentPathTests): + """A configuration imported from Biomek files written in the test, as the instrument's own.""" + + async def asyncSetUp(self) -> None: + await super().asyncSetUp() + folder = tempfile.TemporaryDirectory() + self.addCleanup(folder.cleanup) + self.bif, self.record = Path(folder.name) / "Biomek_i7.bif", Path(folder.name) / "record.txt" + self.instrument = as_instrument(generic_configuration()) + write_instrument_file(self.instrument, self.bif) + write_record(self.instrument, self.record) + self.imported = DeviceConfiguration.from_biomek(self.bif, master_controller_record=self.record) + + async def test_matching_sources_are_accepted(self) -> None: + with self.assertNoLogs(MASTER_LOGGER, "WARNING"): + await self.driver(self.imported).discover() + + async def test_a_re_measured_hysteresis_makes_it_stale(self) -> None: + next(a for a in self.instrument.modules["span8"] if a["name"] == "Z3")["hysteresis"] = 4 + write_record(self.instrument, self.record) + with self.assertRaisesRegex(ValueError, r"no longer matches.*hysteresis: 0 -> 4.*from_biomek"): + await self.driver(self.imported).discover() + self.assertEqual(set(self.requests()) - READS, set()) + + async def test_sources_not_found_here_are_warned_about(self) -> None: + self.bif.unlink() + with self.assertLogs(MASTER_LOGGER, "WARNING") as logs: + await self.driver(self.imported).discover() + self.assertIn("cannot be read here", " ".join(logs.output)) + + class SimulationTests(unittest.IsolatedAsyncioTestCase): async def asyncSetUp(self) -> None: asyncio.get_running_loop().set_debug(False) From 687c97c346582c77ed27d40b1c46408b4a4f6b38 Mon Sep 17 00:00:00 2001 From: cmoscy <46687103+cmoscy@users.noreply.github.com> Date: Wed, 11 Nov 2026 00:21:26 -0800 Subject: [PATCH 11/11] `Biomek i7`: configuring, the interlock, faults, pause and stop `setup()` now brings the instrument up after discovery, moving nothing: the motor tables are loaded where a board has lost them, the interlock is armed and every axis enabled, in the order Biomek's Master Controller logs show. - `driver/master.py`: `initialize`, `configure`, `arm_interlock`; a fault at rest is only noted, one under power is reset with a warning, one that does not clear trips the interlock and shows ERROR; per-pod skips; `stop` stops each pod's module and trips the interlock when the driver armed it; a motor failing on its own, or the interlock tripping under the driver, trips it and shows ERROR, as the Master Controller's logs show; `pause` / `resume` (a deliberate trip with PAUSED shown, then re-arm and enable). - `driver/features/chassis.py`, `door.py`: the interlock's writes, the status display, the door (`front_cover`), which only reports. - `driver/features/pod.py`: configure, enable, axis states, positions, homed state. - `driver/simulator.py`: `SimulatedAceUSB`, each axis's state and the interlock, door and drive supply the boards of one instrument share. - `session_log.py`: a run's log lines in a file of its own, to compare with Biomek's logs. Tests: the simulated boards' rules; configure sends the Configure, interlock and I/O box requests the Master Controller sent at the recorded cold start, in its order; enabling follows its order; faults at rest, under power and stuck; the drive supply, an open door, a broken light curtain; door reports; pause / resume; a motor failing on its own; stop; the session log. --- .../beckman_coulter/biomek_i7/design.md | 12 + .../biomek_i7/driver/features/chassis.py | 68 ++- .../biomek_i7/driver/features/door.py | 58 +++ .../biomek_i7/driver/features/pod.py | 93 ++++- .../biomek_i7/driver/lifecycle_tests.py | 380 +++++++++++++++++ .../biomek_i7/driver/master.py | 387 +++++++++++++++++- .../biomek_i7/driver/recipes/__init__.py | 1 + .../biomek_i7/driver/recipes/homing.py | 19 + .../biomek_i7/driver/simulator.py | 247 ++++++++++- .../beckman_coulter/biomek_i7/session_log.py | 88 ++++ .../biomek_i7/session_log_tests.py | 49 +++ .../biomek_i7/simulation_tests_support.py | 10 +- 12 files changed, 1389 insertions(+), 23 deletions(-) create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/features/door.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/lifecycle_tests.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/recipes/__init__.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/driver/recipes/homing.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/session_log.py create mode 100644 pylabrobot/beckman_coulter/biomek_i7/session_log_tests.py diff --git a/pylabrobot/beckman_coulter/biomek_i7/design.md b/pylabrobot/beckman_coulter/biomek_i7/design.md index b119ee12e3f..a74397bc096 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/design.md +++ b/pylabrobot/beckman_coulter/biomek_i7/design.md @@ -46,3 +46,15 @@ on the instrument, discovery refuses one whose serial numbers are not the module sources have changed since. There is no switch to skip a check; the fix is to import again. A simulation with no files uses the package's generic instrument (`defaults/`), which a live session refuses. + +## The pods + +`left_x_arm` / `right_x_arm` (STAR's names) are `Pod`s, one ACE board each, on one shared X rail. A +pod's axes, head or channels and gripper are driven by one board through one position record, so the +pod keeps the shared mechanics (moves, homing, enabling, the reads, every `_unchecked_fw_*`) and its +features send through it. `driver.arm(name)` also takes Biomek's names (`1`, `"Pod1"`, `"MC_1"`). + +**I5. Safety state.** The instrument rests with the interlock tripped; the driver arms it only to +move and leaves it as it found it. `stop()` moves nothing (Biomek stops in place). `pause` / +`resume` is Biomek's whole-system pause. A fault under power is cleared by enabling, with a warning; +one that will not clear trips the interlock. The door only reports: it has no interlock of its own. diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/features/chassis.py b/pylabrobot/beckman_coulter/biomek_i7/driver/features/chassis.py index df4974fd77a..0217e61071b 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/features/chassis.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/features/chassis.py @@ -1,11 +1,12 @@ -"""The chassis module: its inputs and outputs, the legacy deck devices it lists, and the interlock's -state.""" +"""The chassis module: interlock, status display, deck I/O and the instrument's own sensors (the door +is its own feature, `door.py`, read through the chassis).""" from typing import Dict, List, Optional from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import ModuleConfiguration +from pylabrobot.beckman_coulter.biomek_i7.driver.features.door import Door from pylabrobot.beckman_coulter.biomek_i7.driver.module import ( read_analog_inputs, read_module, @@ -18,6 +19,7 @@ class Chassis: def __init__(self, board: AceBoard): self.board = board self.configuration: Optional[ModuleConfiguration] = None + self.front_cover = Door(self) async def discover(self) -> ModuleConfiguration: """Read what the chassis says about itself. Moves nothing.""" @@ -55,8 +57,9 @@ async def request_legacy_alp_devices(self) -> List[bytes]: return [payload[i : i + 2] for i in range(0, len(payload), 2)] # -- interlock ------------------------------------------------------------- - # The interlock cuts the arms' drive power when the light curtain is broken or the host trips it; - # nothing moves while it is tripped. Here it is only read. + # The interlock cuts the arms' drive power when the light curtain is broken or the host trips it + # (the door does not: see `door.py`); nothing moves while it is tripped. It can be read, tripped and re-armed; there is + # deliberately no way here to bypass it. async def request_interlock_state(self) -> p.InterlockState: """`armed` (the drives may have power) or `tripped`. Moves nothing. @@ -65,3 +68,60 @@ async def request_interlock_state(self) -> p.InterlockState: reads the state; it changes nothing. """ return p.parse_interlock_status((await self.board.send(p.get_interlock_status())).payload) + + async def prepare_interlock(self) -> None: + """Trip the interlock, ask to be told when it trips, and show READY, as before the motor tables + are loaded after a power-up.""" + await self._unchecked_fw_trip_interlock() + await self._unchecked_fw_notify_on_interlock_trip() + await self._unchecked_fw_set_status_display("ready") + + async def _io_box_write_after_configure(self) -> None: + """Send the legacy deck digital I/O box its WRITE 01, a cancel of what that box was doing: + Biomek's logs show it after every Stop Module Execution (the Master Controller stopping the + box), which in a cold start falls after the motor tables are loaded. Kept where the recorded + start sends it, so the start stays byte for byte; it has nothing to do with the light curtain.""" + await self._unchecked_fw_send_digital_io_box(b"\x02\x01") + + async def trip_interlock(self, error: bool = False) -> None: + """Cut the arms' drive power and show READY: how the Master Controller leaves the instrument + at rest (it does so at every start; the drive supply reads off in over 90% of its polls). + With `error`, show ERROR, as it does after a failed move.""" + await self._unchecked_fw_trip_interlock() + await self._unchecked_fw_set_status_display("error" if error else "ready") + + async def arm_interlock(self) -> None: + """Re-arm the interlock and show RUNNING. The light curtain must be clear. + + Raises: + RuntimeError: if the interlock does not report ARMED. + """ + state = await self._unchecked_fw_rearm_interlock() + if state[:1] != b"\x00": + raise RuntimeError( + f"the interlock did not arm (state {state.hex()}); is the light curtain clear?" + ) + await self._unchecked_fw_set_status_display("running") + + # -- firmware commands ----------------------------------------------------- + # The chassis's writes, one request each, as the Master Controller sends them. No checks and no + # bookkeeping: the public methods above decide when each is sent. + + async def _unchecked_fw_trip_interlock(self) -> None: + await self.board.send(p.trip_interlock()) + + async def _unchecked_fw_rearm_interlock(self) -> bytes: + """Re-Arm Interlock. Returns what it answers: `00` when armed.""" + return (await self.board.send(p.rearm_interlock())).payload + + async def _unchecked_fw_notify_on_interlock_trip(self) -> None: + await self.board.send(p.notify_on_interlock_trip()) + + async def _unchecked_fw_set_status_display(self, state: p.StatusDisplayState) -> None: + await self.board.send(p.set_status_display(state)) + + async def _unchecked_fw_send_digital_io_box(self, data: bytes) -> None: + await self.board.send(p.send_digital_io_box(data)) + + async def _unchecked_fw_notify_on_input_change(self, index: int, notify: bool) -> None: + await self.board.send(p.notify_on_change(p.Device.DIGITAL_INPUT, index, notify)) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/features/door.py b/pylabrobot/beckman_coulter/biomek_i7/driver/features/door.py new file mode 100644 index 00000000000..695fc5cbcaa --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/features/door.py @@ -0,0 +1,58 @@ +"""The instrument's door: STAR's `FrontCover`, and reached by its name, `driver.front_cover` / +`biomek.front_cover`. + +The door sensor is the chassis's digital input "Door Sensor": 1 closed, 0 open. The door only +reports: opening it does not trip the interlock, and Biomek arms the interlock with it open +(Biomek's logs, July to October 2026). The interlock (`chassis`) answers to the light curtain and +to the host. STAR's `enable_control` / `disable_control` have no counterpart here: the door has no +interlock to turn off. +""" + +from typing import TYPE_CHECKING, Callable, Literal + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p + +if TYPE_CHECKING: + from pylabrobot.beckman_coulter.biomek_i7.driver.features.chassis import Chassis + +DoorState = Literal["open", "closed"] +DOOR_SENSOR_INPUT = "Door Sensor" +DOOR_CLOSED = 1 + + +class Door: + """The door, read through the chassis's door sensor.""" + + def __init__(self, chassis: "Chassis"): + self._chassis = chassis + + def _input(self) -> int: + config = self._chassis._require_configuration() + for index, name in config.digital_inputs.items(): + if name == DOOR_SENSOR_INPUT: + return index + raise RuntimeError(f"the chassis has no digital input named {DOOR_SENSOR_INPUT!r}") + + async def request_state(self) -> DoorState: + """Whether the door is open or closed (STAR's `FrontCover.request_state`). Moves nothing.""" + board = self._chassis.board + reply = await board.send(p.read_input_output(p.Device.DIGITAL_INPUT, self._input())) + return "closed" if reply.payload[0] == DOOR_CLOSED else "open" + + def subscribe(self, callback: Callable[[DoorState], None]) -> Callable[[], None]: + """Call `callback` whenever the door opens or closes. Returns an unsubscribe. + + The chassis reports changes only once asked to (Notify On Digital Input Change, which the + Master Controller sends at every start and `notify_changes` sends).""" + index = self._input() + + def on_message(reply: p.Reply) -> None: + if (reply.device, reply.opcode) == p.DIGITAL_INPUT_VALUE and reply.index == index: + callback("closed" if reply.payload[:1] == bytes([DOOR_CLOSED]) else "open") + + return self._chassis.board.subscribe(on_message) + + async def notify_changes(self, notify: bool = True) -> None: + """Ask the chassis to report the door opening and closing (or, False, to stop). Moves + nothing.""" + await self._chassis._unchecked_fw_notify_on_input_change(self._input(), notify) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py b/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py index c08056a6c9a..67627737673 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py @@ -1,6 +1,7 @@ """One pod: an arm on the shared X rail, its ACE module, and the axes that module drives.""" -from typing import Dict, List, Literal, Optional, Tuple +import logging +from typing import Dict, List, Literal, Optional, Sequence, Tuple, cast from pylabrobot.beckman_coulter.biomek_i7 import units from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p @@ -14,18 +15,31 @@ read_module, ) from pylabrobot.beckman_coulter.biomek_i7.driver.motors import Axis, MotorTables +from pylabrobot.beckman_coulter.biomek_i7.driver.recipes.homing import ENABLE_ORDER, ENABLE_PREFIX + +logger = logging.getLogger(__name__) # How Biomek numbers its pods. Pod1 is the left pod and Pod2 the right on the instrument this # driver was written against; whether that holds on every build is not established. POD_NUMBERS = {"left": 1, "right": 2} COMPONENT_PREFIXES = {"multichannel": "MC", "span8": "SPAN8"} +# Get Homed State answers. 0x01 was read from every axis at a cold start, 0x00 from every axis of +# both pods after Biomek's Home All (H1, 2026-10-24). +HOMED_STATES = {0x00: "homed", 0x01: "not_homed"} + # Biomek's "Safe Height" (`GlobalMinSafeHeight`) at or below this is unset (it stores -100000). UNSET_SAFE_HEIGHT = -1000.0 # The arm board's analog input carrying the interlocked motor supply ("+36V Interlock"). DRIVE_SUPPLY_INPUT = "+36V Interlock" +# Set State ENABLED on a CiA 402 drive resets a fault, then steps the drive through shutdown, switch +# on and enable operation, waiting up to 3 s for each. Whether a board enables +# a batch one drive at a time is not known, so a batch is given that per axis; it is a bound for +# a drive that does not come up, not how long enabling takes. +ENABLE_SECONDS_PER_AXIS = 9.0 + class Pod: """One pod. Reached as `driver.left_x_arm` / `driver.right_x_arm`: it fills the slot of STAR's @@ -89,6 +103,26 @@ async def discover(self) -> ModuleConfiguration: self.configuration = await read_module(self.board) return self.configuration + async def request_positions(self) -> Dict[str, int]: + """Every axis's current position, in counts, as the drives report it.""" + replies = await self.board.send_many( + [p.get_current_position(axis.device, axis.index) for axis in self.axes] + ) + return {axis.name: p.parse_s32(r.payload) for axis, r in zip(self.axes, replies)} + + async def request_axis_states(self) -> Dict[str, p.AxisStateName]: + """Every axis's state (motors and pumps), sent together: `enabled` (it may move), `disabled` + (configured, not enabled), `not_configured` (as at power-up) or `fault`. Moves nothing. + + Raises: + ValueError: for a state byte the firmware does not set. + """ + replies = await self.board.send_many([p.get_state(a.device, a.index) for a in self.axes]) + return { + a.name: cast(p.AxisStateName, p.parse_axis_state(r.payload).name.lower()) + for a, r in zip(self.axes, replies) + } + async def request_drive_supply(self) -> float: """The pod's interlocked motor supply, in volts: about 36 with the interlock armed, about 0.1 tripped. Moves nothing. @@ -104,6 +138,13 @@ async def request_drive_supply(self) -> float: return p.parse_float(reply.payload) raise RuntimeError(f"{self} has no {DRIVE_SUPPLY_INPUT!r} analog input") + async def request_homed_state(self, axis_name: str) -> str: + """Whether an axis (a motor or a pump) has been homed: `homed`, `not_homed`, or the raw code + of a state not yet seen.""" + axis = self.axis(axis_name) + code = (await self.board.send(p.get_homed_state(axis.device, axis.index))).payload[0] + return HOMED_STATES.get(code, f"0x{code:02X}") + async def request_accuframe_offsets(self) -> Tuple[float, float, float]: """The X, Y and Z offsets the pod's AccuFrame board holds.""" return p.parse_accuframe_offsets((await self.board.send(p.get_accuframe_offsets())).payload) @@ -112,3 +153,53 @@ async def request_analog_inputs(self) -> Dict[str, float]: if self.configuration is None: raise RuntimeError(f"{self} has not been read; call `discover()` or `setup()` first") return await read_analog_inputs(self.board, self.configuration) + + # -- configuration and enabling ------------------------------------------------ + # These write to the board. Nothing in this driver calls them on its own. + + async def configure(self) -> None: + """Load every axis's motor table into the board, then Stop Module Execution, as after a + power-up. The tables come from the motor recording; the board cannot be asked for them. + + Configuring an axis that is configured is accepted, and leaves it disabled and not homed, so + this un-homes the pod.""" + logger.info("%s configure (%d axes)", self.component, len(self.axes)) + for axis in self.axes: + await self._unchecked_fw_configure(axis) + await self._unchecked_fw_stop_module_execution() + + async def enable_axes(self) -> Dict[str, int]: + """Stop motion and enable every axis, as after the interlock is armed (its drive power was + off), and read where each is, as the Master Controller resumes: each axis enabled and read. + Returns every axis's position.""" + axes = [self.axis(name) for name in ENABLE_ORDER[self.module_type]] + await self._unchecked_fw_enable(ENABLE_PREFIX[self.module_type]) + await self._unchecked_fw_stop_motion() + await self._unchecked_fw_enable(ENABLE_ORDER[self.module_type]) + replies = await self.board.send_many([p.get_current_position(a.device, a.index) for a in axes]) + return {a.name: p.parse_s32(r.payload) for a, r in zip(axes, replies)} + + # -- drive commands ---------------------------------------------------------- + # One request, or one batch sent together, each, as the Master Controller sends them. No checks + # and no bookkeeping: the public methods above decide when each is sent. + + async def _unchecked_fw_enable(self, axes: Sequence[str]) -> None: + """Set State ENABLED on each axis, sent together. On a drive in fault this is also the fault + reset; one that cannot come up answers an error and stays in fault.""" + if axes: + targets = [self.axis(name) for name in axes] + await self.board.send_many( + [p.set_state_enabled(a.device, a.index) for a in targets], + timeout=5.0 + ENABLE_SECONDS_PER_AXIS * len(targets), + ) + + async def _unchecked_fw_stop_motion(self) -> None: + """Stop Motion Service on this pod's board: stops every axis and drops pending moves.""" + await self.board.send(p.stop_motion_service()) + + async def _unchecked_fw_configure(self, axis: Axis) -> None: + """Load one axis's motor table (Configure). Leaves it disabled and not homed.""" + await self.board.send(p.configure(axis.device, axis.index, axis.configure)) + + async def _unchecked_fw_stop_module_execution(self) -> None: + await self.board.send(p.stop_module_execution()) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/lifecycle_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/lifecycle_tests.py new file mode 100644 index 00000000000..9d438edf10d --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/lifecycle_tests.py @@ -0,0 +1,380 @@ +"""Configure, the interlock, faults, pause / resume and stop, against the generic instrument +simulated: what the driver sends, and how it handles what the boards answer. Nothing here moves an +axis.""" + +import asyncio +import unittest +from typing import Any, Dict, List + +from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p +from pylabrobot.beckman_coulter.biomek_i7.driver.errors import AceError +from pylabrobot.beckman_coulter.biomek_i7.driver.master import BiomekI7Driver +from pylabrobot.beckman_coulter.biomek_i7.driver.simulator import SimulatedAceUSB +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import ( + generic_driver, + generic_recording, + generic_simulated_boards, +) + +MASTER_LOGGER = "pylabrobot.beckman_coulter.biomek_i7.driver.master" +MODULES = ("chassis", "multichannel", "span8") +READ_ONLY_SETUP = dict(skip_device_initialization=True, skip_left_x_arm=True, skip_right_x_arm=True) + + +def zero_sequence(message: bytes) -> str: + return (message[:3] + b"\x00" + message[4:]).hex() + + +def name_of(message: bytes) -> str: + return p.COMMANDS[(message[0], message[4])] + + +class SimulatedTest(unittest.IsolatedAsyncioTestCase): + """A driver on the generic instrument simulated, and what each board was sent since a mark.""" + + marks: Dict[str, int] + + async def asyncSetUp(self) -> None: + asyncio.get_running_loop().set_debug(False) # the test loop's debug mode makes runs slow + + async def start(self, homed: Any = True, configured: Any = None) -> BiomekI7Driver: + driver = generic_driver(generic_simulated_boards(homed=homed, configured=configured)) + await driver.setup(**READ_ONLY_SETUP) + self.addAsyncCleanup(driver.stop) + self.marks = {} + self.mark(driver) + return driver + + async def start_initialized(self, homed: Any = True, configured: Any = None, **flags: Any): # type: ignore[no-untyped-def] + driver = await self.start(homed, configured) + await driver.initialize(**flags) + return driver + + def usb(self, driver: BiomekI7Driver, module: str) -> SimulatedAceUSB: + for board in driver.boards: + if board.name == f"simulated {module}": + assert isinstance(board.io, SimulatedAceUSB) + return board.io + raise KeyError(module) + + def mark(self, driver: BiomekI7Driver) -> None: + for module in MODULES: + self.marks[module] = len(self.usb(driver, module).requests) + + def sent(self, driver: BiomekI7Driver, module: str) -> List[bytes]: + return self.usb(driver, module).requests[self.marks[module] :] + + def names(self, driver: BiomekI7Driver, module: str) -> List[str]: + return [name_of(m) for m in self.sent(driver, module)] + + def written(self, driver: BiomekI7Driver) -> List[str]: + """Every request since the mark that is not a read.""" + return [ + name + for module in MODULES + for name in self.names(driver, module) + if not name.startswith(("Get ", "Read ", "List ")) + ] + + async def settle(self) -> None: + """Let the boards' read loops and the driver's background writes run.""" + for _ in range(5): + await asyncio.sleep(0.02) + + +class SimulatorRuleTests(SimulatedTest): + """The simulated boards answer as the instrument's did.""" + + async def test_an_axis_is_configured_before_it_takes_a_state(self) -> None: + driver = await self.start(homed=False, configured=False) + pod = driver.left_x_arm + assert pod is not None + with self.assertRaisesRegex(AceError, "not configured"): + await pod._unchecked_fw_enable(["Y"]) + await pod._unchecked_fw_configure(pod.axis("Y")) + self.assertEqual((await pod.request_axis_states())["Y"], "disabled") + self.assertEqual(await pod.request_homed_state("Y"), "not_homed") + + async def test_at_rest_cia402_drives_are_in_fault_and_refuse_enabling(self) -> None: + driver = await self.start() + left, right = driver.left_x_arm, driver.right_x_arm + assert left is not None and right is not None + self.assertEqual(set((await left.request_axis_states()).values()), {"fault"}) + self.assertEqual((await right.request_axis_states())["Z1"], "enabled") # a SAGIAN drive + with self.assertRaisesRegex(AceError, "interlock tripped"): + await left._unchecked_fw_enable(["X"]) + self.assertLess(await left.request_drive_supply(), 1.0) + + async def test_armed_the_supply_comes_up_and_enabling_resets_a_fault(self) -> None: + driver = await self.start() + left = driver.left_x_arm + assert left is not None and driver.chassis is not None + await driver.chassis.arm_interlock() + self.assertGreater(await left.request_drive_supply(), 30.0) + await left._unchecked_fw_enable(["X"]) + self.assertEqual((await left.request_axis_states())["X"], "enabled") + self.usb(driver, "multichannel").axis_model("Y").stuck_fault = True + with self.assertRaises(AceError) as caught: + await left._unchecked_fw_enable(["Y"]) + self.assertEqual(caught.exception.code, 0x3D) + + +class InitializeTests(SimulatedTest): + async def test_only_a_board_that_lost_its_tables_is_configured(self) -> None: + driver = await self.start_initialized( + homed={"multichannel": ["X"]}, configured={"multichannel": True, "span8": False} + ) + self.assertNotIn("Configure", self.names(driver, "multichannel")) + assert driver.right_x_arm is not None + self.assertEqual(self.names(driver, "span8").count("Configure"), len(driver.right_x_arm.axes)) + self.assertEqual( + self.names(driver, "chassis")[:3], + ["Trip Interlock", "Notify On Interlock Trip", "Set Status Display"], + ) + states = await driver.request_axis_states() + self.assertEqual({s for pod in states.values() for s in pod.values()}, {"enabled"}) + + async def test_configure_sends_what_the_recorded_cold_start_sent(self) -> None: + """Each pod's Configure requests, and the chassis's interlock requests before them and the + I/O box write after, are the ones the Master Controller sent at the cold start the generic + recording comes from, in its order.""" + driver = await self.start(homed=False, configured=False) + await driver.configure() + recording = generic_recording()["boards"] + for module in ("multichannel", "span8"): + recorded = [ + key for key, _ in recording[module] if key[6:8] == "10" and key[:2] in ("11", "12") + ] + sent = [(m[:3] + m[4:]).hex() for m in self.sent(driver, module) if name_of(m) == "Configure"] + self.assertEqual(sent, recorded, module) + self.assertEqual(self.names(driver, module)[-1], "Stop Module Execution") + chassis = [(m[:3] + m[4:]).hex() for m in self.sent(driver, "chassis")] + recorded_keys = {key for key, _ in recording["chassis"]} + self.assertEqual( + self.names(driver, "chassis"), + ["Trip Interlock", "Notify On Interlock Trip", "Set Status Display", "Send Digital I/O Box"], + ) + self.assertTrue(set(chassis) <= recorded_keys, set(chassis) - recorded_keys) + + async def test_drives_at_rest_are_in_fault_and_enabling_clears_it(self) -> None: + driver = await self.start() + with self.assertLogs(MASTER_LOGGER, "INFO") as logs: + await driver.initialize() + self.assertTrue(any("as at rest" in line for line in logs.output)) + self.assertFalse(any("collision" in line for line in logs.output)) + self.assertNotIn("Configure", self.written(driver)) + states = await driver.request_axis_states() + self.assertEqual({s for pod in states.values() for s in pod.values()}, {"enabled"}) + self.assertFalse(driver.interlock_tripped.is_set()) + + async def test_enabling_follows_the_master_controllers_order(self) -> None: + driver = await self.start() + await driver.arm_interlock() + left = [m for m in self.sent(driver, "multichannel") if name_of(m) == "Set State"] + assert driver.left_x_arm is not None + names = {(a.device, a.index): a.name for a in driver.left_x_arm.axes} + self.assertEqual( + [names[(m[0], m[1])] for m in left], ["Z", "GZ", "GR", "GY", "GG", "Z", "D", "X", "Y"] + ) + + async def test_a_fault_under_power_is_reset_with_a_warning(self) -> None: + driver = await self.start() + usb = self.usb(driver, "multichannel") + usb.interlock.armed = True # left armed, by an earlier session + for model in usb.axes.values(): + model.state = p.AxisState.ENABLED + usb.axis_model("Z").state = p.AxisState.FAULT + with self.assertLogs(MASTER_LOGGER, "WARNING") as logs: + await driver.initialize() + self.assertTrue(any(": Z in fault" in line and "collision" in line for line in logs.output)) + self.assertEqual(usb.axis_model("Z").state, p.AxisState.ENABLED) + + async def test_a_sagian_fault_is_warned_about_even_at_rest(self) -> None: + driver = await self.start() + self.usb(driver, "span8").axis_model("Z3").state = p.AxisState.FAULT + with self.assertLogs(MASTER_LOGGER, "WARNING") as logs: + await driver.initialize() + self.assertTrue(any("Z3" in line and "collision" in line for line in logs.output)) + + async def test_a_fault_that_does_not_clear_returns_the_instrument_to_rest(self) -> None: + driver = await self.start() + self.usb(driver, "multichannel").axis_model("Z").stuck_fault = True + with self.assertRaises(AceError): + await driver.initialize() + chassis = self.sent(driver, "chassis") + self.assertEqual([name_of(m) for m in chassis[-2:]], ["Trip Interlock", "Set Status Display"]) + self.assertEqual( + zero_sequence(chassis[-1]), zero_sequence(p.set_status_display("error").encode(1)) + ) + self.assertFalse(self.usb(driver, "chassis").interlock.armed) + self.assertTrue(driver.interlock_tripped.is_set()) + + async def test_a_drive_supply_that_stays_off_stops_it_before_enabling(self) -> None: + driver = await self.start() + self.usb(driver, "chassis").interlock.supply_comes_up = False + with self.assertRaisesRegex(RuntimeError, "drive supply"): + await driver.initialize() + self.assertNotIn("Set State", self.written(driver)) + self.assertFalse(self.usb(driver, "chassis").interlock.armed) + + async def test_an_open_door_does_not_stop_it(self) -> None: + driver = await self.start() + chassis_usb = self.usb(driver, "chassis") + chassis_usb.interlock.door_open = True + assert driver.chassis and driver.front_cover + self.assertEqual(await driver.front_cover.request_state(), "open") + await driver.initialize() # Biomek arms with the door open + self.assertEqual(await driver.chassis.request_interlock_state(), "armed") + + async def test_a_broken_light_curtain_stops_it(self) -> None: + driver = await self.start() + chassis_usb = self.usb(driver, "chassis") + chassis_usb.interlock.light_curtain_broken = True + with self.assertRaisesRegex(RuntimeError, "light curtain"): + await driver.initialize() + self.assertFalse(chassis_usb.interlock.armed) + + async def test_door_changes_are_reported_and_the_light_curtain_trips_the_interlock(self) -> None: + driver = await self.start_initialized() + assert driver.chassis and driver.front_cover + await driver.front_cover.notify_changes() + seen: List[str] = [] + driver.front_cover.subscribe(seen.append) + chassis_usb = self.usb(driver, "chassis") + chassis_usb.set_door(True) + await self.settle() + self.assertEqual(seen, ["open"]) + self.assertEqual(await driver.chassis.request_interlock_state(), "armed") + chassis_usb.set_door(False) + await self.settle() + self.assertEqual(seen, ["open", "closed"]) + with self.assertLogs(MASTER_LOGGER, "ERROR") as logs: + chassis_usb.set_light_curtain(True) + await self.settle() + self.assertIn("light curtain violation", "\n".join(logs.output)) + self.assertEqual(await driver.chassis.request_interlock_state(), "tripped") + self.assertTrue(driver.interlock_tripped.is_set()) + self.assertEqual( + zero_sequence(self.sent(driver, "chassis")[-2]), + zero_sequence(p.set_status_display("error").encode(1)), + ) + + async def test_skipping_configuration_leaves_unconfigured_pods_alone(self) -> None: + driver = await self.start(homed=False, configured=False) + await driver.initialize(skip_device_initialization=True) + self.assertEqual(self.written(driver), []) + + async def test_a_skipped_pod_is_left_alone(self) -> None: + driver = await self.start_initialized(skip_right_x_arm=True) + self.assertEqual([n for n in self.names(driver, "span8") if not n.startswith("Get ")], []) + self.assertIn("Set State", self.names(driver, "multichannel")) + + async def test_setup_brings_the_instrument_up_and_is_repeatable(self) -> None: + driver = generic_driver(generic_simulated_boards(homed=False)) + self.addAsyncCleanup(driver.stop) + await driver.setup() + states = await driver.request_axis_states() + self.assertEqual({s for pod in states.values() for s in pod.values()}, {"enabled"}) + await driver.setup() # configured already: not configured again + states = await driver.request_axis_states() + self.assertEqual({s for pod in states.values() for s in pod.values()}, {"enabled"}) + + +class PauseTests(SimulatedTest): + async def test_pause_trips_and_shows_paused_and_resume_re_arms(self) -> None: + driver = await self.start_initialized() + chassis_usb = self.usb(driver, "chassis") + self.mark(driver) + await driver.pause() + self.assertTrue(driver.paused) + self.assertFalse(chassis_usb.interlock.armed) + self.assertTrue(driver.interlock_tripped.is_set()) + self.assertEqual( + [zero_sequence(m) for m in self.sent(driver, "chassis")], + [ + zero_sequence(p.trip_interlock().encode(1)), + zero_sequence(p.set_status_display("paused").encode(1)), + ], + ) + with self.assertRaisesRegex(RuntimeError, "already paused"): + await driver.pause() + await driver.resume() + self.assertFalse(driver.paused) + self.assertTrue(chassis_usb.interlock.armed) + self.assertFalse(driver.interlock_tripped.is_set()) + states = await driver.request_axis_states() + self.assertEqual({s for pod in states.values() for s in pod.values()}, {"enabled"}) + + async def test_a_pause_is_not_an_error(self) -> None: + driver = await self.start_initialized() + with self.assertNoLogs(MASTER_LOGGER, "ERROR"): + await driver.pause() + await self.settle() + + async def test_a_broken_light_curtain_keeps_it_paused(self) -> None: + driver = await self.start_initialized() + chassis_usb = self.usb(driver, "chassis") + await driver.pause() + chassis_usb.set_light_curtain(True) + with self.assertRaisesRegex(RuntimeError, "light curtain"): + await driver.resume() + self.assertTrue(driver.paused) + self.assertFalse(chassis_usb.interlock.armed) + chassis_usb.set_light_curtain(False) + await driver.resume() + self.assertFalse(driver.paused) + self.assertTrue(chassis_usb.interlock.armed) + + async def test_pause_needs_an_armed_interlock(self) -> None: + driver = await self.start() + with self.assertRaisesRegex(RuntimeError, "not armed"): + await driver.pause() + with self.assertRaisesRegex(RuntimeError, "not paused"): + await driver.resume() + + +class FaultAndStopTests(SimulatedTest): + async def test_a_motor_failing_on_its_own_trips_the_interlock(self) -> None: + driver = await self.start_initialized() + assert driver.left_x_arm is not None + x = driver.left_x_arm.axis("X") + self.mark(driver) + with self.assertLogs(MASTER_LOGGER, "ERROR") as logs: + # A Move All's NOTICE for X with a following error, sequence 0: nobody asked. + self.usb(driver, "multichannel")._queue(bytes([x.device, x.index, 0, 0, 0x50, 0xFE, 0x3C])) + await self.settle() + self.assertIn("The left X motor failed", "\n".join(logs.output)) + self.assertEqual(self.names(driver, "chassis"), ["Trip Interlock", "Set Status Display"]) + self.assertEqual(self.sent(driver, "chassis")[1][5:], p.set_status_display("error").params) + self.assertTrue(driver.interlock_tripped.is_set()) + + async def test_a_trip_the_driver_made_is_not_an_error(self) -> None: + driver = await self.start_initialized() + self.mark(driver) + with self.assertNoLogs(MASTER_LOGGER, "ERROR"): + await driver.stop() + # The chassis's own trip event, after the driver's trip. + self.usb(driver, "chassis")._queue(bytes([p.Device.INTERLOCK, 1, 0, 0, 0x10, 0x03, 0, 0xFF])) + await self.settle() + + async def test_stop_leaves_the_instrument_at_rest(self) -> None: + driver = await self.start() + await driver.stop() # never armed: nothing is sent + self.assertEqual(self.written(driver), []) + driver = await self.start_initialized() + self.mark(driver) + await driver.stop() + for module in ("multichannel", "span8"): + self.assertEqual(self.names(driver, module), ["Stop Module Execution"]) + self.assertEqual( + [zero_sequence(m) for m in self.sent(driver, "chassis")], + [ + zero_sequence(p.trip_interlock().encode(1)), + zero_sequence(p.set_status_display("ready").encode(1)), + ], + ) + self.assertFalse(self.usb(driver, "chassis").interlock.armed) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/master.py b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py index f7aeab409b6..75859505457 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/master.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py @@ -4,10 +4,19 @@ is not fixed by USB order or serial number, so setup opens every ACE device, asks each its module ID (its type, and an arm's side), and builds the chassis and a pod per arm from the answers. Only one program can hold an ACE board at a time: Biomek's Master Controller must not be running. + +At rest the interlock is tripped: the arms' drives have no motor power, and every CiA 402 drive +reads FAULT. That is how the Master Controller leaves the instrument (its drive supply polls read +off over 90% of the time), so it is not an error here. Bringing the instrument up arms the +interlock and enables every axis, which is each faulted drive's reset, as Biomek does; a fault +that does not clear stops it before anything moves. When anything fails once the interlock is +armed, the driver shows ERROR and trips the interlock; `stop` trips it too, as the Master +Controller's logs show it doing. """ +import asyncio import logging -from typing import Dict, List, Optional, Sequence, Tuple, Union +from typing import Awaitable, Callable, Dict, Iterable, List, Optional, Sequence, Set, Tuple, Union from pylabrobot.beckman_coulter.biomek_i7.driver import protocol as p from pylabrobot.beckman_coulter.biomek_i7.driver.board import ( @@ -19,12 +28,34 @@ DeviceConfiguration, ModuleConfiguration, ) +from pylabrobot.beckman_coulter.biomek_i7.driver.errors import INTERLOCK_TRIPPED_CODE, ace_error from pylabrobot.beckman_coulter.biomek_i7.driver.features.chassis import Chassis +from pylabrobot.beckman_coulter.biomek_i7.driver.features.door import Door from pylabrobot.beckman_coulter.biomek_i7.driver.features.pod import Pod from pylabrobot.io.usb import USB logger = logging.getLogger(__name__) +# A pod's drive supply ("+36V Interlock") reads about 35-36 V with the interlock armed and 0.1-0.16 +# V tripped (Master Controller polls, 2026-07 to 10). Above this it counts as on. +DRIVE_SUPPLY_ON_VOLTS = 30.0 + +# How long returning to rest may take, in seconds: two requests to the chassis. +REST_TIMEOUT = 5.0 + + +async def _together(aws: Iterable[Awaitable[object]]) -> None: + """Run the pods' work at once. If one fails, the others are cancelled and waited for before the + error is raised, so nothing is left sending to a board behind the caller's back.""" + tasks = [asyncio.ensure_future(a) for a in aws] + try: + await asyncio.gather(*tasks) + except BaseException: + for task in tasks: + task.cancel() + await asyncio.gather(*tasks, return_exceptions=True) + raise + def find_ace_boards() -> Dict[str, int]: """Every ACE board attached: its USB serial number and current USB address. @@ -90,6 +121,15 @@ def __init__( self._given_boards = list(boards) if boards is not None else None self.boards: List[AceBoard] = [] self._connected = False + self._armed = False # this driver armed the interlock, and has not tripped it since + self._tripping = False # this driver is tripping it: the chassis's trip event is our own + self._paused = False # paused (`pause`), waiting for `resume` + # Set while the interlock is tripped as far as this driver knows: from the start, when the + # chassis reports a trip, or when this driver trips it; cleared when it arms it. + self.interlock_tripped = asyncio.Event() + self.interlock_tripped.set() + self._unwatch: List[Callable[[], None]] = [] + self._background: Set["asyncio.Task[None]"] = set() self.chassis: Optional[Chassis] = None # The pods, named as STAR names its X-arms: each fills an X-arm's slot (design.md, Feature map). self.left_x_arm: Optional[Pod] = None @@ -97,23 +137,45 @@ def __init__( # -- lifecycle ------------------------------------------------------------- - async def setup(self) -> None: - """Connect to the instrument and find out what it is. Reads only: nothing is written to a - board and nothing moves. Repeatable: the boards stay open, and discovery reads them again. A - setup that fails part way releases the boards. + async def setup( + self, + skip_device_initialization: bool = False, + *, + skip_left_x_arm: bool = False, + skip_right_x_arm: bool = False, + ) -> None: + """Connect to the instrument, find out what it is, and bring it up. + + `discover` is the read-only part; then the motor tables are loaded where a board has lost them, + the interlock is armed and every axis enabled. Nothing moves: the drives hold where they stand. + With every skip below set, setup only reads. Repeatable: the boards stay open and discovery + reads them again. A setup that fails part way releases the boards. + + Args: + skip_device_initialization: do not load motor tables, even into a board that has lost them. + A pod with an axis not configured is then left as it is. + skip_left_x_arm: leave the left pod as it is: not configured or enabled. + skip_right_x_arm: leave the right pod as it is. Raises: - RuntimeError: if no chassis is found, or a board cannot be placed (`discover`). + RuntimeError: if no chassis is found, a board cannot be placed (`discover`), or the + interlock or a drive supply does not come up. ValueError: for a declared configuration that is not this instrument's (`discover`). + AceError: if an axis cannot be enabled; the interlock is then tripped and ERROR shown. """ logger.warning( - "The Biomek i7 driver's discovery has run on one instrument; it is untested on other " - "instruments. Please report what works and what does not." + "The Biomek i7 driver's discovery, configuration and interlock have run on one instrument; " + "they are untested on other instruments. Please report what works and what does not." ) if not self._connected: await self._open() try: await self.discover() + await self.initialize( + skip_device_initialization=skip_device_initialization, + skip_left_x_arm=skip_left_x_arm, + skip_right_x_arm=skip_right_x_arm, + ) except BaseException: await self.stop() raise @@ -199,6 +261,7 @@ async def discover(self) -> None: if "right" in places else None ) + self._watch_faults() modules: List[Tuple[str, ModuleConfiguration]] = [("chassis", await self.chassis.discover())] for pod in self.arms: modules.append((str(pod), await pod.discover())) @@ -318,7 +381,23 @@ def _serial_numbers_found(self) -> Dict[str, Optional[str]]: return found async def stop(self) -> None: - """Release every board. Writes nothing and moves nothing.""" + """Return the instrument to rest and release every board. Moves nothing. + + If this driver armed the interlock, as the Master Controller does when its host goes away: each + pod's module is stopped (Stop Module Execution), then the interlock is tripped and READY shown. + Otherwise nothing is written. What the boards do on their own when the host goes away is not + known. + """ + if self._armed: + for pod in self.arms: + try: + await asyncio.wait_for(pod._unchecked_fw_stop_module_execution(), REST_TIMEOUT) + except BaseException: + logger.exception("could not stop %s", pod) + await self._return_to_rest() + for unwatch in self._unwatch: + unwatch() + self._unwatch = [] for board in self.boards: try: await board.stop() @@ -365,3 +444,293 @@ def arm(self, name: Union[str, int]) -> Pod: if name in (pod.side, pod.pod_number, f"Pod{pod.pod_number}", pod.component): return pod raise KeyError(f"no pod {name!r}; have {[(p.side, p.component) for p in self.arms]}") + + @property + def front_cover(self) -> Optional[Door]: + """The door, by STAR's name for it, once discovery has found the chassis.""" + return None if self.chassis is None else self.chassis.front_cover + + async def request_axis_states(self) -> Dict[str, Dict[str, p.AxisStateName]]: + """Every axis's state, by pod side then axis name. Moves nothing.""" + return {pod.side: await pod.request_axis_states() for pod in self.arms} + + # -- configuration and interlock ------------------------------------------------ + # These write to the boards. Run them only on a clear deck, with someone at the emergency stop. + + def _require_chassis(self) -> Chassis: + if self.chassis is None: + raise RuntimeError("no chassis; call `setup()` first") + return self.chassis + + def skipped_sides( + self, *, skip_left_x_arm: bool = False, skip_right_x_arm: bool = False + ) -> Set[str]: + """The sides (`"left"`, `"right"`) a setup with these skips leaves as they are.""" + return {s for s, skip in (("left", skip_left_x_arm), ("right", skip_right_x_arm)) if skip} + + async def initialize( + self, + skip_device_initialization: bool = False, + *, + skip_left_x_arm: bool = False, + skip_right_x_arm: bool = False, + ) -> None: + """Bring the instrument up: what `setup` does after discovery. + + Reads every axis's state first. A pod with an axis not configured (the board was powered up, or + a drive lost its parameters) has its motor tables loaded; one fully configured does not, since + loading them again would un-home it. Then the interlock is armed and every axis enabled + (`arm_interlock`). The arguments are those of `setup`. + + An axis in fault is not refused: enabling it is its fault reset, as when Biomek re-arms and + enables after a fault, and calling this is the person's go-ahead that Biomek waits for. A CiA + 402 drive in fault with its motor supply off is the instrument at rest and is only noted; any + other fault is warned about, since under power it usually means a following error or a + collision. A fault that does not clear fails the enable, and the instrument is returned to rest. + + Raises: + RuntimeError: if the interlock or a drive supply does not come up when armed. + AceError: if an axis cannot be enabled; the interlock is then tripped and ERROR shown. + """ + skipped = self.skipped_sides(skip_left_x_arm=skip_left_x_arm, skip_right_x_arm=skip_right_x_arm) + pods = [pod for pod in self.arms if pod.side not in skipped] + if skip_device_initialization and not pods: + return + + states = await self.request_axis_states() + for pod in pods: + faulted = [name for name, state in states[pod.side].items() if state == "fault"] + if not faulted: + continue + supply = await pod.request_drive_supply() + at_rest = supply < DRIVE_SUPPLY_ON_VOLTS and all( + pod.axis(name).drive == "cia402" for name in faulted + ) + if at_rest: + logger.info("%s: %s in fault with the drive supply off (%.1f V), as at rest", pod, + ", ".join(faulted), supply) # fmt: skip + else: + positions = await pod.request_positions() + logger.warning( + "%s: %s in fault with the drive supply at %.1f V; enabling will reset them. A fault under " + "power usually means a following error or a collision: check the deck. Positions: %s", + pod, + ", ".join(faulted), + supply, + {name: positions[name] for name in faulted}, + ) + + unconfigured = [pod for pod in pods if "not_configured" in states[pod.side].values()] + if unconfigured and skip_device_initialization: + logger.warning( + "%s not configured, and configuring was skipped; left as they are, and they cannot move", + ", ".join(str(pod) for pod in unconfigured), + ) + pods = [pod for pod in pods if pod not in unconfigured] + unconfigured = [] + if unconfigured: + await self.configure(unconfigured) + if pods: + try: + await self.arm_interlock(pods) + except BaseException: + await self._return_to_rest(error=True) + raise + + # A pod that answered every request is not a pod that came up, so each is asked again. + states = await self.request_axis_states() + down = [ + f"{pod.side} {name} ({state})" + for pod in pods + for name, state in states[pod.side].items() + if state != "enabled" + ] + if down: + logger.warning("initialize finished with these axes not enabled: %s", ", ".join(down)) + + async def configure(self, pods: Optional[Sequence[Pod]] = None) -> None: + """Load the motor tables into pods' boards (every pod by default), as after a power-up. Moves + nothing. + + A board keeps its tables until it loses power. Loading them into a configured board is + accepted, and leaves every axis disabled and not homed, so this un-homes + the pods; `initialize` loads them only where an axis is not configured. + """ + chassis = self._require_chassis() + await chassis.prepare_interlock() + for pod in self.arms if pods is None else pods: + await pod.configure() + await chassis._io_box_write_after_configure() + + async def arm_interlock(self, pods: Optional[Sequence[Pod]] = None) -> None: + """Arm the interlock, check the pods' drive supply came up, then enable every axis of pods + (every pod by default). Enabling resets a drive's fault. Moves nothing: the drives hold where + they stand. + + The door does not take part: Biomek arms with it open, and opening it does not trip the + interlock (Biomek's logs); only its state is logged. + + Raises: + RuntimeError: if the interlock does not arm (the light curtain broken), or a pod's drive + supply stays off. + AceError: if an axis cannot be enabled. + """ + targets = self.arms if pods is None else list(pods) + chassis = self._require_chassis() + if await chassis.front_cover.request_state() == "open": + logger.info("arming the interlock with the door open (the door does not trip it)") + self._armed = True # before the request: a re-arm that times out may still have armed it + self.interlock_tripped.clear() + await chassis.arm_interlock() + state = await chassis.request_interlock_state() + if state != "armed": + raise RuntimeError(f"the interlock reads {state} after re-arming") + for pod in targets: + supply = await pod.request_drive_supply() + if supply < DRIVE_SUPPLY_ON_VOLTS: + raise RuntimeError(f"{pod}: the drive supply reads {supply:.1f} V with the interlock armed") + await _together(pod.enable_axes() for pod in targets) + + async def _return_to_rest(self, error: bool = False) -> None: + """Trip the interlock, if this driver armed it, and show READY (ERROR with `error`). Never + raises: it runs on the way out of a failure.""" + if not self._armed: + return + await self._trip(error) + + async def _trip(self, error: bool) -> None: + """Trip the interlock and show READY or ERROR. Never raises.""" + if self.chassis is None: + return + self._tripping = True + try: + await asyncio.wait_for(self.chassis.trip_interlock(error=error), REST_TIMEOUT) + self._armed = False + self.interlock_tripped.set() + except BaseException: + logger.exception( + "could not trip the interlock; the drives may still be powered: use the E-stop" + ) + finally: + self._tripping = False + + # -- pause for access -------------------------------------------------------------- + # Biomek's whole-system pause, as its logs show it: a deliberate interlock trip with PAUSED shown; + # resuming re-arms and enables every axis. There is no mute: the light curtain may be broken only + # because the drives have no power. + + @property + def paused(self) -> bool: + """Whether the instrument is paused (`pause`), waiting for `resume`.""" + return self._paused + + async def pause(self) -> None: + """Pause for access: cut the pods' drive power and show PAUSED, so the light curtain may be + broken without an error. Call it between operations, as Biomek's Pause step runs between + steps. + + Raises: + RuntimeError: if the interlock is not armed by this driver (nothing to pause), or the + instrument is already paused. + """ + if self._paused: + raise RuntimeError("the instrument is already paused") + if not self._armed: + raise RuntimeError("the interlock is not armed: nothing to pause") + chassis = self._require_chassis() + self._tripping = True + try: + await chassis._unchecked_fw_trip_interlock() + self._armed = False + self.interlock_tripped.set() + finally: + self._tripping = False + await chassis._unchecked_fw_set_status_display("paused") + self._paused = True + logger.info("paused: the interlock is tripped; the light curtain may be broken") + + async def resume(self) -> None: + """Resume after `pause`: re-arm the interlock and enable every axis. Nothing is homed. + + Raises: + RuntimeError: if not paused, or if the interlock does not arm (the light curtain still + broken): the instrument stays paused, so clear it and call `resume` again. + """ + if not self._paused: + raise RuntimeError("the instrument is not paused") + try: + await self.arm_interlock() + except BaseException: + self._armed = False + self.interlock_tripped.set() + raise + self._paused = False + logger.info("resumed: the interlock is armed") + + # -- faults the boards report unasked ------------------------------------------ + # As the Master Controller handles them, as its logs show it. + + def _watch_faults(self) -> None: + """Listen for the chassis reporting the interlock tripped and the pods reporting a motor that + failed on its own (both arrive unasked, sequence 0).""" + for unwatch in self._unwatch: + unwatch() + self._unwatch = [] + if self.chassis is not None: + self._unwatch.append(self.chassis.board.subscribe(self._on_chassis_message)) + for pod in self.arms: + self._unwatch.append(pod.board.subscribe(self._pod_watcher(pod))) + + def _pod_watcher(self, pod: Pod) -> Callable[[p.Reply], None]: + return lambda reply: self._on_pod_message(pod, reply) + + def _on_chassis_message(self, reply: p.Reply) -> None: + """The interlock tripped (Notify On Interlock Trip): the light curtain broken, or a trip by + the host.""" + if reply.status == p.Status.EVENT and (reply.device, reply.opcode) == p.INTERLOCK_TRIPPED: + self._interlock_tripped("A light curtain violation has occurred.") + + def _on_pod_message(self, pod: Pod, reply: p.Reply) -> None: + """A motor's Move All ended in an error nobody was waiting for: the Master Controller trips + the interlock with "The motor failed: ." (an interlock trip itself is + reported by the chassis instead).""" + if not ( + reply.opcode == 0x50 + and reply.status == p.Status.NOTICE + and reply.device in (p.Device.MOTOR, p.Device.PUMP) + and reply.error_code is not None + and reply.error_code != INTERLOCK_TRIPPED_CODE + ): + return + names = {(a.device, a.index): a.name for a in pod.axes} + axis = names.get((reply.device, reply.index), f"device 0x{reply.device:02X} {reply.index}") + error = ace_error(reply.error_code, reply.device_error, f"{pod} {axis}") + logger.error("The %s %s motor failed: %s.", pod.side, axis, error) + self.interlock_tripped.set() + self._in_background(self._trip(error=True)) + + def _interlock_tripped(self, reason: str) -> None: + """What the Master Controller does when the interlock trips under a running instrument: waits + end, and ERROR is shown. A trip this driver made itself (at rest, or after a failure) only marks + it tripped.""" + ours = self._tripping or not self._armed + self.interlock_tripped.set() + if ours: + return + logger.error("the interlock tripped: %s", reason) + self._armed = False + if self.chassis is not None: + self._in_background(self.chassis._unchecked_fw_set_status_display("error")) + + def _in_background(self, coroutine: Awaitable[None]) -> None: + """Run a board write from a message handler, which cannot wait; its failure is logged.""" + + async def run() -> None: + try: + await coroutine + except Exception: + logger.exception("after a fault the boards reported") + + task = asyncio.get_running_loop().create_task(run()) + self._background.add(task) + task.add_done_callback(self._background.discard) diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/recipes/__init__.py b/pylabrobot/beckman_coulter/biomek_i7/driver/recipes/__init__.py new file mode 100644 index 00000000000..e338b229eab --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/recipes/__init__.py @@ -0,0 +1 @@ +"""The Master Controller's multi-step host commands, as the pods run them: `homing.py`.""" diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/recipes/homing.py b/pylabrobot/beckman_coulter/biomek_i7/driver/recipes/homing.py new file mode 100644 index 00000000000..028126699fc --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/recipes/homing.py @@ -0,0 +1,19 @@ +"""Bringing a pod's axes up, as the Master Controller does it. + +Enabling (after the interlock is armed, or a fault): the Master Controller enables a pod's axes in a +fixed order, and on the Multichannel first its Z alone, then stops motion; this order, as its logs +show it, is what `Pod.enable_axes` sends. +""" + +from typing import Dict, Tuple + +# The order the Master Controller enables every axis in after the interlock is armed, and reads +# their positions in. The Multichannel board is sent one Z enable first. +ENABLE_ORDER: Dict[str, Tuple[str, ...]] = { + "multichannel": ("GZ", "GR", "GY", "GG", "Z", "D", "X", "Y"), + "span8": ( + "GR", "GG", "GZ", "D8", "GY", "D6", "D7", "D4", "D5", "D2", "D3", "Z8", "D1", "Z6", "Z7", + "Z4", "Z5", "Z2", "Z3", "Y8", "Z1", "Y6", "Y7", "Y4", "Y5", "Y2", "Y3", "X", "Y1", + ), +} # fmt: skip +ENABLE_PREFIX: Dict[str, Tuple[str, ...]] = {"multichannel": ("Z",), "span8": ()} diff --git a/pylabrobot/beckman_coulter/biomek_i7/driver/simulator.py b/pylabrobot/beckman_coulter/biomek_i7/driver/simulator.py index 357375452b9..274a0a74f41 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/driver/simulator.py +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/simulator.py @@ -1,26 +1,34 @@ -"""Simulated boards: boards that answer from what a real Biomek i7's boards answered. +"""Simulated instruments: boards that answer from what a real Biomek i7's boards answered. -`ReplayAceUSB` replays a recording; nothing it does reaches a USB device. A replayed board holds a -recording of request -> replies, keyed on everything in a request but its sequence number, and -answers a request it has a recording for with those replies under the request's sequence number. -A request it has no recording for gets no answer, as a board that ignored it would, and is kept in -`unanswered`. +`ReplayAceUSB` only replays a recording. `SimulatedAceUSB` also models each axis's state and the +interlock, so configuring, arming and enabling can run against it; nothing it does reaches a USB +device. + +A replayed board holds a recording of request -> replies, keyed on everything in a request +but its sequence number, and answers a request it has a recording for with those replies under +the request's sequence number. A request it has no recording for gets no answer, as a board that +ignored it would, and is kept in `unanswered`. """ import asyncio import gzip import json import os +import struct +from dataclasses import dataclass from pathlib import Path -from typing import Any, Dict, List, Optional, Union +from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard from pylabrobot.beckman_coulter.biomek_i7.driver.framing import frame, split +from pylabrobot.beckman_coulter.biomek_i7.driver.motors import Axis, MotorTables +from pylabrobot.beckman_coulter.biomek_i7.driver.protocol import AxisState, Device from pylabrobot.io.usb import USB # Names the recording the simulator answers from (identity and sensor reads, recorded at an # instrument's cold start) when no path is given. A generic one ships in `defaults/` -# (`biomek_i7_generic_coldstart.json`). +# (`biomek_i7_generic_coldstart.json`), which `BiomekI7(simulation=True)` uses when neither is +# given. RECORDING_ENV = "BIOMEK_I7_SIMULATOR_RECORDING" @@ -101,3 +109,226 @@ def replay_boards( ) for module, entries in data["boards"].items() ] + + +class SimulatedAceUSB(ReplayAceUSB): + """One board's USB link, answered from a model of its axes rather than only a recording. + + Each axis has a state (`AxisState`), is homed or not, and has a position, by the boards' rules: + an axis starts not configured; Configure leaves it disabled and not homed; Set State is refused + "not configured" before that. Identity and sensor reads are answered from the recording. + + The boards of one instrument share an `Interlock`. While it is tripped, as at rest, a CiA 402 + axis that was enabled reads FAULT (its drive lost motor power: H1, 2026-10-27; one configured at + rest reads DISABLED, as on H2 the same day), its enable fails, and the arm's drive supply + input reads 0.12 V; armed, 35.4 V. + Enabling a CiA 402 axis in fault resets it, unless it was given a fault that + does not clear (`_AxisModel.stuck_fault`). The error codes of a failed enable are not known; the + model answers "interlock tripped" without power and 0x3D for a stuck fault. + """ + + def __init__( + self, + recording: Dict[str, List[str]], + axes: Sequence[Axis] = (), + homed: Iterable[str] = (), + name: str = "simulated ACE board", + configured: bool = False, + interlock: Optional["Interlock"] = None, + supply_input: Optional[int] = None, + door_input: Optional[int] = None, + ): + super().__init__(recording, name=name) + self.door_input = door_input + homed = set(homed) + if homed and not configured: + raise ValueError("an axis cannot be homed on a board that is not configured") + self.interlock = interlock or Interlock() + self.supply_input = supply_input + self.axes: Dict[Tuple[int, int], _AxisModel] = {} + for a in axes: + # At rest a configured instrument's SAGIAN axes read ENABLED, as on 2026-10-27; CiA 402 + # axes read FAULT while the interlock is tripped (`_apply_power`). + state = AxisState.ENABLED if configured else AxisState.NOT_CONFIGURED + self.axes[(a.device, a.index)] = _AxisModel(a.name, a.name in homed, state, a.drive) + + def _apply_power(self) -> None: + """An enabled CiA 402 drive faults when its motor power goes. One configured with the power + already off stays DISABLED (H2, 2026-10-27: every axis read DISABLED after the Master + Controller's Configure at rest).""" + if self.interlock.armed: + return + for model in self.axes.values(): + if model.drive == "cia402" and model.state == AxisState.ENABLED: + model.state = AxisState.FAULT + + def set_door(self, open_: bool) -> None: + """Open or close the door, on the chassis's link: the door sensor reports the change; the + interlock is not affected (as in Biomek's logs).""" + self.interlock.door_open = open_ + self._queue( + bytes([Device.DIGITAL_INPUT, self.door_input or 1, 0, 0, 0x10, 0x03, 0, int(not open_)]) + ) + + def set_light_curtain(self, broken: bool) -> None: + """Break or clear the light curtain: breaking it trips an armed interlock, which reports it + (Notify On Interlock Trip); while broken, the interlock does not arm.""" + self.interlock.light_curtain_broken = broken + if broken and self.interlock.armed: + self.interlock.armed = False + self._queue(bytes([Device.INTERLOCK, 1, 0, 0, 0x10, 0x03, 0, 0xFF])) + + def axis_model(self, name: str) -> "_AxisModel": + for model in self.axes.values(): + if model.name == name: + return model + raise KeyError(name) + + def answer(self, message: bytes) -> Optional[List[bytes]]: + device, index, opcode, params = message[0], message[1], message[4], message[5:] + header = message[:5] + done = header + b"\x02\x00" + tripped = header + b"\x00\x0f" + self._apply_power() + if device == Device.ANALOG_INPUT and opcode == 0x10 and index == self.supply_input: + powered = self.interlock.armed and self.interlock.supply_comes_up + return [done + struct.pack(" None: + framed = frame(message) + for i in range(0, len(framed), 16): + self._packets.put_nowait(framed[i : i + 16]) + + +@dataclass +class Interlock: + """The interlock one instrument's simulated boards share. `supply_comes_up=False` models an + interlock that arms while the drive supply stays off.""" + + armed: bool = False + supply_comes_up: bool = True + door_open: bool = False + light_curtain_broken: bool = False + + +@dataclass +class _AxisModel: + name: str + homed: bool + state: AxisState = AxisState.NOT_CONFIGURED + drive: str = "cia402" + stuck_fault: bool = False + position: int = 0 + + +# The analog input carrying the interlocked drive supply, per module (the Master Controller's cold +# start: "+36V Interlocked" is the chassis's input 5, "+36V Interlock" each arm's input 4). +SUPPLY_INPUTS = {"chassis": 5, "multichannel": 4, "span8": 4} +# The chassis's digital input 1 is "Door Sensor". +DOOR_INPUTS = {"chassis": 1} + + +def simulated_boards( + motor_tables: MotorTables, + homed: Union[bool, Dict[str, Iterable[str]]] = False, + path: Optional[Union[str, Path]] = None, + default_timeout: float = 1.0, + configured: Optional[Union[bool, Dict[str, bool]]] = None, +) -> List[AceBoard]: + """A simulated instrument as `BiomekI7Driver(boards=...)` takes it: the recorded chassis, a left + Multichannel and a right Span-8 pod. + + Args: + motor_tables: the axes to model: the declared configuration's + (`DeviceConfiguration.motor_tables`), the one the driver is given. + homed: True for every axis homed, False for none, or the homed axes' names per arm type. + path: the recording that answers identity and sensor reads (`recording_path`). + configured: whether each arm's board has its motor tables, as one value or per arm type. + Defaults to configured wherever an axis is homed, and not configured (just powered up) + otherwise. + """ + tables = motor_tables + data = load_recording(path) + interlock = Interlock() + boards = [] + for module, entries in data["boards"].items(): + axes = tables.axes(module) if module in tables.modules else [] + if isinstance(homed, bool): + homed_axes: Iterable[str] = [a.name for a in axes] if homed else [] + else: + homed_axes = homed.get(module, []) + homed_axes = list(homed_axes) + if configured is None: + is_configured = bool(homed_axes) + elif isinstance(configured, bool): + is_configured = configured + else: + is_configured = configured.get(module, False) + usb = SimulatedAceUSB( + dict(entries), + axes, + homed_axes, + name=f"simulated {module}", + configured=is_configured, + interlock=interlock, + supply_input=SUPPLY_INPUTS.get(module), + door_input=DOOR_INPUTS.get(module), + ) + boards.append(AceBoard(io=usb, name=f"simulated {module}", default_timeout=default_timeout)) + return boards diff --git a/pylabrobot/beckman_coulter/biomek_i7/session_log.py b/pylabrobot/beckman_coulter/biomek_i7/session_log.py new file mode 100644 index 00000000000..3bca1a33eb8 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/session_log.py @@ -0,0 +1,88 @@ +"""A run's log in a file of its own, to compare a live run with Biomek's logs of the same work. + +`start_session_log(directory)` writes every line of this package's loggers to +`/biomek_i7_.log`: the driver's commands, warnings and errors, and with +`usb_frames` every message to and from the boards, unframed and in +hex, which is what Biomek's Master Controller keeps in its `ace_io` table. Each line starts with +the time in milliseconds since the epoch, as the Master Controller's tables stamp theirs. + +PyLabRobot's own `pylabrobot.setup_logger` writes one file per day for every PyLabRobot logger; +this one is per run and holds only the Biomek i7's lines, so one run reads on its own. +""" + +import datetime +import logging +from pathlib import Path +from typing import Optional, Union + +PACKAGE_LOGGER = "pylabrobot.beckman_coulter.biomek_i7" +LINE_FORMAT = "%(created_ms)d %(asctime)s.%(msecs)03d %(name)s %(levelname)s %(message)s" +DATE_FORMAT = "%Y-%m-%d %H:%M:%S" + + +class _EpochMilliseconds(logging.Formatter): + def format(self, record: logging.LogRecord) -> str: + record.created_ms = int(record.created * 1000) + return super().format(record) + + +class SessionLog: + """A session log being written; `stop()` closes it.""" + + def __init__(self, path: Path, handler: logging.Handler): + self.path = path + self._handler = handler + + def stop(self) -> None: + """Stop writing the log and close its file.""" + logging.getLogger(PACKAGE_LOGGER).removeHandler(self._handler) + self._handler.close() + + def __enter__(self) -> "SessionLog": + return self + + def __exit__(self, *exc) -> None: + self.stop() + + +def start_session_log( + directory: Union[str, Path], + usb_frames: bool = True, + name: Optional[str] = None, +) -> SessionLog: + """Start writing this package's log lines to a new timestamped file in `directory`. + + The package's loggers are set to log at DEBUG (with `usb_frames`) or INFO, and any of its + loggers set higher is reset to follow the package's level, so every line reaches the file. What + a console shows is up to the console's own handler and its level. + + Args: + directory: where to write the log; made if missing. + usb_frames: also write every message to and from the boards (DEBUG lines ` write ` + and ` read `). + name: the file's name; default `biomek_i7_.log`. + + Returns: + The log being written; `.path` is its file. + """ + directory = Path(directory) + directory.mkdir(parents=True, exist_ok=True) + stamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S") + path = directory / (name or f"biomek_i7_{stamp}.log") + handler = logging.FileHandler(path, encoding="utf-8") + handler.setLevel(logging.NOTSET) + handler.setFormatter(_EpochMilliseconds(LINE_FORMAT, DATE_FORMAT)) + + level = logging.DEBUG if usb_frames else logging.INFO + package = logging.getLogger(PACKAGE_LOGGER) + package.setLevel(level) + for logger_name, logger in logging.root.manager.loggerDict.items(): + if ( + logger_name.startswith(PACKAGE_LOGGER + ".") + and isinstance(logger, logging.Logger) + and logger.level > level + ): + logger.setLevel(logging.NOTSET) + package.addHandler(handler) + package.info("session log started: %s (USB frames %s)", path, "on" if usb_frames else "off") + return SessionLog(path, handler) diff --git a/pylabrobot/beckman_coulter/biomek_i7/session_log_tests.py b/pylabrobot/beckman_coulter/biomek_i7/session_log_tests.py new file mode 100644 index 00000000000..d91626bd110 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/session_log_tests.py @@ -0,0 +1,49 @@ +"""A session log holds the driver's commands and, at DEBUG, every message to and from the boards.""" + +import asyncio +import re +import tempfile +import unittest +from pathlib import Path + +from pylabrobot.beckman_coulter.biomek_i7.session_log import start_session_log +from pylabrobot.beckman_coulter.biomek_i7.simulation_tests_support import ( + generic_driver, + generic_simulated_boards, +) + + +class SessionLogTests(unittest.IsolatedAsyncioTestCase): + async def asyncSetUp(self) -> None: + asyncio.get_running_loop().set_debug(False) + + async def run_setup(self) -> None: + driver = generic_driver(generic_simulated_boards()) # just powered up: configured at setup + await driver.setup() + await driver.stop() + + async def test_a_run_is_logged_with_its_frames(self) -> None: + with tempfile.TemporaryDirectory() as directory: + log = start_session_log(directory) + try: + await self.run_setup() + finally: + log.stop() + lines = Path(log.path).read_text(encoding="utf-8").splitlines() + self.assertTrue(Path(log.path).name.startswith("biomek_i7_")) + self.assertTrue(all(re.match(r"\d{13} ", line) for line in lines)) + self.assertTrue(any(" MC_1 configure" in line for line in lines)) + self.assertTrue(any(re.search(r" write [0-9a-f]+$", line) for line in lines)) + self.assertTrue(any(re.search(r" read [0-9a-f]+$", line) for line in lines)) + + async def test_info_only_leaves_out_the_frames(self) -> None: + with tempfile.TemporaryDirectory() as directory: + with start_session_log(directory, usb_frames=False) as log: + await self.run_setup() + text = Path(log.path).read_text(encoding="utf-8") + self.assertIn(" SPAN8_2 configure", text) + self.assertNotIn(" write ", text) + + +if __name__ == "__main__": + unittest.main() diff --git a/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py b/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py index dc56c661fa4..383804b7c66 100644 --- a/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py +++ b/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py @@ -13,7 +13,7 @@ from pylabrobot.beckman_coulter.biomek_i7.driver.board import AceBoard from pylabrobot.beckman_coulter.biomek_i7.driver.configuration import DeviceConfiguration from pylabrobot.beckman_coulter.biomek_i7.driver.master import BiomekI7Driver -from pylabrobot.beckman_coulter.biomek_i7.driver.simulator import ReplayAceUSB +from pylabrobot.beckman_coulter.biomek_i7.driver.simulator import ReplayAceUSB, simulated_boards _GENERIC: Optional[Dict[str, Any]] = None @@ -89,6 +89,14 @@ def configuration_file(configuration: DeviceConfiguration) -> str: return str(path) +def generic_simulated_boards(**kwargs: Any) -> List[AceBoard]: + """The generic instrument simulated (`simulator.simulated_boards`), with the generic + configuration's motor tables and the generic cold start; `kwargs` as `simulated_boards` takes + them (`homed`, `configured`).""" + kwargs.setdefault("path", GENERIC_RECORDING) + return simulated_boards(generic_configuration().motor_tables, **kwargs) + + def generic_driver( boards: Optional[Sequence[AceBoard]] = None, configuration: Optional[DeviceConfiguration] = None,