Skip to main content

Transporters

A transporter is anything that moves labware between locations — typically a robotic arm. Every topology with multiple devices needs at least one transporter so the runtime can move labware between methods.

Defining a transporter​

from orca.resource_models.transporter import Transporter
from cheshire_drivers import AccessConfig, CartesianCoordinates, Teachpoint

c = CartesianCoordinates
vertical = AccessConfig(name="default_vertical", access_type="vertical")
stores.access_configs(seed=[vertical])

teachpoints = [
    Teachpoint("stacker",  c(0,    200, 300, 0, 90, 180), orientation="right", access=vertical),
    Teachpoint("shaker",   c(400,  200, 300, 0, 90, 180), orientation="right", access=vertical),
    Teachpoint("sealer",   c(800,  200, 300, 0, 90, 180), orientation="right", access=vertical),
    Teachpoint("waste",    c(1200, 200, 200, 0, 90, 180), orientation="right", access=vertical),
]

arm = Transporter(
    "robotic_arm",
    teachpoint_store=stores.teachpoints("robotic_arm", seed=teachpoints),
)

A transporter needs a name and a teachpoint_store. The store maps location names to physical coordinates.

Teachpoints​

A Teachpoint's first argument is position_id (the location name this teachpoint reaches), followed by a coordinate and optional access metadata:

Teachpoint(
    "sealer",                                  # position_id (positional)
    coordinates=c(1300, 200, 300, 0, 90, 180),
    orientation="right",
    access=sealer_access_config,    # optional
)

Cartesian teachpoints must specify orientation ("left" or "right"); a Cartesian teachpoint with orientation=None raises at construction. Cartesian coordinates carry (x, y, z, yaw, pitch, roll).

Cartesian vs joint coordinates​

Pick/place locations use CartesianCoordinates (orientation required, supports access patterns). Waypoints along a path use JointCoordinates (per-joint values; no orientation, no access pattern). Both import from cheshire_drivers.

Capturing teachpoints​

In production, you capture teachpoints by physically jogging the arm to each location and recording the coordinates. The values shown in examples are placeholders.

TODO: teachpoint capture workflow — how to jog, save, and seed the store from your real lab.

Access configs​

Some devices need a special approach pattern (horizontal slide-in for a plate sealer, vertical drop for a centrifuge bucket, etc.). An AccessConfig tells the transporter how to enter and exit the location:

from cheshire_drivers import AccessConfig

sealer_access = AccessConfig(
    name="sealer_horizontal",
    access_type="horizontal",
    gripper_offset=25.0,
    horizontal_clearance=120.0,
    vertical_clearance=30.0,
)

AccessConfig fields: name, access_type ("vertical" or "horizontal"), gripper_offset (default 20.0), vertical_clearance (default 20.0), horizontal_clearance (default 100.0). Import it from cheshire_drivers.

Seed access configs into the store once and reference the same one from many teachpoints (access=vertical):

from cheshire_drivers import AccessConfig

vertical = AccessConfig(name="default_vertical", access_type="vertical")
horizontal = AccessConfig(name="default_horizontal", access_type="horizontal")
stores.access_configs(seed=[vertical, horizontal])

Persistence caveat: pass a named AccessConfig via access=..., not inline access params. A teachpoint built with inline params (access_type=..., gripper_offset=...) has access_config_name=None and is rejected by persistent teachpoint stores. Always reference a named config so the teachpoint round-trips through storage.

Waypoint gateways​

A Teachpoint also accepts a gateway argument: the name of a waypoint to route through before/after pick and place. Use it to chain a safe approach path (typically JointCoordinates waypoints) ahead of a Cartesian pick/place point.

Multiple transporters​

A topology can have multiple transporters — common in larger systems with handoff points between two arms. The runtime picks the right transporter for each move based on which arm can reach both endpoints.

TODO: handoff topology example.

Where to go next​

  • Devices — the locations the transporter moves between.
  • Topology — putting it all together.