Commands

Commands are the data structures that you send to your fleet as instructions.

A T-code script is a list of commands, typically beginning with a chunk of ADD_*** commands to define the entities that will be used in the script, then followed by various action commands to manipulate those entities.

Tip

An important concept to understand before diving into T-code commands is the ValueWithUnits class, used in many of the following commands to represent physical quantities such as distances, speeds, and volumes.

See Common Types for full documentation of ValueWithUnits and related types.

TCode command schemas: data structures sent to the fleet as instructions.

class tcode_api.schemas.commands.ADD_LABWARE(**data)

Find a matching labware on the fleet and assign it the given id.

Raises:

ValidatorError – ValidatorErrorCode.ID_EXISTS if id is already registered to a labware.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.ADD_PIPETTE_TIP_GROUP(**data)

Find a matching group of pipette tips on the fleet and assign it the given id.

The resolved pipette tip group is scoped to the robot identified by robot_id.

Raises:

ValidatorError – ValidatorErrorCode.ID_EXISTS if id is already registered to a pipette tip group.

Parameters:

  • schema_version (Literal[2])

  • type (Literal['ADD_PIPETTE_TIP_GROUP'])

  • robot_id (str)

  • id (str)

  • descriptor (PipetteTipGroupDescriptor)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.ADD_ROBOT(**data)

Find a matching robot on the fleet and assign it the given id.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['ADD_ROBOT'])

  • id (str)

  • descriptor (RobotDescriptor)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.ADD_TOOL(**data)

Find a matching tool on the fleet and assign it the given id.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.ASPIRATE(**data)

Aspirate a given fluid volume at a given speed into the target robot’s pipette.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.CALIBRATE_LABWARE_HEIGHT(**data)

Tune the height of a target labware by probing.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.CALIBRATE_LABWARE_HOLDER(**data)

Calibrate the position of a target labware holder (deck slot) on the target robot by probing or by teaching.

  • If a probe is held by the robot, the calibration will be performed by probing.

  • If a pipette is held by the robot, the calibration will be performed by teaching.

    • Only X, Y, and rotation around Z will be calibrated.

    • A tip box must be registered in the target holder

The pipette teach procedure is as follows: - Single Channel Pipette:

  • Move the pipette manifold to the center of the A1 tip location

  • Confirm via the UI that the pipette is in position

  • Move the pipette manifold to the center of the H12 tip location

  • Confirm via the UI that the pipette is in position

  • 8-Channel Pipette:

    • Move the pipette manifold to the center of the A1 tip location

    • Confirm via the UI that the pipette is in position

    • Move the pipette manifold to the center of the A12 tip location

    • Confirm via the UI that the pipette is in position

NOTE: The UI confirmation steps are done via a websocket connection to the Tcode server

Raises:

  • ValidatorError – ValidatorErrorCode.ID_NOT_FOUND if any of the following are true: * robot_id is not registered to a robot * The labware holder id referenced in location is not registered on the target robot

  • ValidatorError – ValidatorErrorCode.UNEXPECTED_TOOL if the targeted robot has a tool mounted that is not compatible with probing or teaching.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['CALIBRATE_LABWARE_HOLDER'])

  • robot_id (str)

  • location (LocationAsLabwareHolder)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.CALIBRATE_LABWARE_WELL_DEPTH(**data)

Tune the depth of a target labware’s well by probing.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.CALIBRATE_TOOL(**data)

Calibrate the target robot’s currently held tool for probing.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['CALIBRATE_TOOL'])

  • robot_id (str)

  • z_only (bool)

  • persistent (bool)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.COMMENT(**data)

A human-readable comment in the TCode script.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['COMMENT'])

  • text (str)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.CREATE_LABWARE(**data)

Create a new physical labware on the targeted robot’s deck.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.DELETE_LABWARE(**data)

Physically remove a labware from the robot’s deck.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['DELETE_LABWARE'])

  • robot_id (str)

  • labware_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Identifier for a target piece of ANSI-SLAS-compatible labware, assigned by previous :class:``ADD_LABWARE`` command.')])

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.DISCARD_PIPETTE_TIP_GROUP(**data)

Dispose of the currently held pipette tip group.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['DISCARD_PIPETTE_TIP_GROUP'])

  • robot_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.DISPENSE(**data)

Dispense a given fluid volume at a given speed.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.MOVE_GRIPPER(**data)

Manually drive the target robot’s gripper.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['MOVE_GRIPPER'])

  • robot_id (str)

  • gripper_state_type (int)

  • finger_separation (ValueWithUnits | None)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.MOVE_TO_JOINT_POSE(**data)

Move the robot to the specified joint positions.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['MOVE_TO_JOINT_POSE'])

  • robot_id (str)

  • joint_positions (list[ValueWithUnits])

  • relative (bool)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.MOVE_TO_LOCATION(**data)

Move the robot’s control point to a specified location.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.PAUSE(**data)

Pause execution of the target robot until manually resumed.

While WAIT delays a target robot for a set duration, PAUSE halts the target robot until the user manually resumes execution. To pause the entire fleet, schedule a PAUSE for each robot using a sync_group so they pause together.

Parameters:

  • schema_version (Literal[2])

  • type (Literal['PAUSE'])

  • robot_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.PICK_UP_LABWARE(**data)

Pick up a labware with the robot’s plate gripper.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['PICK_UP_LABWARE'])

  • robot_id (str)

  • labware_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Identifier for a target piece of ANSI-SLAS-compatible labware, assigned by previous :class:``ADD_LABWARE`` command.')])

  • grasp_type (str)

  • offset_transform (Annotated[list[list[float]], FieldInfo(annotation=NoneType, required=True, description='A 3D 4x4 transformation matrix represented in row-major order. Used to represent the position and orientation in 3D space.')])

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.PICK_UP_PIPETTE_TIP(**data)

Pick up pipette tip(s) at the specified location.

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.PUT_DOWN_LABWARE(**data)

Put down the currently held labware.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['PUT_DOWN_LABWARE'])

  • robot_id (str)

  • holder (Annotated[LabwareHolderName | LabwareId, FieldInfo(annotation=NoneType, required=True, description='Union type of all valid LabwareHolder specifications.', discriminator='type')])

  • offset_transform (Annotated[list[list[float]], FieldInfo(annotation=NoneType, required=True, description='A 3D 4x4 transformation matrix represented in row-major order. Used to represent the position and orientation in 3D space.')])

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.PUT_DOWN_PIPETTE_TIP(**data)

Put down the currently held pipette tip(s).

Parameters:
model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.REMOVE_LABWARE_LID(**data)

Remove the lid from the target labware.

Parameters:

  • schema_version (Literal[2])

  • type (Literal['REMOVE_LABWARE_LID'])

  • robot_id (str)

  • labware_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Identifier for a target piece of ANSI-SLAS-compatible labware, assigned by previous :class:``ADD_LABWARE`` command.')])

  • storage_holder (Annotated[LabwareHolderName | LabwareId, FieldInfo(annotation=NoneType, required=True, description='Union type of all valid LabwareHolder specifications.', discriminator='type')] | None)

  • offset_transform (Annotated[list[list[float]], FieldInfo(annotation=NoneType, required=True, description='A 3D 4x4 transformation matrix represented in row-major order. Used to represent the position and orientation in 3D space.')])

  • grasp_type (str)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.REPLACE_LABWARE_LID(**data)

Replace the lid on the target labware.

Parameters:

  • schema_version (Literal[2])

  • type (Literal['REPLACE_LABWARE_LID'])

  • robot_id (str)

  • labware_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Identifier for a target piece of ANSI-SLAS-compatible labware, assigned by previous :class:``ADD_LABWARE`` command.')])

  • lid_id (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Identifier for the targeted lid of a piece of ANSI-SLAS-compatible labware, assigned by previous :class:``ADD_LABWARE`` command via the ``lid_id`` argument.')])

  • offset_transform (Annotated[list[list[float]], FieldInfo(annotation=NoneType, required=True, description='A 3D 4x4 transformation matrix represented in row-major order. Used to represent the position and orientation in 3D space.')])

  • grasp_type (str)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.RETRIEVE_PIPETTE_TIP_GROUP(**data)

Pick up a pipette tip group using the held pipette.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['RETRIEVE_PIPETTE_TIP_GROUP'])

  • robot_id (str)

  • id (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Identifier for a target pipette tip group, assigned by previous :class:``ADD_PIPETTE_TIP_GROUP`` command.')])

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.RETRIEVE_TOOL(**data)

Pick up the target tool using the robot’s empty flange.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['RETRIEVE_TOOL'])

  • robot_id (str)

  • id (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Identifier for a target robot tool, assigned by previous :class:``ADD_TOOL`` command.')])

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.RETURN_PIPETTE_TIP_GROUP(**data)

Return the currently held pipette tip group to its origin.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['RETURN_PIPETTE_TIP_GROUP'])

  • robot_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.RETURN_TOOL(**data)

Return the currently held tool to the tool rack.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['RETURN_TOOL'])

  • robot_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.SEND_WEBHOOK(**data)

Send an HTTP webhook request.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['SEND_WEBHOOK'])

  • pause_execution (bool)

  • ignore_external_error (bool)

  • url (str)

  • payload (str | None)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.SWAP_TO_TOOL(**data)

Return the currently held tool, then pick up the target tool.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['SWAP_TO_TOOL'])

  • robot_id (str)

  • id (Annotated[str, FieldInfo(annotation=NoneType, required=True, description='Identifier for a target robot tool, assigned by previous :class:``ADD_TOOL`` command.')])

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tcode_api.schemas.commands.WAIT(**data)

Delay execution for a specified duration.

Parameters:

  • schema_version (Literal[1])

  • type (Literal['WAIT'])

  • robot_id (str)

  • duration (ValueWithUnits)

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].