Transporters

Transporters are robotic arms and plate handlers that move labware between positions.

Overview

Transporters in Swarm AI can:

• Move to named positions (teachpoints)
• Pick up and place plates
• Execute multi-step plate transfers
• Be taught new positions interactively

Basic Operations

Moving to Positions

Move to a saved teachpoint:

"Move the robot to source_rack"

Move to predefined positions:

"Move the robot to the home position"
"Move to the safe position"

Pick and Place

Pick up a plate:

"Pick up a plate from source_slot_1"

Place a plate:

"Place the plate at destination_rack"

Combined operation:

"Pick from input_stack and place at shaker_nest"

Gripper Control

"Open the gripper"
"Close the gripper"

Speed Control

Set movement speed (0.0 = stopped, 1.0 = maximum):

"Set the robot speed to 50%"
"What is the current robot speed?"

Emergency Stop

For any unexpected movement:

"Stop the robot immediately"

This halts all motion. The robot may need re-initialization after a halt.

Coordinate Systems

Transporters use two coordinate systems:

Cartesian Coordinates

Position in 3D space with orientation:

Parameter	Description	Unit
x	Left/right position	mm
y	Forward/back position	mm
z	Up/down position	mm
yaw	Rotation around vertical axis	degrees
pitch	Tilt up/down	degrees
roll	Rotation around gripper axis	degrees

Required for: Pick and place operations

Joint Coordinates

Individual joint angles:

Parameter	Description	Unit
rail	Linear rail position (if equipped)	mm
base	Base rotation	degrees
shoulder	Shoulder joint	degrees
elbow	Elbow joint	degrees
wrist	Wrist rotation	degrees

Used for: Waypoints, safe positions, teaching

Teachpoints

Teachpoints are saved positions stored in the Swarm AI database. Instead of specifying coordinates each time, you reference positions by name. This makes it easy to reuse positions and share them across sessions.

Listing Teachpoints

"What teachpoints are saved for the robot?"

Creating Teachpoints

Method 1: From current position

1. Move the robot to the desired position (manually or via free mode)
2. Save the position:

"Save the current position as new_source_rack"

Method 2: With explicit coordinates

"Create a teachpoint called test_position with cartesian coordinates x=100, y=200, z=50"

Updating Teachpoints

"Update source_rack to the current robot position"

Deleting Teachpoints

"Delete the teachpoint called old_position"

Exporting and Importing

Export all teachpoints for backup:

"Export all teachpoints for the robot"

Import teachpoints in bulk (via API):

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "robot-arm",
    "teachpoints": [...],
    "overwrite": false
  }' \
  https://swarm.cheshirelabs.io/api/teachpoints/bulk

Teaching Workflow

Teaching new positions using free mode (freedrive):

Step 1: Enable Free Mode

Enable free mode so you can manually move the robot:

"Enable free mode on all axes"

Or for specific axes:

"Enable free mode on the rail axis only"

Step 2: Position the Robot

Physically guide the robot arm to the desired position. In free mode, the motors allow manual movement.

Step 3: Save the Position

"Save the current position as plate_stack_top"

Choose coordinate type based on use:

• Cartesian (default): For pick/place positions
• Joint: For waypoints or intermediate positions

"Save the current position as waypoint_1 using joint coordinates"

Step 4: Disable Free Mode

"Disable free mode"

Step 5: Test the Position

"Move to plate_stack_top"

Access Configuration

For pick and place operations, teachpoints need access configuration that defines how the robot approaches the position.

Vertical Access

Robot approaches from above (typical for plate nests):

{
  "access_type": "vertical",
  "vertical_clearance": 30
}

The robot will:

1. Move to position with Z + clearance
2. Lower to Z position
3. Grip/release plate
4. Raise back up

Horizontal Access

Robot approaches from the side (for enclosed positions):

{
  "access_type": "horizontal",
  "horizontal_clearance": 50,
  "vertical_clearance": 20
}

The robot will:

1. Move above and in front of position
2. Lower to approach height
3. Move forward horizontally
4. Grip/release plate
5. Retract

Advanced Operations

Single Axis Movement

Move one axis at a time for fine positioning:

"Move the rail axis to 100mm"
"Move the shoulder 5 degrees forward"

Coordinate-Based Movement

For advanced use, move to specific coordinates without a teachpoint:

"Move to cartesian position x=150, y=200, z=100"

Position Queries

"What is the current robot position in cartesian coordinates?"
"What are the current joint angles?"

What's Next?

• Using Claude with Swarm AI - More examples
• MCP Tools Reference - All transporter tools
• Troubleshooting - Common issues