Config for min channel spacing that's not 9 mm

[HaamsRee]

I have a Hamilton STAR with a weird config. It has a single arm holding a 96-head and four 1 mL channels with 18 mm spacing. When running with probe_liquid_height=True in a 96-well format, this results in channel 3 probing in a position that's outside of the column of wells, channel 2 probing B1, channel 1 probing D1, etc. I found a temporary workaround by changing the probe to be sequential:

    current_absolute_liquid_heights: List[float] = []
    for channel, container, tip, offset in zip(use_channels, containers, tips, resource_offsets):
      y_pos = container.get_location_wrt(self.deck, x="c", y="c", z="b").y + offset.y

      if sequential_probe:
        # # Give the active channel full freedom by parking others, then position only this channel.
        # await self.position_max_free_y_for_n(pipetting_channel_index=channel)
        # await self.move_channel_y(channel=channel, y=y_pos)
        await self.position_channels_in_y_direction({channel: y_pos})

      else:
        # Positions are sufficiently spaced; move the set in one go.
        await self.position_channels_in_y_direction(
          {channel: y for channel, y in zip(use_channels, target_y_positions)}
        )

      await self.move_z_drive_to_liquid_surface_using_clld(
        channel_idx=channel,
        lowest_immers_pos=container.get_absolute_location("c", "c", "cavity_bottom").z
        + tip.total_tip_length
        - tip.fitting_depth,
        start_pos_search=container.get_absolute_location("c", "c", "t").z
        + tip.total_tip_length
        - tip.fitting_depth
        + 5,
      )

      # TODO: Move z up after probing


      liquid_levels: List[int] = (await self.request_pip_height_last_lld())["lh"]  # type: ignore
      current_absolute_liquid_heights.append(float(liquid_levels[channel] / 10))

But I think there are other places where the 9 mm min spacing is hardcoded. It would be nice to have this as a config that the user can change, or read from the instrument.

[rickwierenga]

thanks for bringing this up, I think you're the first person I hear from using 4mL channels

we certainly have 9mm hardcoded in some places ...

im certainly happy to work on this, just a heads up that there might be a few problems similar to this one

first of all: do you know if it's possible to mix&match 1mL and 4mL channels?

[HaamsRee]

thanks for bringing this up, I think you're the first person I hear from using 4mL channels

we certainly have 9mm hardcoded in some places ...

im certainly happy to work on this, just a heads up that there might be a few problems similar to this one

first of all: do you know if it's possible to mix&match 1mL and 4mL channels?

Thanks for the quick reply. I'm not sure about mixing 4mLs and 1mLs. We have 4x1mL channels. They do work with iSWAP on the same rail tho

[rickwierenga]

thanks, I will go through the star backend some time this week and attempt to work out the hardcoded 1ml channel behavior and report here. please tell me if you find other bugs

[rickwierenga]

to clarify: are these 1ml or 4ml channels?

[BioCam]

Hi @HaamsRee,

Can I please ask for some clarification of the main issue you are seeing?:

• You have a specialised STAR in which 1_000uL/1mL channels cannot get closer to each other than 18 mm?
  (Do you have a picture of these channels, specifically their connection to their rails?)

Case study - Aspirate/Dispense in "A1:D1" (96-wellplate):

• Does standard aspirate/dispense work?
  i.e. the smart firmware plans the movement correctly, i.e. it knows the channels cannot get to the 9mm distance needed and then automatically decides to perform each aspirate/dispense sequentially?

• But, when using the new PLR-parameter probe_liquid_height=True the liquid probing doesn't have smart firmware decision making and therefore ... crashes?, errors?, or still performs the probing but instead of channel:well spacing 0:A1, 1:B1, 2:C1, 3:D1 you are seeing 0:A1, 1:C1, 2:E1, 3:G1 ?

[HaamsRee]

to clarify: are these 1ml or 4ml channels?

These are 1 mL channels.

[HaamsRee]

Hi @HaamsRee,

Can I please ask for some clarification of the main issue you are seeing?:

• You have a specialised STAR in which 1_000uL/1mL channels cannot get closer to each other than 18 mm?
  (Do you have a picture of these channels, specifically their connection to their rails?)

Here's a picture:

The min distance is 18 mm because they're mounted on a single rail. In a normal STAR, the channels are staggered to get to 9 mm. I can snap a better one tomorrow.

Case study - Aspirate/Dispense in "A1:D1" (96-wellplate):

• Does standard aspirate/dispense work?
  i.e. the smart firmware plans the movement correctly, i.e. it knows the channels cannot get to the 9mm distance needed and then automatically decides to perform each aspirate/dispense sequentially?

Standard aspirate/dispense works, as well as tip pickup.

• But, when using the new PLR-parameter probe_liquid_height=True the liquid probing doesn't have smart firmware decision making and therefore ... crashes?, errors?, or still performs the probing but instead of channel:well spacing 0:A1, 1:B1, 2:C1, 3:D1 you are seeing 0:A1, 1:C1, 2:E1, 3:G1 ?

It doesn't error, but does this instead:

And then it crashes due to the innermost channel.

[BioCam]

@HaamsRee, thank you that picture of your setup explains the physical limitations perfectly!
This is the first time, to my knowledge, PLR is dealing with a "half-sized pipetting arm":

This is very important information because there are a couple of potentially hard-coded PLR-STAR constraints that we should fix for you: including the reach of the 96-head - yours can go much further to the right! (very timely! I just started a series of 96-head upgrades)

It doesn't error, but does this instead:

Can you please provide a minimal code example that causes this behaviour?
I can then run it in simulation/visualisation mode and create the firmware command to understand why this is happening

Also, can you please show us the return of running the following on your STAR?:

from pylabrobot.liquid_handling import LiquidHandler
from pylabrobot.resources.hamilton import STARDeck
from pylabrobot.liquid_handling.backends import STARBackend

star = STARBackend()
lh = LiquidHandler(backend=star, deck=STARDeck())

await lh.setup()

for ch_idx in range(4):
  channel_fw_version = await star.request_pip_channel_version(ch_idx)
  print(f"{ch_idx}: {channel_fw_version=}")

print(star._head96_information)

[HaamsRee]

@BioCam

Can you please provide a minimal code example that causes this behaviour?
I can then run it in simulation/visualisation mode and create the firmware command to understand why this is happening

from pylabrobot.liquid_handling import LiquidHandler
from pylabrobot.liquid_handling.backends import STARBackend
from pylabrobot.resources.hamilton import STARDeck
from pylabrobot.resources import (
  TIP_CAR_480_A00,
  PLT_CAR_L5AC_A00,
  Cor_96_wellplate_2mL_Vb ,
  hamilton_96_tiprack_1000uL_filter,
)

backend = STARBackend()
lh = LiquidHandler(backend=backend, deck=STARDeck(core_grippers=None))

await lh.setup()

tip_car = TIP_CAR_480_A00(name="tip carrier")
tip_car[0] = hamilton_96_tiprack_1000uL_filter(name="tips_01")

lh.deck.assign_child_resource(tip_car, rails=11)

plt_car = PLT_CAR_L5AC_A00(name="plate carrier")
plt_car[0] = Cor_96_wellplate_2mL_Vb (name="plate_01")

lh.deck.assign_child_resource(plt_car, rails=5)

plate = lh.deck.get_resource("plate_01")

tiprack = lh.deck.get_resource("tips_01")
await lh.pick_up_tips(tiprack["A1:C1"])

await lh.aspirate(plate["A1:C1"],
                  vols=[100.0, 50.0, 200.0],
                  lld_mode=[backend.LLDMode.GAMMA] * 3,
                  probe_liquid_height=True, ### Happens when this is enabled ###
                  auto_surface_following_distance=True,
                  immersion_depth=[1] * 3)

Also, can you please show us the return of running the following on your STAR?:

2026-01-29 13:37:26,956 - pylabrobot.io.usb - INFO - Finding USB device...
2026-01-29 13:37:27,019 - pylabrobot.io.usb - INFO - Found USB device.
2026-01-29 13:37:27,021 - pylabrobot.io.usb - INFO - Found endpoints.
Write:
ENDPOINT 0x2: Bulk OUT ===============================
bLength : 0x7 (7 bytes)
bDescriptorType : 0x5 Endpoint
bEndpointAddress : 0x2 OUT
bmAttributes : 0x2 Bulk
wMaxPacketSize : 0x40 (64 bytes)
bInterval : 0x0
Read:
ENDPOINT 0x81: Bulk IN ===============================
bLength : 0x7 (7 bytes)
bDescriptorType : 0x5 Endpoint
bEndpointAddress : 0x81 IN
bmAttributes : 0x2 Bulk
wMaxPacketSize : 0x40 (64 bytes)
bInterval : 0x0
0: channel_fw_version='4.0S j 2022-03-16'
1: channel_fw_version='4.0S j 2022-03-16'
2: channel_fw_version='4.0S j 2022-03-16'
3: channel_fw_version='4.0S j 2022-03-16'
Head96Information(fw_version=datetime.date(2021, 10, 22), supports_clot_monitoring_clld=False, stop_disc_type='core_ii', instrument_type='legacy', head_type='96 head II')

[BioCam]

@HaamsRee, this is very interesting - insight: on a "standard" STAR the channels are alternating between the two rails, giving each rail either only odd or even indices, but your system indexes channels still 0-3 even though they are on the same rail.

This has helped me develop the following plan to fix this issue:

1. Add STARBackend._channel_minimum_y_spacing: float = 9.0 and overwrite it right after the .set_up_pip() channel initialisation.
   Status: PR submitted Enable Variable Channel Spacing in STARBackend #862
   (this sets up the necessary infrastructure to fix the channel spacing variability between different STAR(let)s)
2. Auto-identify _channel_minimum_y_spacing - we can't have people be required to declare the channel spacing of their STAR manually, PLR is better than this :)
   I have multiple ideas of how to do this. Please see below another request for data from you for this purpose.
   Status: options mapped / machine information gathering to identify fastest/easiest one
3. Update STARBackend.probe_liquid_heights() to check whether the spacing between the to-probe-containers >= STARBackend._channel_minimum_y_spacing -> if True: behave as now (i.e. in parallel) else probe each container separately
   Status: required logic identified, and sequential probing already tested by @HaamsRee; writing PR atm

Could you please send us the return of the following?:

from pylabrobot.liquid_handling import LiquidHandler
from pylabrobot.resources.hamilton import STARDeck
from pylabrobot.liquid_handling.backends import STARBackend

star = STARBackend()
lh = LiquidHandler(backend=star, deck=STARDeck())

await lh.setup()

# Test idea 1:
for ch_idx in range(4):
    # These are just MEM-READ commands - no moving parts :)
    new_fw_cmd = await star.send_command(
        module=star.channel_id(ch_idx),
        command="VY",
    )
    print(f"{ch_idx=}: VY - {new_fw_cmd=}")

    new_fw_cmd = await star.send_command(
        module=star.channel_id(ch_idx),
        command="BY",
    )
    print(f"{ch_idx=}: BY - {new_fw_cmd=}\n")

# Test idea 2:
await star.move_all_channels_in_z_safety()
await star.spread_pip_channels()

channels_y_positions = await star.get_channels_y_positions()
print(f"\nSpread: {channels_y_positions=}")
# TODO: rename to .channels_request_y_positions()

await star.prepare_for_manual_channel_operation(channel=0)

channels_y_positions = await star.get_channels_y_positions()
print(f"\nTight for ch_idx>0: {channels_y_positions=}")

config_to_find_arm_width = await star.send_command(
        module="C0",
        command="QM",
    )
print(f"\n{config_to_find_arm_width=}")

Cherry on top:
This will solve your issue... but it will still not be pretty -> the probing would be executed one channel at a time - that's great and needed - but it will initially probe all containers first, and then use that information to perform the aspirate/dispense action separately (guided by the smart firmware).
I.e. it would be a 2-step process: first probe everything, then aspirate/pipette
That's too slow for PLR.

So here is step 4:

• Power up STARBackend.probe_liquid_heights() even further:
  to perform the smart planning that the firmware already does for aspirate/dispense but this time in PLR! -> i.e. PLR identifies the correct mapping by sorting containers into what can be probed AND aspirated/dispensed directly.
  This will ensure you probe a container and straight away aspirate/dispense - no time lost on separation of probing and aspirate/dispense.
  Status: writing PR atm (steps 3 and 4 can be solved together)

This is the way I suggest we fully integrate single-channel-rail "legacy" STAR(let)s into PyLabRobot 😊

Estimated completion (without promising too much of my spare/non-consulting/non-main job time 😅 ): start of SLAS 2026 next week

Let's do this 🚀

[rickwierenga]

output for me on a 12 channel 9mm spread star:

ch_idx=0: VY - new_fw_cmd='P1VYid0016yc000 194 0'
ch_idx=0: BY - new_fw_cmd='P1BYid0017er00'

ch_idx=1: VY - new_fw_cmd='P2VYid0018yc000 194 1'
ch_idx=1: BY - new_fw_cmd='P2BYid0019er00'

ch_idx=2: VY - new_fw_cmd='P3VYid0020yc000 194 0'
ch_idx=2: BY - new_fw_cmd='P3BYid0021er00'

ch_idx=3: VY - new_fw_cmd='P4VYid0022yc000 194 1'
ch_idx=3: BY - new_fw_cmd='P4BYid0023er00'


Spread: channels_y_positions={0: 560.3, 1: 514.2, 2: 468.0, 3: 421.8, 4: 375.7, 5: 329.5, 6: 283.3, 7: 237.2, 8: 191.0, 9: 144.8, 10: 98.7, 11: 52.5}

Tight for ch_idx>0: channels_y_positions={0: 560.3, 1: 96.0, 2: 87.0, 3: 78.0, 4: 69.0, 5: 60.0, 6: 51.0, 7: 42.0, 8: 33.0, 9: 24.0, 10: 15.0, 11: 6.0}

config_to_find_arm_width='C0QMid0029er00/00ka010003xt54xa54xw13400xl07xr00xm03500xx11400ys090xu3700xv3700yu0060kl360kc0yx0060ke00000000xn00xo00ym6065kr0km360'

[BioCam]

Thank you @rickwierenga - this is the answer for step 2: auto-detection of possible minimum y-spacing between channels 😄

@HaamsRee, could you please provide the same response from your STAR so we are sure we get the correct response from your machine too?
(I believe your response should say 388 where Rick's says 194 - if it does or is close, we're good to go; I will raise the PR for this feature integration)

[HaamsRee]

@BioCam Here:

2026-02-01 15:17:37,568 - pylabrobot.io.usb - INFO - Finding USB device...
2026-02-01 15:17:37,630 - pylabrobot.io.usb - INFO - Found USB device.
2026-02-01 15:17:37,633 - pylabrobot.io.usb - INFO - Found endpoints. 
Write:
       ENDPOINT 0x2: Bulk OUT ===============================
       bLength          :    0x7 (7 bytes)
       bDescriptorType  :    0x5 Endpoint
       bEndpointAddress :    0x2 OUT
       bmAttributes     :    0x2 Bulk
       wMaxPacketSize   :   0x40 (64 bytes)
       bInterval        :    0x0 
Read:
       ENDPOINT 0x81: Bulk IN ===============================
       bLength          :    0x7 (7 bytes)
       bDescriptorType  :    0x5 Endpoint
       bEndpointAddress :   0x81 IN
       bmAttributes     :    0x2 Bulk
       wMaxPacketSize   :   0x40 (64 bytes)
       bInterval        :    0x0
ch_idx=0: VY - new_fw_cmd='P1VYid0016yc194 388 1'
ch_idx=0: BY - new_fw_cmd='P1BYid0017er00'

ch_idx=1: VY - new_fw_cmd='P2VYid0018yc194 388 1'
ch_idx=1: BY - new_fw_cmd='P2BYid0019er00'

ch_idx=2: VY - new_fw_cmd='P3VYid0020yc194 388 1'
ch_idx=2: BY - new_fw_cmd='P3BYid0021er00'

ch_idx=3: VY - new_fw_cmd='P4VYid0022yc194 388 1'
ch_idx=3: BY - new_fw_cmd='P4BYid0023er00'


Spread: channels_y_positions={0: 597.5, 1: 579.5, 2: 561.6, 3: 543.6}

Tight for ch_idx>0: channels_y_positions={0: 597.5, 1: 41.9, 2: 23.9, 3: 6.0}

config_to_find_arm_width='C0QMid0029er00/00ka018002xt54xa54xw13400xl07xr00xm03600xx11400ys180xu2460xv3540yu0060kl360kc0yx0060ke00000000xn00xo00ym6065kr0km360'

@HaamsRee, this is very interesting - insight: on a "standard" STAR the channels are alternating between the two rails, giving each rail either only odd or even indices, but your system indexes channels still 0-3 even though they are on the same rail.

This reminded me that the techs who set it up had a lot of trouble making this four-channel config work. I wonder if the board has a connector for each channel with physical indices, and in this configuration, the channels should be plugged into ports 0, 2, 4, and 6. I have no idea how it actually works. Just a note for future weirdness.