This is a simple browser tool which can be used to generate labware definitions for regular labware (labware that is laid out on a grid, and where all wells have consistent dimensions), or irregular labware.

This is a geometric sense of the word "regular". A labware in which:

• grid shape is uniform (a single regular grid, where each column and each row has a consistent number of wells)
• spacing between columns and rows remains consistent throughout the labware
• the overall height remains consistent throughout the labware

Any labware that does not meet the criteria of 'regular'. A labware is irregular if it has:

• more than one grid defining the x-y position of wells (such as a diamond arrangement)
• differing well dimensions (depth, diameter, shape, etc)
• differing numbers of wells from row to row or column to column
• any other dimensional irregularity

First you should make sure that you run make install within the opentrons top level folder. If you are up-to-date on all other directories you can simply run yarn instead. Next you have two options:

1. From the top level folder type: make -C labware-designer dev
2. Open your browser and type in: localhost:8080

OR

1. From the top level folder type: make -C labware-designer
2. Open labware-designer/dist/index.html in your browser

• In the browser window, open the console (in Chrome, right click in the middle of the page, select "Inspect" and then select the "Console" tab--other browsers vary but are similar).
• In the console, you can use the global variable sharedData and use any public functions which are exported in that project.

The generator has the following functions:

• sharedData.createRegularLabware - Generate regular labware definition
• sharedData.createIrregularLabware - Generate irrgular labware definition

To build a regular labware, the options object should have the following shape:

This example generates generic_96_wellplate_380_ul.json:

const options = {
  metadata: {
    displayName: 'ANSI 96 Standard Microplate',
    displayCategory: 'wellPlate',
    displayVolumeUnits: 'µL',
    tags: ['flat', 'microplate', 'SBS', 'ANSI', 'generic'],
  },
  parameters: {
    format: '96Standard',
    isTiprack: false,
    isMagneticModuleCompatible: false,
  },
  offset: { x: 14.38, y: 11.24, z: 14.35 },
  dimensions: {
    overallLength: 127.76,
    overallWidth: 85.48,
    overallHeight: 14.35,
  },
  grid: { row: 8, column: 12 },
  spacing: { row: 9, column: 9 },
  well: {
    depth: 10.54,
    shape: 'circular',
    diameter: 6.4,
    totalLiquidVolume: 380,
  },
  brand: { brand: 'generic' },
}

const labware = sharedData.createRegularLabware(options)

To build an irregular labware, the options object should have the following shape:

This example generates opentrons_6x15_ml_4x50_ml_tuberack.json

const options = {
  metadata: {
    displayName: 'Opentrons 6x15mL 4x50mL tube rack',
    displayCategory: 'tubeRack',
    displayVolumeUnits: 'mL',
    tags: ['opentrons', 'modular', 'tuberack', '15', 'mL', '50'],
  },
  parameters: {
    format: 'irregular',
    isTiprack: false,
    isMagneticModuleCompatible: false,
  },
  dimensions: {
    overallLength: 127.75,
    overallWidth: 85.5,
    overallHeight: 123.76,
  },
  offset: [{ x: 13.88, y: 17.75, z: 123.76 }, { x: 71.38, y: 25.25, z: 119.8 }],
  grid: [{ row: 3, column: 2 }, { row: 2, column: 2 }],
  spacing: [{ row: 25, column: 25 }, { row: 35, column: 35 }],
  well: [
    {
      totalLiquidVolume: 15000,
      diameter: 14.5,
      shape: 'circular',
      depth: 117.98,
    },
    {
      totalLiquidVolume: 50000,
      diameter: 26.45,
      shape: 'circular',
      depth: 113.85,
    },
  ],
  gridStart: [
    { rowStart: 'A', colStart: '1', rowStride: 1, colStride: 1 },
    { rowStart: 'A', colStart: '3', rowStride: 1, colStride: 1 },
  ],
  brand: { brand: 'Opentrons', brandId: ['352096', '352070'] },
}

const labware = sharedData.createIrregularLabware(options)

Metadata that affects how the labware is displayed to the user but does not affect labware functionality.

Example:

const metadata = {
  displayName: 'ANSI 96 Standard Microplate',
  displayCategory: 'wellPlate',
  displayVolumeUnits: 'uL', // u will be converted to µ
  tags: ['flat', 'microplate', 'SBS', 'ANSI', 'generic'],
}

Fields:

• displayName is the name of the labware in the Opentrons App, Protocol Designer, and other client apps
• displayCategory must be one of:
  • wellPlate
  • tubeRack
  • tipRack
  • trough
  • trash
  • other
• displayVolumeUnits is the units scale to use in the labware load name and app display; defaults to µL and must be one of:
  • µL
  • mL
  • L
• tags is a list of generic words that a user may search for to find the labware

Parameters that affect how the labware is operated on by the robot

Example:

const parameters = {
  format: '96Standard',
  isTiprack: false,
  isMagneticModuleCompatible: false,
}

Fields:

• format is determines how a multichannel pipette may interact with the labware
  • irregular - any type of container a multichannel cannot access; e.g. most tuberacks, irregular labware, etc
  • 96Standard - any labware with an 8x12 grid, well plate or tiprack
  • 384Standard - any labware with a 16x24 grid, well plate or tiprack
  • trough - labware where all tips of a multichannel access a single well simultaneously
• isTiprack specifies that the labware is a tiprack and all wells are tips
• tipLength specifies the length of the tips if isTiprack is true
• isMagneticModuleCompatible specifies that the labware can be used on the Magnetic Module
• magneticModuleEngageHeight specifies the height at which the Magnetic Module should engage if isMagneticModuleCompatible is true

Note: the full schema for labwareDefinition.parameters also inlcudes parameters.loadName. This field should not be set by the user; the program will generate it automatically and insert it into the definition:

loadName = `${brand}_${numWells}_${displayCategory}_${totalVol}_${displayVolumeUnits}`.toLowerCase()

Properties to apply to every well in a given grid.

Example:

const well = {
  depth: 10.54,
  shape: 'circular',
  diameter: 6.4,
  totalLiquidVolume: 380,
}

Fields:

totalLiquidVolume must be specified in µL. The generator will convert the value in µL to metadata.displayVolumeUnits for the loadName.

Note: The full well schema includes x, y, and z fields, but they should not be set by the user. The generator functions will calculate well positions.

The number of rows and columns in a regular labware or irregular labware grid

Example:

const grid = {
  row: 8,
  column: 12,
}

Fields:

Center-to-center distance in mm between rows and columns in a regular labware or irregular labware grid

Example:

const spacing = {
  row: 9,
  column: 9,
}

Fields:

The distance in mm from the upper left corner of the labware, flush with the deck to the top-center of well A1 (or the first well in an irregular labware grid).

Example:

const offset = {
  x: 14.38,
  y: 11.24,
  z: 14.35,
}

Fields:

Overall dimensions in mm of the labware

Example:

const dimensions = {
  overallLength: 127.76,
  overallWidth: 85.48,
  overallHeight: 14.35,
}

Fields:

• overallLength is the outer dimension of the labware in the X-axis
  • Usually equal to the length of the slot (127.76 mm)
• overallWidth is the outer dimension of the labware in the Y-axis
  • Usually equal to the width of the slot (85.48 mm)
• overallHeight is the outer dimension of the labware in the Z-axis
  • Usually the same as the top the well
  • Can be higher in case of some kind of vertical protrusion.

Used to generate well names for irregular labware. The object represents creating a "range" of well names with step intervals included. For example, starting at well "A1" with a column stride of 2 would result in the grid names being ordered as: "A1", "B1", ...; "A3", "B3", ...; etc.

Example:

// if grid has 3 rows and 3 columns, will produce the following well names:
//   B2  B4  B6
//   C2  C4  C6
//   D2  D4  D6
const gridStart = {
  rowStart: 'B',
  colStart: '2',
  rowStride: 1,
  colStride: 2,
}

Fields:

Brand information for the labware

Example:

const brand = {
  brand: 'Opentrons',
  brandId: ['352096', '352070'],
}

Fields:

If a brand object not input, the resulting definition will have: "brand": {"brand": "generic"}.

See diagram below: