Entities¶
Entities are the core objects that can be referenced in TCode commands. This includes tools, robots, labware, and more.
Entities have up to four actions associated with them: Creation, Reference, Resolution, and Deletion.
Entity Creation¶
CREATE_*** TCode commands manipulate the fleet state. For example, suppose you want a biologist to add a specific labware to a robot’s deck. Here, you would use CREATE_LABWARE. If you want a biologist to remove a labware from a fleet, you would use DELETE_LABWARE.
Note
Currently, only CREATE_LABWARE is implemented. Tools and robots are created when your fleet controller starts up, and pipette tips are implicitly created when you call CREATE_LABWARE with a PipetteTipRack description, and full=True.
Relevant TCode Commands
Entity Reference¶
ADD_*** TCode commands pair an entity with a identifier, so that you can reference that entity in later commands. For example, calling ADD_LABWARE(id_a, ...) allows you to use id_a in later commands such as PICK_UP_LABWARE(***, id_a). For more details, see Concept: Entity Resolution.
Relevant TCode Commands
Entity Deletion¶
DELETE_*** TCode commands remove an entity from the fleet state. For example, calling DELETE_LABWARE(id_a) removes the labware associated with id_a from the robot’s deck.
Note
Currently, only DELETE_LABWARE is implemented. Tools and robots are never removed once detected at the start of the script, and pipette_tips are both implicitly deleted when you call DELETE_LABWARE on a pipette tip rack and when you call DISCARD_PIPETTE_TIPS`.
Documentation¶
Data structures for defining various robot-related entities in TCode.
- TCode entites are various objects that can be referenced in TCode commands:
Robots
Tools
Labware Holders
Labware
- note:
labware are complex enough that they have their own sub-module: tcode_api.api.labware
- pydantic model tcode_api.api.entity.PipetteTipGroupDescriptor¶
Grid layout of pipette tips.
Show JSON schema
{ "title": "PipetteTipGroupDescriptor", "description": "Grid layout of pipette tips.", "type": "object", "properties": { "type": { "const": "PipetteTipGroup", "default": "PipetteTipGroup", "title": "Type", "type": "string" }, "row_count": { "title": "Row Count", "type": "integer" }, "column_count": { "title": "Column Count", "type": "integer" }, "pipette_tip_tags": { "items": { "type": "string" }, "title": "Pipette Tip Tags", "type": "array" }, "pipette_tip_named_tags": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "title": "Pipette Tip Named Tags", "type": "object" } }, "required": [ "row_count", "column_count" ] }
- Config:
strict: bool = True
extra: str = ignore
- Fields:
-
field type:
Literal['PipetteTipGroup'] = 'PipetteTipGroup'¶
-
field row_count:
Annotated[int] [Required]¶
-
field column_count:
Annotated[int] [Required]¶
-
field pipette_tip_tags:
list[str] [Optional]¶
-
field pipette_tip_named_tags:
dict[str,str|int|float|bool] [Optional]¶
- pydantic model tcode_api.api.entity.ProbeDescriptor¶
Show JSON schema
{ "title": "ProbeDescriptor", "type": "object", "properties": { "type": { "const": "Probe", "default": "Probe", "title": "Type", "type": "string" } } }
- Config:
strict: bool = True
extra: str = ignore
- Fields:
-
field type:
Literal['Probe'] = 'Probe'¶
- pydantic model tcode_api.api.entity.GripperDescriptor¶
Show JSON schema
{ "title": "GripperDescriptor", "type": "object", "properties": { "type": { "const": "Gripper", "default": "Gripper", "title": "Type", "type": "string" } } }
- Config:
strict: bool = True
extra: str = ignore
- Fields:
-
field type:
Literal['Gripper'] = 'Gripper'¶
- pydantic model tcode_api.api.entity.SingleChannelPipetteDescriptor¶
Show JSON schema
{ "title": "SingleChannelPipetteDescriptor", "type": "object", "properties": { "min_volume": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "max_volume": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "max_speed": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "type": { "const": "SingleChannelPipette", "default": "SingleChannelPipette", "title": "Type", "type": "string" } }, "$defs": { "ValueWithUnits": { "description": "A numeric value with associated units.\n\n:note: The following values are all equivalent:\n\n ``ValueWithUnits(magnitude=0.005, units=\"L\")``\n\n ``ValueWithUnits(magnitude=5, units=\"mL\")``\n\n ``ValueWithUnits(magnitude=5000, units=\"uL\")``\n\n ``ValueWithUnits(magnitude=5000, units=\"mm\u00b3\")``\n\n:note: In the python implementation, ``pint`` is used to resolve units. see `tcode_api.units`.", "properties": { "type": { "const": "ValueWithUnits", "default": "ValueWithUnits", "title": "Type", "type": "string" }, "magnitude": { "title": "Magnitude", "type": "number" }, "units": { "title": "Units", "type": "string" } }, "required": [ "magnitude", "units" ], "title": "ValueWithUnits", "type": "object" } } }
- Config:
strict: bool = True
extra: str = ignore
- Fields:
-
field type:
Literal['SingleChannelPipette'] = 'SingleChannelPipette'¶
- pydantic model tcode_api.api.entity.EightChannelPipetteDescriptor¶
Show JSON schema
{ "title": "EightChannelPipetteDescriptor", "type": "object", "properties": { "min_volume": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "max_volume": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "max_speed": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "type": { "const": "EightChannelPipette", "default": "EightChannelPipette", "title": "Type", "type": "string" } }, "$defs": { "ValueWithUnits": { "description": "A numeric value with associated units.\n\n:note: The following values are all equivalent:\n\n ``ValueWithUnits(magnitude=0.005, units=\"L\")``\n\n ``ValueWithUnits(magnitude=5, units=\"mL\")``\n\n ``ValueWithUnits(magnitude=5000, units=\"uL\")``\n\n ``ValueWithUnits(magnitude=5000, units=\"mm\u00b3\")``\n\n:note: In the python implementation, ``pint`` is used to resolve units. see `tcode_api.units`.", "properties": { "type": { "const": "ValueWithUnits", "default": "ValueWithUnits", "title": "Type", "type": "string" }, "magnitude": { "title": "Magnitude", "type": "number" }, "units": { "title": "Units", "type": "string" } }, "required": [ "magnitude", "units" ], "title": "ValueWithUnits", "type": "object" } } }
- Config:
strict: bool = True
extra: str = ignore
- Fields:
-
field type:
Literal['EightChannelPipette'] = 'EightChannelPipette'¶
- pydantic model tcode_api.api.entity.LabwareHolderDescriptor¶
Descriptor for an entity that can hold labware.
Show JSON schema
{ "title": "LabwareHolderDescriptor", "description": "Descriptor for an entity that can hold labware.", "type": "object", "properties": { "type": { "const": "LabwareHolder", "default": "LabwareHolder", "title": "Type", "type": "string" } } }
- Fields:
-
field type:
Literal['LabwareHolder'] = 'LabwareHolder'¶
- pydantic model tcode_api.api.entity.ToolHolderDescriptor¶
Descriptor for an entity that can hold tools.
Show JSON schema
{ "title": "ToolHolderDescriptor", "description": "Descriptor for an entity that can hold tools.", "type": "object", "properties": { "type": { "const": "ToolHolder", "default": "ToolHolder", "title": "Type", "type": "string" } } }
- Fields:
-
field type:
Literal['ToolHolder'] = 'ToolHolder'¶
- pydantic model tcode_api.api.entity.RobotDescriptor¶
Descriptor for a robot in the fleet.
Show JSON schema
{ "title": "RobotDescriptor", "description": "Descriptor for a robot in the fleet.", "type": "object", "properties": { "type": { "const": "Robot", "default": "Robot", "title": "Type", "type": "string" }, "serial_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Serial Number" }, "tools": { "additionalProperties": { "discriminator": { "mapping": { "EightChannelPipette": "#/$defs/EightChannelPipetteDescriptor", "Gripper": "#/$defs/GripperDescriptor", "Probe": "#/$defs/ProbeDescriptor", "SingleChannelPipette": "#/$defs/SingleChannelPipetteDescriptor" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/$defs/SingleChannelPipetteDescriptor" }, { "$ref": "#/$defs/EightChannelPipetteDescriptor" }, { "$ref": "#/$defs/ProbeDescriptor" }, { "$ref": "#/$defs/GripperDescriptor" } ] }, "title": "Tools", "type": "object" }, "tool_holders": { "additionalProperties": { "$ref": "#/$defs/ToolHolderDescriptor" }, "title": "Tool Holders", "type": "object" }, "labware_holders": { "additionalProperties": { "$ref": "#/$defs/LabwareHolderDescriptor" }, "title": "Labware Holders", "type": "object" } }, "$defs": { "EightChannelPipetteDescriptor": { "properties": { "min_volume": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "max_volume": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "max_speed": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "type": { "const": "EightChannelPipette", "default": "EightChannelPipette", "title": "Type", "type": "string" } }, "title": "EightChannelPipetteDescriptor", "type": "object" }, "GripperDescriptor": { "properties": { "type": { "const": "Gripper", "default": "Gripper", "title": "Type", "type": "string" } }, "title": "GripperDescriptor", "type": "object" }, "LabwareHolderDescriptor": { "description": "Descriptor for an entity that can hold labware.", "properties": { "type": { "const": "LabwareHolder", "default": "LabwareHolder", "title": "Type", "type": "string" } }, "title": "LabwareHolderDescriptor", "type": "object" }, "ProbeDescriptor": { "properties": { "type": { "const": "Probe", "default": "Probe", "title": "Type", "type": "string" } }, "title": "ProbeDescriptor", "type": "object" }, "SingleChannelPipetteDescriptor": { "properties": { "min_volume": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "max_volume": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "max_speed": { "anyOf": [ { "$ref": "#/$defs/ValueWithUnits" }, { "type": "null" } ], "default": null }, "type": { "const": "SingleChannelPipette", "default": "SingleChannelPipette", "title": "Type", "type": "string" } }, "title": "SingleChannelPipetteDescriptor", "type": "object" }, "ToolHolderDescriptor": { "description": "Descriptor for an entity that can hold tools.", "properties": { "type": { "const": "ToolHolder", "default": "ToolHolder", "title": "Type", "type": "string" } }, "title": "ToolHolderDescriptor", "type": "object" }, "ValueWithUnits": { "description": "A numeric value with associated units.\n\n:note: The following values are all equivalent:\n\n ``ValueWithUnits(magnitude=0.005, units=\"L\")``\n\n ``ValueWithUnits(magnitude=5, units=\"mL\")``\n\n ``ValueWithUnits(magnitude=5000, units=\"uL\")``\n\n ``ValueWithUnits(magnitude=5000, units=\"mm\u00b3\")``\n\n:note: In the python implementation, ``pint`` is used to resolve units. see `tcode_api.units`.", "properties": { "type": { "const": "ValueWithUnits", "default": "ValueWithUnits", "title": "Type", "type": "string" }, "magnitude": { "title": "Magnitude", "type": "number" }, "units": { "title": "Units", "type": "string" } }, "required": [ "magnitude", "units" ], "title": "ValueWithUnits", "type": "object" } } }
- Fields:
-
field type:
Literal['Robot'] = 'Robot'¶
-
field serial_number:
str|None= None¶
-
field tools:
dict[str,Annotated[SingleChannelPipetteDescriptor|EightChannelPipetteDescriptor|ProbeDescriptor|GripperDescriptor]] [Optional]¶
-
field tool_holders:
dict[str,ToolHolderDescriptor] [Optional]¶
-
field labware_holders:
dict[str,LabwareHolderDescriptor] [Optional]¶
- class tcode_api.api.entity.PathType(*values)¶
Enumeration of robot path types.
DIRECT: robot moves to the target location directly in jointspace. SAFE: robot moves to the target location via a safe path. SHORTCUT: robot uses DIRECT if it is close to the target, othserwise SAFE.
- class tcode_api.api.entity.GraspType(*values)¶
Enumeration of robot gripper grasp types.
PINCH: robot actively pinches the labware from the sides. LIFT: robot passively lifts the labware from the bottom.
- class tcode_api.api.entity.TrajectoryType(*values)¶
Enumeration of trajectory types.
JOINT_SQUARE: robot moves in joint space with square motor profiles. JOINT_TRAPEZOIDAL: robot moves in joint space with trapezoidal motor profiles. LINEAR: robot moves in cartesian space with non-uniform motor profiles.