Skip to content

bi7/03: Biomek i7: configuring, the interlock, faults, pause and stop - #1644

Open
cmoscy wants to merge 11 commits into
PyLabRobot:mainfrom
cmoscy:bi7/03-lifecycle
Open

cmoscy wants to merge 11 commits into
PyLabRobot:mainfrom
cmoscy:bi7/03-lifecycle

Conversation

@cmoscy

@cmoscy cmoscy commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Summary

  • setup after discovery: configure motors, arm interlock, enable axes (no motion).
  • Faults, pause/resume, stop, door/light-curtain reporting; shared simulator interlock state.

Test plan

  • Lifecycle / interlock / pause / stop simulator tests pass

… empty cache

Choosing a device by `serial_number` compared it with `dev._serial_number`, which PyUSB fills
only once something has read `dev.serial_number`. Straight after enumeration it is None, so every
device was refused as having no serial number. The serial number is now read through the
descriptor (`dev.serial_number`), and a device without one (`iSerialNumber == 0`) is still refused.
The Biomek tips (T50F, T190F, T230, T1025F, T1070), their 96-tip boxes (BC50F, BC190F, BC230,
BC1025F, BC1070), plates (Thermo96VB_PP, BCFlat96, BCDeep96Square, Thomson_24w_Square_RB, with the
lids Biomek seats on them) and reservoirs (ThermoNUNC_350CB, Reservoir, ModularReservoir),
transcribed from Biomek 5's tip and labware classes.

A tip is a `BiomekTip`, a `Tip` that also carries its cone (the radius at its end and the length
over which it widens); a well is a `BiomekWell`, a `Well` that also carries Biomek's outline of it by
height (`WellSegment`s), from which its height <-> volume table and its wall come. Biomek uses both
to place a tip near a well's wall, as `HamiltonTip` and `TecanTip` carry their instruments' data. A
tip box is a `StandingTipRack` whose tip spots sit on its top face, where the head's mandrels meet
the tips. Each resource carries Biomek's grip point (`preferred_pickup_location`). A resource
library page lists them with their part numbers.
`TipMountingShaft.serialize_state` holds the tool the shaft carries (as it serializes; None for
none), as a tip spot's state holds its tip, and `load_state` puts it back: the saved tip goes onto
the shaft (a tool of the same name held elsewhere in the tree gives way first), and a saved None
takes off the one it carries. State saved before shafts had any leaves the shaft as it is. With
it, `save_state_to_file` / `load_state_from_file` keep the tips a head carries across sessions,
which a device that cannot sense its tips needs.

Tests: a carried tip saved and read back, its own state after it; None taking a tip off; the same
tip staying; a tip of that name held elsewhere giving way.
…covery

The first part of a Beckman Coulter Biomek i7 driver that talks to the instrument's ACE boards
directly over USB (0AB5:ACE0), one board per module: the chassis and one per pod.

- `driver/framing.py`, `board.py`: length-prefixed frames packed into interrupt transfers; a board's
  replies matched to their requests by header, two-stage replies (ACCEPTED, DONE), unsolicited
  messages to subscribers.
- `driver/protocol.py`, `errors.py`: every request the Master Controller was logged sending, plus
  three reads, and nothing else; each field layout as Biomek's `ace_io` log (Log.db3) decodes it.
- `driver/master.py`, `features/chassis.py`, `features/pod.py`, `module.py`: discovery places each
  board by what it reports (Get Module ID: type and side), not by USB order or serial number, then
  reads each module's serial number, its boards with their application images and versions, and
  the names of its inputs, in the order of the Master Controller's cold start. It writes nothing
  to the boards. Unknown types or sides, two boards in one place, and no chassis are refused.
- `driver/simulator.py`, `defaults/`: boards replayed from a cold-start recording; a generic one
  ships, every serial number replaced by a placeholder.

Tests: one exact frame per command (from Biomek's `ace_io` log; three reads it never logged from
their layout), build and parse round trips, framing inverses, the replay's rules, and discovery on
the generic recording. Discovery sends the same requests as on the full driver this series comes
from.
What the boards cannot report about an instrument, declared per instrument in one JSON file
given by path (`declared_configuration_json`, now required):

- `driver/configuration.py`: `DeviceConfiguration`, the motor tables (the Master Controller's
  instrument record: each axis's Configure parameters, home position and measured hysteresis, and
  the modules' serial numbers) and per pod the conversions, travel limits, geometry and settings
  from Biomek's instrument file, with the default deck's calibrated positions and layout. Each
  source's values carry a fingerprint; a file changed after import is refused at load.
  `anonymized()` makes a generic one: no serial numbers, no measured hysteresis.
- `driver/motors.py`: the axes of each arm type and the limits read from their Configure bytes.
- `units.py`: the one place PyLabRobot's units (mm, uL, mm/s) meet Biomek's (cm, its frame, the
  speed field).
- `defaults/`: the generic configuration, one instrument's physical values with every serial number
  removed.
- Discovery refuses a pod type other than the declared one, and on the instrument a configuration
  whose serial numbers are not the modules', or the generic one. Each pod gets its type's axes and
  its declared values.

Tests: conversions give the counts Biomek's logs show for the instrument file's targets, the
bridges meet where Biomek's logged moves stopped, save / load and the changed-file refusal,
anonymizing, declared against found, the serial-number check on the instrument's own path, every
speed field round-tripping on every Z and pump, and the motor tables' limits.
… checked against them

`DeviceConfiguration.from_biomek` makes an instrument's declared configuration from its two
Biomek sources, read-only, standard library only (`biomek_files/`):

- `variant_tree.py`: Biomek's variant-tree files (the instrument file, `.bif`); a file with any
  byte it cannot account for is refused, not misread.
- `instrument_file.py`: the pods (conversions, travel, geometry, settings, gripper, obstacles),
  the default deck's calibrated positions and layout; Biomek's runtime state in the same file is
  left out.
- `master_controller.py`: the Master Controller's instrument record (its database's `instrument`
  table, or a text file of it): motor tables, home positions, measured hysteresis, the modules'
  serial numbers.
- `importer.py`: the two put together and checked against each other, each source's path, kind,
  read time and fingerprint recorded; `check_sources` reads them again and lists what changed.

On the instrument, discovery now also refuses a configuration whose sources have changed since it
was imported (a re-framed position, a re-measured hysteresis), and warns where they cannot be
found. Reading the database closes its connection.

Tests: the readers on files written in the test from the generic configuration (a small
variant-tree writer and a record writer, `files_tests_support.py`): every value kind and class
body, the refusals, the round trip from configuration to files and back, inconsistent sources,
changes found by `check_sources`, and the discovery check on the instrument's own path.
`setup()` now brings the instrument up after discovery, moving nothing: the motor tables are loaded
where a board has lost them, the interlock is armed and every axis enabled, in the order Biomek's
Master Controller logs show.

- `driver/master.py`: `initialize`, `configure`, `arm_interlock`; a fault at rest is only noted, one
  under power is reset with a warning, one that does not clear trips the interlock and shows ERROR;
  per-pod skips; `stop` stops each pod's module and trips the interlock when the driver armed it;
  a motor failing on its own, or the interlock tripping under the driver, trips it and shows ERROR,
  as the Master Controller's logs show; `pause` / `resume` (a deliberate trip with PAUSED shown,
  then re-arm and enable).
- `driver/features/chassis.py`, `door.py`: the interlock's writes, the status display, the door
  (`front_cover`), which only reports.
- `driver/features/pod.py`: configure, enable, axis states, positions, homed state.
- `driver/simulator.py`: `SimulatedAceUSB`, each axis's state and the interlock, door and drive
  supply the boards of one instrument share.
- `session_log.py`: a run's log lines in a file of its own, to compare with Biomek's logs.

Tests: the simulated boards' rules; configure sends the Configure, interlock and I/O box requests
the Master Controller sent at the recorded cold start, in its order; enabling follows its order;
faults at rest, under power and stuck; the drive supply, an open door, a broken light curtain; door
reports; pause / resume; a motor failing on its own; stop; the session log.
@cmoscy cmoscy changed the title Biomek i7: configuring, the interlock, faults, pause and stop bi7/03: Biomek i7: configuring, the interlock, faults, pause and stop Nov 17, 2026
@cmoscy
cmoscy marked this pull request as ready for review November 17, 2026 03:49
@cmoscy
cmoscy requested a review from a team as a code owner November 17, 2026 03:49

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant