Updating PLR API for machine interfaces discussion

dev discussion
64

@rickwierenga agree with the structure and the argument for separate capability instances over kwargs.

One naming proposal: the abstract ABCs that define what a backend must implement. Why not call those contracts, named with a Can... prefix.

Why?: Backend currently means both the abstract spec (OrientableArmCapabilityBackend) and the concrete implementation (STARiSWAPBackend). The Can... prefix disambiguates at a glance.

Arm example (see recent arm thread):

  # Contracts — the spec
  class CanPickUpResource(DeviceBackend, ABC):
      async def pick_up_resource(self, ...) -> None: ...
      async def drop_resource(self, ...) -> None: ...

  class CanOrientGrip(ABC):
      async def oriented_pick_up_resource(self, ..., grip_direction) -> None: ...

  # Drivers — the implementation (pick which contracts they fulfill)
  class STARiSWAPDriver(CanPickUpResource, CanOrientGrip): ...   # can rotate
  class STARCoreGripperDriver(CanPickUpResource): ...             # cannot rotate

The alternative would be keeping Backend for the ABC and using Driver for the concrete implementation, but that’s confusing, because in old PLR Backend meant the concrete implementation, not the spec.

Liquid handling example, why this matters for the Echo (see thread Echo 650 acoustic dispenser — interest in adding support?)

The current LiquidHandlerBackend as many abstract methods. The Echo 650 (acoustic dispenser) dispenses, no tips, no aspiration. With contracts:

  class EchoDriver(CanDispense): ...                              # just dispense
  class STARLHDriver(CanAspirate, CanDispense, CanPickUpTips,     # everything
                     CanDropTips, CanAspirate96, ...): ...

The Echo-specific operations like survey() can be a separate contract (CanSurveyPlate) if other acoustic dispensers also do this.

Finally, I prefer driver over backend, but that has been said before in this thread, also by @CamilloMoschner I think. So:

Layer What it is Example
Capability User-facing frontend ArmCapability, LiquidHandlingCapability
Contract Abstract ABC; the spec CanPickUpResource, CanDispense
Driver Concrete implementation of contracts STARiSWAPDriver, STARDriver, EchoDriver
IO Machine connection STARConnection, Serial, USB

Just some ideas, other naming choices could work just as well.

1 Like