Transporters

Transporters are robotic arms that move labware between devices. They use teachpoints - named positions that define where to pick and place plates.

Basic Setup

from orca.sdk.devices import Transporter
from cheshire_drivers import PreciseFlexDriver

arm = Transporter(
    name="robot_arm",
    driver=PreciseFlexDriver(ip="192.168.1.100"),
    load_positions="teachpoints/robot_arm.json"
)

The load_positions parameter accepts either a file path (string) or a list of Teachpoint objects.

Coordinate Systems

Teachpoints can use two coordinate systems:

Cartesian Coordinates

Required for pick/place operations. Defines position in world space:

Field	Description
x, y, z	Position in millimeters
yaw, pitch, roll	Rotation in degrees
orientation	"left" or "right" (elbow configuration)
access	Reference to an access config name

{
  "name": "shaker_1",
  "x": 100.0,
  "y": 200.0,
  "z": 50.0,
  "yaw": 180.0,
  "pitch": 90.0,
  "roll": 0.0,
  "orientation": "right",
  "access": "default_vertical"
}

Joint Coordinates

For waypoints only - not for pick/place. Defines joint angles directly:

Field	Description
base	Base rotation (degrees)
shoulder	Shoulder angle (degrees)
elbow	Elbow angle (degrees)
wrist	Wrist angle (degrees)
rail	Rail position (mm, if present)

{
  "name": "safe_waypoint",
  "base": 90.0,
  "shoulder": 45.0,
  "elbow": 135.0,
  "wrist": 0.0
}

Why can't joint coordinates be used for pick/place? Access patterns (approach and retract movements) are calculated in world space. Joint coordinates don't provide the spatial reference needed for these calculations.

Access Configurations

Access configs define how the robot approaches and retracts from a position. Define them once and reference by name.

Vertical Access

For positions accessed from above (deck positions, stacks):

{
  "default_vertical": {
    "access_type": "vertical",
    "gripper_offset": 20.0,
    "vertical_clearance": 30.0
  }
}

Parameter	Description
vertical_clearance	Height above the teachpoint to approach/depart from (mm)
gripper_offset	Plate thickness compensation (mm)

Pick motion sequence:

1. Move to teachpoint + vertical_clearance (above the point)
2. Descend to teachpoint
3. Grip at teachpoint + gripper_offset
4. Lift to teachpoint + vertical_clearance
5. Depart

Horizontal Access

For positions accessed from the side (hotel slots, carriers):

{
  "default_horizontal": {
    "access_type": "horizontal",
    "gripper_offset": 20.0,
    "horizontal_clearance": 100.0,
    "vertical_clearance": 30.0
  }
}

Parameter	Description
horizontal_clearance	Distance outside the slot to start from (mm)
vertical_clearance	Lift height AFTER horizontal exit (mm)
gripper_offset	Plate thickness compensation (mm)

Pick motion sequence:

1. Position at teachpoint + horizontal_clearance (outside slot)
2. Enter horizontally to teachpoint
3. Grip at teachpoint + gripper_offset
4. Retract horizontally to teachpoint - horizontal_clearance
5. Lift to teachpoint + vertical_clearance
6. Depart

Gateway Waypoints

Gateways are safe intermediate positions the robot passes through when approaching or departing a destination. They prevent collisions and ensure predictable motion paths.

Add a gateway field to any teachpoint to specify a waypoint to pass through first:

{
  "name": "nest_1",
  "x": 100.0,
  "y": 0.0,
  "z": 50.0,
  "yaw": 180.0,
  "pitch": 90.0,
  "roll": 0.0,
  "orientation": "right",
  "access": "default_vertical",
  "gateway": "safe_zone"
}

When moving to nest_1, the robot first moves to safe_zone, then proceeds to the final position. When leaving, the robot retraces through the gateway in reverse.

Gateways can be chained - if safe_zone has its own gateway, the robot traverses the full path.

The safe_zone waypoint must be defined in the same teachpoint file (see file format below).

Teachpoint File Format

Complete example with access configs, cartesian positions, and joint waypoints:

{
  "access_configs": {
    "default_vertical": {
      "access_type": "vertical",
      "gripper_offset": 20.0,
      "vertical_clearance": 30.0
    },
    "hotel_access": {
      "access_type": "horizontal",
      "gripper_offset": 20.0,
      "horizontal_clearance": 100.0,
      "vertical_clearance": 40.0
    }
  },
  "teachpoints": [
    {
      "name": "shaker_1",
      "x": 100.0,
      "y": 200.0,
      "z": 50.0,
      "yaw": 180.0,
      "pitch": 90.0,
      "roll": 0.0,
      "orientation": "right",
      "access": "default_vertical",
      "gateway": "safe_waypoint"
    },
    {
      "name": "hotel_slot_1",
      "x": 300.0,
      "y": 150.0,
      "z": 100.0,
      "yaw": 90.0,
      "pitch": 90.0,
      "roll": 0.0,
      "orientation": "left",
      "access": "hotel_access"
    },
    {
      "name": "safe_waypoint",
      "base": 90.0,
      "shoulder": 30.0,
      "elbow": 150.0,
      "wrist": 0.0
    }
  ]
}

Elbow Orientation

The orientation field specifies the elbow configuration:

• "right" - Elbow points right (from above view)
• "left" - Elbow points left (from above view)

Some positions can only be reached with a specific orientation depending on arm geometry.

Initialization

When a transporter initializes, it:

1. Connects to hardware
2. Homes all axes
3. Moves to safe position

await system.initialize_all()  # Initializes all devices including transporters

Human Transfer

For manual plate movements, use HumanTransfer:

from orca.sdk.devices import HumanTransfer

human = HumanTransfer("operator", "teachpoints/manual_positions.json")

HumanTransfer is a specialized Transporter that prompts the operator to manually move plates instead of using a robotic arm. The operator sees source and destination positions and confirms each transfer.

Next Steps

• Devices - Other device types
• Actions - Operations on devices
• Running Workflows - Simulation and execution options