Move

This module provides the base class for mover tools.

CLASS	DESCRIPTION
`Mover`	base class for mover tools

Documentation last updated: 2025-02-22

Mover

Mover(
    *,
    robot_position: Position = Position(),
    home_position: Position = Position(),
    tool_offset: Position = Position(),
    calibrated_offset: Position = Position(),
    scale: float = 1.0,
    deck: Deck | None = None,
    workspace: BoundingVolume | None = None,
    safe_height: float | None = None,
    saved_positions: dict | None = None,
    speed_max: float = 600,
    verbose: bool = False,
    **kwargs,
)

Base class for mover tools.

ATTRIBUTE	DESCRIPTION
`connection_details`	connection details for the device TYPE: `dict`
`device`	device object that communicates with physical tool TYPE: `Device`
`flags`	flags for the class TYPE: `SimpleNamespace[str, bool]`
`is_busy`	whether the device is busy TYPE: `bool`
`is_connected`	whether the device is connected TYPE: `bool`
`verbose`	verbosity of class TYPE: `bool`
`deck`	Deck object for workspace TYPE: `Deck`
`workspace`	workspace bounding box TYPE: `BoundingVolume`
`safe_height`	safe height in terms of robot coordinate system TYPE: `float`
`saved_positions`	dictionary of saved positions TYPE: `dict`
`current_zone_waypoints`	current zone entry waypoints TYPE: `tuple[str, list[Position]]`
`speed`	travel speed of robot TYPE: `float`
`speed_factor`	fraction of maximum travel speed of robot TYPE: `float`
`speed_max`	maximum speed of robot in mm/min TYPE: `float`
`robot_position`	current position of the robot TYPE: `Position`
`home_position`	home position of the robot in terms of robot coordinate system TYPE: `Position`
`tool_offset`	tool offset from robot to end effector TYPE: `Position`
`calibrated_offset`	calibrated offset from robot to work position TYPE: `Position`
`scale`	factor to scale the basis vectors by TYPE: `float`
`tool_position`	robot position of the tool end effector TYPE: `Position`
`work_position`	work position of the robot TYPE: `Position`
`worktool_position`	work position of the tool end effector TYPE: `Position`
`position`	work position of the tool end effector; alias for worktool_position TYPE: `Position`

METHOD	DESCRIPTION
`connect`	connect to the device
`disconnect`	disconnect from the device
`resetFlags`	reset all flags to class attribute _default_flags
`shutdown`	shutdown procedure for tool
`enterZone`	enter a zone on the deck
`exitZone`	exit the current zone on the deck
`halt`	halt robot movement
`home`	make the robot go home
`isFeasible`	checks and returns whether the target coordinates is feasible
`loadDeck`	load Deck layout object to mover
`loadDeckFromDict`	load Deck layout object from dictionary
`loadDeckFromFile`	load Deck layout object from file
`move`	move the robot in a specific axis by a specific value
`moveBy`	move the robot by target direction
`moveTo`	move the robot to target position
`moveToSafeHeight`	move the robot to safe height
`moveRobotTo`	move the robot to target position
`moveToolTo`	move the tool end effector to target position
`reset`	reset the robot
`rotate`	rotate the robot in a specific axis by a specific value
`rotateBy`	rotate the robot by target direction
`rotateTo`	rotate the robot to target orientation
`rotateRobotTo`	rotate the robot to target orientation
`rotateToolTo`	rotate the tool end effector to target orientation
`safeMoveTo`	safe version of moveTo by moving to safe height first
`setSafeHeight`	set safe height for robot
`setSpeedFactor`	set the speed factor of the robot
`setToolOffset`	set the tool offset of the robot
`showWorkspace`	show the workspace of the robot
`transferLabware`	transfer labware from one slot to another
`updateRobotPosition`	update the robot position
`transformRobotToTool`	transform robot coordinates to tool coordinates
`transformRobotToWork`	transform robot coordinates to work coordinates
`transformToolToRobot`	transform tool coordinates to robot coordinates
`transformWorkToRobot`	transform work coordinates to robot coordinates
`calibrate`	calibrate the internal and external coordinate systems

Initialize Mover class

PARAMETER	DESCRIPTION
`robot_position`	current position of the robot. Defaults to Position(). TYPE: `Position` DEFAULT: `Position()`
`home_position`	home position of the robot in terms of robot coordinate system. Defaults to Position(). TYPE: `Position` DEFAULT: `Position()`
`tool_offset`	tool offset from robot to end effector. Defaults to Position(). TYPE: `Position` DEFAULT: `Position()`
`calibrated_offset`	calibrated offset from robot to work position. Defaults to Position(). TYPE: `Position` DEFAULT: `Position()`
`scale`	factor to scale the basis vectors by. Defaults to 1.0. TYPE: `float` DEFAULT: `1.0`
`deck`	Deck object for workspace. Defaults to None. TYPE: `Deck` DEFAULT: `None`
`workspace`	workspace bounding box. Defaults to None. TYPE: `BoundingVolume` DEFAULT: `None`
`safe_height`	safe height in terms of robot coordinate system. Defaults to None. TYPE: `float` DEFAULT: `None`
`speed_max`	maximum speed of robot in mm/min. Defaults to 600. TYPE: `float` DEFAULT: `600`
`verbose`	verbosity of class. Defaults to False. TYPE: `bool` DEFAULT: `False`

calibrated_offset `property`

calibrated_offset: Position

Calibrated offset from robot to work position

connection_details `property`

connection_details: dict

Connection details for the device

home_position `property`

home_position: Position

Home position of the robot

is_busy `property`

is_busy: bool

Whether the device is busy

is_connected `property`

is_connected: bool

Whether the device is connected

position `property`

position: Position

Work position of the tool end effector. Alias for worktool_position

robot_position `property`

robot_position: Position

Current position of the robot

scale `property`

scale: float

Factor to scale the basis vectors by

speed `property`

speed: float

Travel speed of robot

speed_factor `property` `writable`

speed_factor: float

Fraction of maximum travel speed of robot

speed_max `property` `writable`

speed_max: dict[str, float]

Maximum speed(s) of robot

tool_offset `property`

tool_offset: Position

Tool offset from robot to end effector

tool_position `property`

tool_position: Position

Robot position of the tool end effector

verbose `property` `writable`

verbose: bool

Verbosity of class

work_position `property`

work_position: Position

Work position of the robot

worktool_position `property`

worktool_position: Position

Work position of the tool end effector

enter

__enter__()

Context manager enter method

exit

__exit__(exc_type, exc_value, traceback)

Context manager exit method

calibrate `staticmethod`

calibrate(
    internal_points: ndarray, external_points: ndarray
) -> tuple[Position, float]

Calibrate the internal and external coordinate systems

PARAMETER	DESCRIPTION
`internal_points`	internal points TYPE: `ndarray`
`external_points`	external points TYPE: `ndarray`

RETURNS	DESCRIPTION
`tuple[Position, float]`	tuple[Position,float]: calibrated offset and scale

connect

connect()

Connect to the device

disconnect

disconnect()

Disconnect from the device

enterZone

enterZone(zone: str, speed_factor: float | None = None)

Enter a zone on the deck

PARAMETER	DESCRIPTION
`zone`	zone to enter TYPE: `str`
`speed_factor`	fraction of maximum speed to travel at. Defaults to None. TYPE: `float` DEFAULT: `None`

exitZone

exitZone(speed_factor: float | None = None)

Exit the current zone on the deck

PARAMETER	DESCRIPTION
`speed_factor`	fraction of maximum speed to travel at. Defaults to None. TYPE: `float` DEFAULT: `None`

halt

halt() -> Position

Halt robot movement

home

home(axis: str | None = None) -> bool

Make the robot go home

PARAMETER	DESCRIPTION
`axis`	axis to home. Defaults to None. TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	whether the robot successfully homed TYPE: `bool`

isFeasible

isFeasible(
    coordinates: Sequence[float] | ndarray,
    external: bool = True,
    tool_offset: bool = True,
) -> bool

Checks and returns whether the target coordinates is feasible

PARAMETER	DESCRIPTION
`coordinates`	target coordinates TYPE: `Sequence[float] \| ndarray`
`external`	whether the target coordinates are in external coordinates. Defaults to True. TYPE: `bool` DEFAULT: `True`
`tool_offset`	whether to consider the tool offset. Defaults to True. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`bool`	whether the target coordinates are feasible TYPE: `bool`

loadDeck

loadDeck(deck: Deck)

Load Deck layout object to mover

PARAMETER	DESCRIPTION
`deck`	Deck layout object TYPE: `Deck`

loadDeckFromDict

loadDeckFromDict(details: dict[str, Any])

Load Deck layout object from dictionary

PARAMETER	DESCRIPTION
`details`	Deck layout dictionary TYPE: `dict[str, Any]`

loadDeckFromFile

loadDeckFromFile(deck_file: str)

Load Deck layout object from file

PARAMETER	DESCRIPTION
`deck_file`	Deck layout file TYPE: `str`

move

move(
    axis: str,
    by: float,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
    rapid: bool = False,
) -> Position

Move the robot in a specific axis by a specific value

PARAMETER	DESCRIPTION
`axis`	axis to move TYPE: `str`
`by`	displacement to move TYPE: `float`
`speed_factor`	fraction of maximum speed to travel at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`
`rapid`	whether to move rapidly. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Position`	new tool position TYPE: `Position`

moveBy

moveBy(
    by: Sequence[float] | Position | ndarray,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
    rapid: bool = False,
    robot: bool = False,
) -> Position

Move the robot by target direction

PARAMETER	DESCRIPTION
`by`	target direction TYPE: `Sequence[float] \| Position \| ndarray`
`speed_factor`	fraction of maximum speed to travel at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`
`rapid`	whether to move rapidly. Defaults to False. TYPE: `bool` DEFAULT: `False`
`robot`	whether to move the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Position`	new tool/robot position TYPE: `Position`

moveRobotTo

moveRobotTo(
    to: Sequence[float] | Position | ndarray,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
    rapid: bool = False,
) -> Position

Move the robot to target position

PARAMETER	DESCRIPTION
`to`	target position TYPE: `Sequence[float] \| Position`
`speed_factor`	fraction of maximum speed to travel at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`
`rapid`	whether to move rapidly. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Position`	new robot position TYPE: `Position`

moveTo

moveTo(
    to: Sequence[float] | Position | ndarray,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
    rapid: bool = False,
    robot: bool = False,
) -> Position

Move the robot to target position

PARAMETER	DESCRIPTION
`to`	target position TYPE: `Sequence[float] \| Position \| ndarray`
`speed_factor`	fraction of maximum speed to travel at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`
`rapid`	whether to move rapidly. Defaults to False. TYPE: `bool` DEFAULT: `False`
`robot`	whether to move the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Position`	new tool/robot position TYPE: `Position`

moveToSafeHeight

moveToSafeHeight(
    speed_factor: float | None = None,
) -> Position

Move the robot to safe height

PARAMETER	DESCRIPTION
`speed_factor`	fraction of maximum speed to travel at. Defaults to None. TYPE: `float` DEFAULT: `None`

RETURNS	DESCRIPTION
`Position`	new tool position TYPE: `Position`

moveToolTo

moveToolTo(
    to: Sequence[float] | Position | ndarray,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
    rapid: bool = False,
) -> Position

Move the tool end effector to target position

PARAMETER	DESCRIPTION
`to`	target position TYPE: `Sequence[float] \| Position`
`speed_factor`	fraction of maximum speed to travel at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`
`rapid`	whether to move rapidly. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Position`	new tool position TYPE: `Position`

reset

reset()

Reset the robot

resetFlags

resetFlags()

Reset all flags to class attribute _default_flags

rotate

rotate(
    axis: str,
    by: float,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
) -> Rotation

Rotate the robot in a specific axis by a specific value

PARAMETER	DESCRIPTION
`axis`	axis to rotate TYPE: `str`
`by`	angle to rotate TYPE: `float`
`speed_factor`	fraction of maximum speed to rotate at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Rotation`	new tool orientation TYPE: `Rotation`

rotateBy

rotateBy(
    by: Sequence[float] | Rotation | ndarray,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
    robot: bool = False,
) -> Rotation

Rotate the robot by target rotation

PARAMETER	DESCRIPTION
`by`	target rotation TYPE: `Sequence[float] \| Rotation \| ndarray`
`speed_factor`	fraction of maximum speed to rotate at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`
`robot`	whether to rotate the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Rotation`	new tool/robot orientation TYPE: `Rotation`

rotateRobotTo

rotateRobotTo(
    to: Sequence[float] | Rotation,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
) -> Rotation

Rotate the robot to target orientation

PARAMETER	DESCRIPTION
`to`	target orientation TYPE: `Sequence[float] \| Rotation`
`speed_factor`	fraction of maximum speed to rotate at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Rotation`	new robot orientation TYPE: `Rotation`

rotateTo

rotateTo(
    to: Sequence[float] | Rotation | ndarray,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
    robot: bool = False,
) -> Rotation

Rotate the robot to target orientation

PARAMETER	DESCRIPTION
`to`	target orientation TYPE: `Sequence[float] \| Rotation \| ndarray`
`speed_factor`	fraction of maximum speed to rotate at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`
`robot`	whether to rotate the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Rotation`	new tool/robot orientation TYPE: `Rotation`

rotateToolTo

rotateToolTo(
    to: Sequence[float] | Rotation,
    speed_factor: float | None = None,
    *,
    jog: bool = False,
) -> Rotation

Rotate the tool end effector to target orientation

PARAMETER	DESCRIPTION
`to`	target orientation TYPE: `Sequence[float] \| Rotation`
`speed_factor`	fraction of maximum speed to rotate at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Rotation`	new tool orientation TYPE: `Rotation`

safeMoveTo

safeMoveTo(
    to: Sequence[float] | Position | ndarray,
    speed_factor_lateral: float | None = None,
    speed_factor_up: float | None = None,
    speed_factor_down: float | None = None,
    *,
    jog: bool = False,
    rotation_before_lateral: bool = False,
    robot: bool = False,
) -> Position

Safe version of moveTo by moving in to safe height first

PARAMETER	DESCRIPTION
`to`	target position TYPE: `Sequence[float] \| Position \| ndarray`
`speed_factor_lateral`	fraction of maximum speed to travel laterally at. Defaults to None. TYPE: `float` DEFAULT: `None`
`speed_factor_up`	fraction of maximum speed to travel up at. Defaults to None. TYPE: `float` DEFAULT: `None`
`speed_factor_down`	fraction of maximum speed to travel down at. Defaults to None. TYPE: `float` DEFAULT: `None`
`jog`	whether to jog the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`
`rotation_before_lateral`	whether to rotate before moving laterally. Defaults to False. TYPE: `bool` DEFAULT: `False`
`robot`	whether to move the robot. Defaults to False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Position`	new tool/robot position TYPE: `Position`

setSafeHeight

setSafeHeight(height: float)

Set safe height for robot

PARAMETER	DESCRIPTION
`height`	safe height in terms of robot coordinate system TYPE: `float`

setSpeedFactor

setSpeedFactor(
    speed_factor: float, *, persist: bool = True
)

Set the speed factor of the robot

PARAMETER	DESCRIPTION
`speed_factor`	fraction of maximum speed to travel at TYPE: `float`
`persist`	whether to persist the speed factor. Defaults to True. TYPE: `bool` DEFAULT: `True`

setToolOffset

setToolOffset(
    offset: Sequence[float] | Position | ndarray,
) -> Position

Set the tool offset of the robot

PARAMETER	DESCRIPTION
`offset`	tool offset TYPE: `Sequence[float] \| Position \| ndarray`

RETURNS	DESCRIPTION
`Position`	old tool offset TYPE: `Position`

showWorkspace

showWorkspace() -> tuple[Figure, Axes]

Show the workspace of the robot

RETURNS	DESCRIPTION
`tuple[Figure, Axes]`	tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]: matplotlib figure, axes

shutdown

shutdown()

Shutdown procedure for tool

transferLabware

transferLabware(
    from_slot: str,
    to_slot: str,
    src_offset: Sequence[float] | ndarray = (0, 0, 0),
    dst_offset: Sequence[float] | ndarray = (0, 0, 0),
    speed_factor: float | None = None,
)

Transfer labware from one slot to another

PARAMETER	DESCRIPTION
`from_slot`	source slot name TYPE: `str`
`to_slot`	destination slot name TYPE: `str`
`src_offset`	offset from top of labware at source. Defaults to (0,0,0). TYPE: `Sequence[float] \| ndarray` DEFAULT: `(0, 0, 0)`
`dst_offset`	offset from center of destination slot. Defaults to (0,0,0). TYPE: `Sequence[float] \| ndarray` DEFAULT: `(0, 0, 0)`
`speed_factor`	speed factor. Defaults to None. TYPE: `float` DEFAULT: `None`

transformRobotToTool `staticmethod`

transformRobotToTool(
    internal_position: Position, offset: Position
) -> Position

Transform robot coordinates to tool coordinates

PARAMETER	DESCRIPTION
`internal_position`	robot position TYPE: `Position`
`offset`	tool offset TYPE: `Position`

RETURNS	DESCRIPTION
`Position`	tool position TYPE: `Position`

transformRobotToWork `staticmethod`

transformRobotToWork(
    internal_position: Position,
    offset: Position,
    scale: float = 1.0,
) -> Position

Transform robot coordinates to work coordinates

PARAMETER	DESCRIPTION
`internal_position`	robot position TYPE: `Position`
`offset`	calibrated offset TYPE: `Position`
`scale`	scale factor. Defaults to 1.0. TYPE: `float` DEFAULT: `1.0`

RETURNS	DESCRIPTION
`Position`	work position TYPE: `Position`

transformToolToRobot `staticmethod`

transformToolToRobot(
    external_position: Position, offset: Position
) -> Position

Transform tool coordinates to robot coordinates

PARAMETER	DESCRIPTION
`external_position`	tool position TYPE: `Position`
`offset`	tool offset TYPE: `Position`

RETURNS	DESCRIPTION
`Position`	robot position TYPE: `Position`

transformWorkToRobot `staticmethod`

transformWorkToRobot(
    external_position: Position,
    offset: Position,
    scale: float = 1.0,
) -> Position

Transform work coordinates to robot coordinates

PARAMETER	DESCRIPTION
`external_position`	work position TYPE: `Position`
`offset`	calibrated offset TYPE: `Position`
`scale`	scale factor. Defaults to 1.0. TYPE: `float` DEFAULT: `1.0`

RETURNS	DESCRIPTION
`Position`	robot position TYPE: `Position`

updateRobotPosition

updateRobotPosition(
    by: Position | Rotation | None = None,
    to: Position | Rotation | None = None,
) -> Position

Update the robot position

PARAMETER	DESCRIPTION
`by`	move/rotate by. Defaults to None. TYPE: `Position \| Rotation` DEFAULT: `None`
`to`	move/rotate to. Defaults to None. TYPE: `Position \| Rotation` DEFAULT: `None`

RETURNS	DESCRIPTION
`Position`	new robot position TYPE: `Position`