Expose STARBackend.request_iswap_relative_wrist_orientation()

[BioCam]

No description provided.

[BioCam]

Here I am proposing the clear distinction between

• RelativeWristOrientation (what has previously been named just WristOrientation) ... wrist orientation in relation to the iSWAP arm / RotationDrive
• AbsoluteWristOrientation ... wrist orientation in relation to the user / front of the machine (not captured yet in the machine model I believe, TODO)

[BioCam]

Why "relative" wrist? It's just the wrist drive. It is always relative to rotation drive

That is not true: the wrist can also be referenced to the "absolute" orientation, i.e. in the current PLR definition that is the orientation in reference to the liquid_handler (used in e.g. get_absolute_location, i.e. in reference to the liquid handler).

I added a couple of examples into the docstring to explain this more:

    """
    Request the relative iSWAP wrist orientation.
    This is the orientation of the iSWAP wrist in relation to the iSWAP arm/rotation drive.

    e.g.:
    1) iSWAP RotationDrive.Front (i.e. pointing to the front of the machine) +
       iSWAP RelativeWristOrientation.STRAIGHT (i.e. wrist is also pointing to the front)

    2) iSWAP RotationDrive.LEFT (i.e. pointing to the left of the machine) +
       iSWAP RelativeWristOrientation.STRAIGHT (i.e. wrist is also pointing to the left)

    3) iSWAP RotationDrive.Front (i.e. pointing to the back of the machine) +
       iSWAP RelativeWristOrientation.RIGHT (i.e. wrist is pointing to the left !)

    The relative wrist orientation is reported as a motor position increment by the STAR
    firmware. This value is mapped to a `RelativeWristOrientation` enum member.

    Returns:
        RelativeWristOrientation: The interpreted wrist orientation
        (e.g., RIGHT, STRAIGHT, LEFT, REVERSE).
    """

Interestingly, this "absolute" direction is what GripDirection means in lh.pick_up_resource and lh.drop_resource.
But I am not aware of a direct firmware command to request the absolute wrist direction, only the relative wrist direction to the iSWAP_arm / rotation drive.

For automators thinking in terms of wrist orientation relative to the iSWAP arm/rotation drive is very confusing because one constantly has to think about both rotation motors' positions (see docstring example no 3).
In contrast, the absolute wrist orientation is always relative to the programmer standing in front of the machine (i.e. the same as the liquid handler coordinate system).
No matter whether RotationDriveOrientation is RIGHT, FRONT or LEFT, the absolute wrist orientation options will always be the same, making them more predictable, making them more useful for programming.

[BioCam]

I've made this infographic to explain the 12 possible iSWAP configurations and what their relative and absolute wrist orientations are:

[rickwierenga]

Tbh, I am not a huge fan of "relative" in the name because it is just the orientation of the wrist itself, that has nothing to do with the deck. It says wrist drive, meaning that specific component.

GripDirection is the type we use for "absolute" (wrt Deck) space

I don't think we should be changing the names of unique Hamilton components in the backend. They are not ours to name. Instead we can work with our own abstractions (like GripD.) that have more direct utility

[rickwierenga]

No matter whether RotationDriveOrientation is RIGHT, FRONT or LEFT, the absolute wrist orientation options will always be the same, making them more predictable, making them more useful for programming.

That is why iswap_rotate uses GripDirection