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/10] `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/10] `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/10] `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/10] `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/10] `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/10] `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/10] `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/10] `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/10] `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/10] `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)