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/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/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(" 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..b423c4a6391 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/configuration.py @@ -0,0 +1,582 @@ +"""What the driver knows about an instrument: facts only (STAR design.md P3). + +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 only by `DeviceConfiguration.from_biomek` from the + instrument's two Biomek sources (`biomek_files/`), 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), and a live session refuses one whose sources have changed since + (`check_sources`). +""" + +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): +# 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 + + +# -- 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() + + +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. + + `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] + + @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()) + 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 by anything but `from_biomek`.""" + 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 `from_biomek` made and `save` wrote. + + Raises: + ValueError: if its values no longer match the fingerprints recorded at import: it was + changed afterwards. Make it again with `from_biomek`. + """ + 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, or not made by `DeviceConfiguration.from_biomek`); 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/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..c08056a6c9a --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/features/pod.py @@ -0,0 +1,114 @@ +"""One pod: an arm on the shared X rail, its ACE module, and the axes that module drives.""" + +from typing import Dict, List, Literal, Optional, Tuple + +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, + 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" + + +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). 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, + 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: + 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}" + + 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) + 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..f7aeab409b6 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/master.py @@ -0,0 +1,367 @@ +"""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 ( + 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 + +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, + 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), 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. + + 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 " + "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 + 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 + 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`). + 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 " + "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, no chassis, or a pod type other than the declared one is refused + (`_check_declared_against`). + + 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, or is stale. + """ + 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._check_declared_against(types) + self.chassis = Chassis(places["chassis"]) + 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())) + 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) + ) + 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 by " + "`DeviceConfiguration.from_biomek` from its Biomek files." + ) + 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. + Moves nothing. + + Raises: + RuntimeError: before discovery (`discover` or `setup`). + """ + 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, indent: Optional[int] = 2) -> None: + """Write the declared configuration to `path`, as loaded, for `declared_configuration_json` to + 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: + 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/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/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/serial_numbers_tests.py b/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py new file mode 100644 index 00000000000..f77e3888fc4 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/driver/serial_numbers_tests.py @@ -0,0 +1,142 @@ +"""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` +would open the USB devices, so `discover` runs exactly as on the instrument.""" + +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 +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, +) + +MASTER_LOGGER = "pylabrobot.beckman_coulter.biomek_i7.driver.master" +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 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) + + 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/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..dc56c661fa4 --- /dev/null +++ b/pylabrobot/beckman_coulter/biomek_i7/simulation_tests_support.py @@ -0,0 +1,103 @@ +"""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_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 + (`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_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..9de769f9d66 --- /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.beckman_coulter.biomek_i7.simulation_tests_support import generic_driver +from pylabrobot.resources.coordinate import Coordinate + + +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() 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() 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..9d267dddfc9 --- /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, + BiomekWell, + Plate, + 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..1e8ef072f54 --- /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_50uL_filter, + beckman_coulter_biomek_tip_190uL_filter, + beckman_coulter_biomek_tip_230uL, + beckman_coulter_biomek_tip_1025uL_filter, + beckman_coulter_biomek_tip_1070uL, +) + + +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 + ) 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..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): @@ -18,6 +19,56 @@ 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 + 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 + + 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."""