Native LabMate Commands

Overview

This document describes the low-level command set of the LabMate liquid handler. These low-level commands can be sent to the LabMate liquid handler using Genie’s Instrument REST API or by running the Execute Commands action from the Genie UI.

Execute Commands Action

Native LabMate commands can be sent to the instrument through the Instrument Actions page (shown below). Select the Execute Commands action and attach a JSON file with the list of commands to execute. Below is a list of a single command that retrieves liquid handler’s firmware version.

{
  "commands": [
    {
      "command_id": "ReadVersion",
      "payload": {}
    }
  ]
}

After the specified commands finished running, view the run result to see the list of responses:

LabMate Commands

Commands

ReadVersion

Gets version information from the instrument.

{
  "command_id": "ReadVersion",
  "payload": {}
}

The response to this command includes the mainboard firmware version. The current minimally supported version is 1.2.0. Contact support@genielifesciences.com if you need updated firmware.

ClearLabware

Instructs the instrument to remove all labware definitions. Call LoadLabware or LoadLabwareFromCache to register loaded labware with the instrument.

{
  "command_id": "ClearLabware",
  "payload": {}
}

ClearError

When the instrument errors the light will turn red. After resolving the error condition, call this command to clear the error state.

{
  "command_id": "ClearError",
  "payload": {}
}

ClearPause

If a user hits the pause button on the instrument it will enter the pause state and the light will turn blue. No movement commands can be run while the instrument is in a pause state. This command will reset the state so commands can be run.

{
  "command_id": "ClearPause",
  "payload": {}
}

Init

Perform instrument initialization. This must be done after the instrument is power cycled.

{
  "command_id": "Init",
  "payload": {}
}

Park

Move the pipette head to the Park position

{
  "command_id": "Park",
  "payload": {}
}

Home

Move the pipette head to the Home position

{
  "command_id": "Home",
  "payload": {}
}

SafeZ

Move the pipette head to its topmost height.

{
  "command_id": "SafeZ",
  "payload": {}
}

LoadLabware

Load a labware definition manually onto the instrument. This low level command can define custom labware not currently supported by Genie. Use at your own risk.

LoadLabwareFromCache is the safe way to load all Genie supported labware.

Arguments

• slot_ids: List[str] – Deck location to add the labware (‘A1’, top left). The same labware can be added to multiple slots in one command.
• x_index: float – X offset to the center of the first well, measured from the base on left side of the plate
• y_index: float – Y offset to the center of the first well, measured from the base on the top of the plate
• x_pitch: float – X distance between wells
• y_pitch: float – Y distance between wells
• max_z_height: float – Top of the well, measured from the bottom of the plate
• min_z_height: float – Bottom of the well, measured from the bottom of the plate
• diameter: float – The diameter of the well. Ignored for tipracks.
• row_count: int – Number of rows
• col_count: int – Number of columns
• height_to_volume: float – A measured factor that controls how the pipette moves during aspirate. Ignored for tipracks.
• cross_section_area: float – length*width for square wells and π(diameter/2)^2 for circular wells. Ignored for tipracks.
• tiprack_input: Optional[GlsTiprackInput] – Optional, if this labware is a tiprack this would include the settings for the tiprack.

Example

Load labware for a 50ul tiprack

{
  "command_id": "LoadLabware",
  "payload": {
    "slot_ids": ["B1"],
    "x_index": 12.41,
    "y_index": 11.60,
    "x_pitch": 9.0,
    "y_pitch": 9.0,
    "max_z_height": 61.79,
    "min_z_height": 61.79,
    "diameter": 0,
    "row_count": 8,
    "col_count": 12,
    "height_to_volume": 0,
    "cross_section_area": 0,
    "tiprack_input": {
      "tip_length": 58.3,
      "max_volume": 50,
      "min_volume": 1,
      "air_gap": 50,
      "lld_sensitivity": 150
    }
  }
}

Load the same 96 well plate into two deck locations.

{
  "command_id": "LoadLabware",
  "payload": {
    "slot_ids": ["C2","C3"],
    "x_index": 14.145,
    "y_index": 11.15,
    "x_pitch": 9.044,
    "y_pitch": 9.048,
    "max_z_height": 44.06,
    "min_z_height": 2.52,
    "diameter": 7.65,
    "row_count": 8,
    "col_count": 12,
    "height_to_volume": 10,
    "cross_section_area": 74.82
  }
}

LoadLabwareFromCache

Load a labware definition from the cache onto the instrument

Arguments

• slot_ids: List[str] – Deck location to add the labware (‘A1’, top left). The labware can be added to multiple slots in one command.
• labware: List[LabwareRef] – The labware ‘stack’. A stack is one or more pieces of labware on top of the other.
• offset: Optional[XYZVector] – The X, Y, and Z offset for the stack of labware. This would mostly be used if the labware were sitting on an on-deck instrument. All offsets are measured from the base of the labware.

Example

Loads a labware stack of a magnet and plate on to two deck locations. So both C2 and C3 will have the stack. Magnet is loaded by name, plate is loaded by LID.

{
  "command_id": "LoadLabwareFromCache",
  "payload": {
    "slot_ids": ["C2", "C3"],
    "labware": [
      { "filter": "Alpaqua 96S Super Magnet" },
      { "filter": "2" }
    ],
    "offset": { "x": 1.0, "y": 1.0, "z": 1.0 }
  }
}

Move

Move the instruments pipette head

Arguments

• deck_index: str – Deck position containing labware (A1, B1, etc)
• well_row: int – Numeric row of labware well (For 96 well plate 1-8)
• well_col: int – Numeric column of labware well (For 96 well plate 1-12)
• pipette_index: int – The pipette to move over the well (1 – 8)

Example

Movement can only happen to deck locations that have labware loaded on them. The labware model determines how the head will span to access the wells. This happens automatically, and is not user controllable.

{
  "command_id": "Move",
  "payload": {
    "deck_index": "B1",
    "well_row": 1,
    "well_col": 1,
    "pipette_index": 1
  }
}

AffixTips

Affix tips to the pipettes

Arguments

• pipettes: List[int] – List of pipettes to affix

Example

{
  "command_id": "AffixTips",
  "payload": {
    "pipettes": [1, 2, 3, 4, 5, 6, 7, 8]
  }
}

EjectTips

Eject tips from the pipettes

Arguments

• pipettes: List[int] – List of pipettes to eject

Example

Commands to move over the trash and eject all 8 tips. Trash is on deck position ‘D5’. It would also be possible to move the head over an empty column of a tip rack and eject the tips back into the rack.

[
  {
    "command_id": "Move",
    "payload": {
      "deck_index": "D5",
      "well_row": 1,
      "well_col": 1,
      "pipette_index": 1
    }
  },
  {
    "command_id": "EjectTips",
    "payload": {
      "pipettes": [1, 2, 3, 4, 5, 6, 7, 8]
    }
  }
]

Aspirate

Perform an aspirate

Arguments

• pipette_settings: List[GlsAspiratePipetteSetting]
• flow_rate_ratio: int – The Flow Rate Ratio is a tool used to adjust the LLT on a transfer without adjusting the pressure to the system. The Genie liquid handler uses an input of pressure (mbar), but the UI asks for flow rate (uL/s). The flow rate ratio converts the given flow rate into the respective pressure. The LLT uses the flow rate as a speed for the z movement. The default set is 344 for aspirate and 400 for dispense. For help, please contact support@genielifesciences.com
• retract_speed: int – Speed to retract tip from the well in mm/s

Example

Command to aspirate using all 8 pipettes using LLD.

{
  "command_id": "Aspirate",
  "payload": {
    "pipette_settings": [
      {
        "pipettes": [1, 2, 3, 4, 5, 6, 7, 8],
        "volume": 25,
        "offset": {
          "base": 1,
          "offset": -0.5
        },
        "flow_rate": 125,
        "air_gap_vol": 0.0,
        "track_liquid": true,
        "wet_tip": false,
        "settling_time": 0
      }
    ],
    "flow_rate_ratio": 400,
    "retract_speed": 2
  }
}

Dispense

Perform a dispense

Arguments

• pipette_settings
• flow_rate_ratio – The Flow Rate Ratio is a tool used to adjust the LLT on a transfer without adjusting the pressure to the system. The Genie liquid handler uses an input of pressure (mbar), but the UI asks for flow rate (uL/s). The flow rate ratio converts the given flow rate into the respective pressure. The LLT uses the flow rate as a speed for the z movement. The default set is 344 for aspirate and 400 for dispense. For help, please contact support@genielifesciences.com

Example

Command to dispense using all 8 tips

{
  "command_id": "Dispense",
  "payload": {
    "pipette_settings": [
      {
        "pipettes": [1, 2, 3, 4, 5, 6, 7, 8],
        "volume": 25,
        "flow_rate": 145,
        "offset": {
          "base": 1,
          "offset": -2.0
        },
        "track_liquid": false,
        "volume_factor": 1000,
        "settling_time": 0,
        "blowout": {
          "offset": {
            "base": 1,
            "offset": -2
          },
          "pressure": 116,
          "volume": 10
        }
      }
    ],
    "flow_rate_ratio": 344
  }
}

TipTouch

Perform a tip touch

Arguments

• pipette_settings: List[GlsTipTouchPipetteSettings]

Example

Performs a tip touch with pipettes 1-4.

{
  "command_id": "TipTouch",
  "payload": {
    "pipette_settings": [
      {
        "pipettes": [1, 2, 3, 4],
        "offset": {
          "base": 1,
          "offset": -1.0
        },
        "mode": "northSouth"
      }
    ]
  }
}

Mix

Perform a standalone mix

Arguments

• pipette_settings: List[GlsMixPipetteSetting] – List of mix pipette settings. Different sets of pipettes can have different settings.
• cycles: int – Number of times to mix
• asp_flow_rate_ratio: int – Flow rate ratio to use for aspirate portion of mix
• dsp_flow_rate_ratio: int – Flow rate ratio to use for dispense portion of mix
• retract_speed: float – The speed in mm/s at which the channels raise out of the liquid on the z axis after an aspiration. The minimum speed is 1 mm/s, the maximum speed is 20 mm/s, and the default is 2 mm/s. Commonly helpful to retract slower for viscous liquids and faster for volatile liquids.
• mode: MixMode

Example

This command performs a standalone mix. It’s an example of executing a command differently on different sets of pipettes. The first element of pipette_settings is for pipettes 1-4, and the second set is for 5-8. The two sets of pipettes use different offsets, and volumes but mix for the same number of iterations (3). All 8 pipettes would mix in parallel each using the correct settings.

{
  "command_id": "Mix",
  "payload": {
    "pipette_settings": [
      {
        "aspirate": {
          "offset": {
            "offset": -1.0,
            "base": 1
          },
          "flow_rate": 25
        },
        "dispense": {
          "offset": {
            "offset": -1.0,
            "base": 1
          },
          "flow_rate": 25
        },
        "pipettes": [1, 2, 3, 4],
        "volume": 25.00,
        "volume_factor": 10,
        "settling_time": 1,
        "blowout": {
          "volume": 10,
          "pressure": 50,
          "offset": {
            "offset": -2.0,
            "base": 1
          }
        }
      },
      {
        "aspirate": {
          "offset": {
            "offset": -2.0,
            "base": 1
          },
          "flow_rate": 25
        },
        "dispense": {
          "offset": {
            "offset": -2.0,
            "base": 1
          },
          "flow_rate": 35
        },
        "pipettes": [5, 6, 7, 8],
        "volume": 30.00,
        "volume_factor": 10,
        "settling_time": 1
      }
    ],
    "cycles": 3,
    "asp_flow_rate_ratio": 25,
    "dsp_flow_rate_ratio": 15,
    "retract_speed": 3,
    "mode": 1
  }
}

Shared Settings