Support variable channel spacing via per-channel minimum Y spacing firmware retrieval by BioCam · Pull Request #915 · PyLabRobot/pylabrobot

BioCam · 2026-03-01T20:36:28Z

The Problem

All channel spacing in STARBackend was hardcoded to a single value (9mm / 8.9mm / 8990µm depending on the call site). This fails for:

4-channel single-rail machines with 18mm spacing; reported PLR user configuration in Config for min channel spacing that's not 9 mm #822
Mixed 1mL + 5mL channel configurations where adjacent channels have different physical constraints (e.g. 8.98mm between two 1mL channels, 17.96mm between a 1mL and 5mL channel) -> preparation for the new X1 channels arriving to consumers

The constraint is per-channel and symmetric: each channel carries its own minimum spacing, and the safe distance between any two adjacent channels is the max() of both.

PR Content/Solution

Infrastructure (STAR_backend.py)

_channel_minimum_y_spacing: float → _channels_minimum_y_spacing: List[float] (per-channel)
_min_spacing_between(i, j) helper: round(max(spacing[i], spacing[j]), 1)
channels_request_y_minimum_spacing(): parallel P<n>VY queries via asyncio.gather at setup
All 11 consumer sites updated: can_reach_position, position_channels_in_y_direction, get_channels_y_positions,
probe_liquid_heights safe bounds, CoRe gripper assert, validation

Simulation (STAR_chatterbox.py)

channels_minimum_y_spacing constructor param (defaults to [9.0] * num_channels)
channel_request_y_minimum_spacing() / channels_request_y_minimum_spacing() overrides — return stored values without firmware calls

Generic LH (utils.py)

min_spacing parameter added to get_wide_ and get_tight_single_resource_liquid_op_offsets (default unchanged)
Renamed constant to GENERIC_LH_MIN_SPACING_BETWEEN_CHANNELS

Tests (STAR_tests.py)

4 behavioral tests comparing 4ch/18mm vs 8ch/9mm: reachability bounds, validation rejection, and JY command payload differences

NOTE: This PR is meant to bring NO BREAKING CHANGES :)

Copilot

Pull request overview

This PR updates the Hamilton STAR backend to support per-channel minimum Y spacing (queried from firmware or provided by the simulator) instead of relying on a single hardcoded spacing, enabling correct behavior on 4ch/18mm single-rail and mixed-spacing channel configurations.

Changes:

Replace global channel spacing with a per-channel spacing list and enforce spacing using a pairwise max() rule.
Add firmware queries to retrieve per-channel minimum Y spacing during setup; add simulator overrides to supply these values without hardware calls.
Extend generic liquid-handling offset utilities to accept a configurable min_spacing, and add tests covering behavioral differences between 9mm vs 18mm spacing.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
`pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py`	Introduces per-channel spacing storage, firmware retrieval, and updates spacing enforcement/validation logic across Y-motion related code paths.
`pylabrobot/liquid_handling/backends/hamilton/STAR_chatterbox.py`	Adds constructor/setup support for simulated per-channel spacing and overrides spacing query methods.
`pylabrobot/liquid_handling/utils.py`	Renames the generic min-spacing constant and adds `min_spacing` parameters to offset helper functions (default preserved).
`pylabrobot/liquid_handling/backends/hamilton/STAR_tests.py`	Adds tests validating reachability and movement command differences for 4ch/18mm vs 9mm spacing configurations.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py

pylabrobot/liquid_handling/utils.py

pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py

rickwierenga · 2026-03-02T06:42:59Z

pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py

+      rounded: If True (default), round the result to 1 decimal place. Hardware reports
+        exact values (e.g. 8.98) which round to the expected 9.0.
+


just choose a behavior that works, a parameter is making it overly complex

I would lean towards not rounding and letting the user (caller) round if they need to

the user doesn't have access to a lot of the usage of these parameters (e.g. going into the spread channels command at runtime), but the user does expect minimal spacing of 9 mm.

if forced to not give the user deeper insight into what the firmware returns via this parameter, I would prefer to use math.ceil which is conservative and safe, and always produces what the user expects -> 9 mm / 18 mm

if that's what the method should method should return to be correct sure

otherwise the user can call round or ceil or whatever

pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py

rickwierenga · 2026-03-02T06:51:29Z

pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py

    else:  # probing_direction == "forward"
+      adjacent_idx = max(channel_idx - 1, 0)
      if channel_idx == 0:  # safe default
        adjacent_y_pos = STARBackend.y_drive_increment_to_mm(13_714) + 9  # y-position=635 mm
      else:  #  previous channel
        adjacent_y_pos = await self.request_y_pos_channel_n(channel_idx - 1)

      max_safe_y_mov_dist_post_detection = (
-        adjacent_y_pos - detected_material_y_pos - self._channel_minimum_y_spacing
+        adjacent_y_pos
+        - detected_material_y_pos
+        - self._min_spacing_between(channel_idx, adjacent_idx)


adjacent_idx = max(channel_idx - 1, 0) seems like a special case to me, not sure if we can just say adjacent_idx = 0 when channel_idx = 0 and expect the code to work.

strictly speaking _min_spacing_between should raise when this happens I think

pylabrobot/liquid_handling/backends/hamilton/STAR_tests.py

pylabrobot/liquid_handling/utils.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

rickwierenga · 2026-03-02T20:57:28Z

we do not know what the minimum y position for 5mL channels in the front, but given that for 9mm channels it's 6, it'd probably be 15

…ackmost_channel_max_y Replace hardcoded 6/6.0/5.8/635 and y_drive_increment_to_mm(13_714) constants with methods that derive the limits from _channels_minimum_y_spacing and iswap state. Also simplify the y_search_channel anti-crash and post-detection logic to compute safe bounds directly rather than through fake self-spacing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

BioCam · 2026-03-03T07:57:59Z

we do not know what the minimum y position for 5mL channels in the front, but given that for 9mm channels it's 6, it'd probably be 15

Why 15?

If y = 6 mm is the center of 1 mL channel index=-1 (radius=4.5 mm) then the frontfacing inaccessible y-distance is 1.5 mm.

Since a 5 mL channel is assumed to be double the diameter (radius=9 mm): 9 mm + 1.5 = 10.5 mm

…tations - _backmost_channel_max_y: account for channel 0's spacing (symmetric with _frontmost) - _min_spacing_between: match error message format (i={i}, j={j}) - position_channels_in_y_direction: cleaner validation using round(um) comparison - move_channel_y: inline _frontmost_channel_min_y() call, no local var - TestChannelsMinimumYSpacing: more thorough tests (both 9mm-pass AND 18mm-fail, raw STARBackend for can_reach, chatterbox+JY verification for position_channels) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…-pipette-orchestration Resolved conflicts keeping our orchestration architecture (pipette_orchestration.py, plan_batches, probe_liquid_heights) while incorporating PR PyLabRobot#915's spacing infrastructure. Both branches' per-channel spacing helpers were pre-aligned in the previous commit. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

rickwierenga · 2026-03-05T05:36:18Z

merged main into this branch, including new changes from #876

…channels_request_y_minimum_spacing override Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Parse RM and QM command responses into typed dataclasses instead of raw dicts. All bit fields (kb, ka, ke, xl, xn, xr, xo) are parsed into descriptive boolean attributes. Positional values are converted from 0.1mm to mm. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…nimum-y-spacing-adaptation

…g default Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove _frontmost_channel_min_y and _backmost_channel_max_y helpers, use extended_conf.left_arm_min_y_position and extended_conf.pip_maximal_y_position directly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

BioCam added 2 commits March 1, 2026 20:19

convert to list for each channel's spacing, tests, sim, utils fix

29f19a4

make format

ff05a77

BioCam requested review from Copilot and rickwierenga March 1, 2026 20:39

Copilot started reviewing on behalf of BioCam March 1, 2026 20:40 View session

Copilot AI reviewed Mar 1, 2026

View reviewed changes