Evoware Configuration

The EvowareConfigSpec enables you to configure your Evoware robot for Roboliq. You will need to create a JavaScript file in which you define an EvowareConfigSpec object, and then have it converted to the Roboliq protocol format. Your config file will have the following structure:

const evowareConfigSpec = {
  // Lab name and robot name
  namespace: "YOUR LAB ID",
  name: "YOUR ROBOT ID",
  // Compiler settings
  config: {
    TEMPDIR: "TEMPORARY DIRECTORY FOR MEASUREMENT FILES",
    ROBOLIQ: "COMMAND TO CALL ROBOLIQ'S RUNTIME",
    BROWSER: "PATH TO WEB BROWSER"
  },
  // Bench sites on the robot
  sites: {
    MYSITE1: {evowareCarrier: "CARRIER ID", evowareGrid: MYGRID, evowareSite: MYSITE},
    ...
  },
  // Labware models
  models: {
    MYPLATEMODEL1: {type: "PlateModel", rows: 8, columns: 12, evowareName: "EVOWARE LABWARE NAME"},
    ...
  },
  // List of which sites and labware models can be used together
  siteModelCompatibilities: [
    {
      sites: ["MYSITE1", ...],
      models: ["MYPLATEMODEL1", ...]
    },
    ...
  ],
  // List of the robot's equipment
  equipment: {
    MYEQUIPMENT1: {
      module: "EQUIPMENT1.js",
      params: {
        ...
      }
    }
  },
  // List of which lid types can be stacked on which labware models
  lidStacking: [
    {
      lids: ["lidModel_standard"],
      models: ["MYPLATEMODEL1"]
    }
  ],
  // List of the robot's robotic arms
  romas: [
    {
      description: "roma1",
      // List of sites this ROMA can safely access with which vectors
      safeVectorCliques: [
                { vector: "Narrow", clique: ["MYSITE1", ...] },
                ...
            ]
    },
    ...
  ],
  // Liquid handing arm
  liha: {
    // Available tip models
    tipModels: {
      MYTIPMODEL1000: {programCode: "1000", min: "3ul", max: "950ul", canHandleSeal: false, canHandleCells: true},
      ...
    },
    // List of LIHA syringes (e.g. 8 entries if it has 8 syringes)
    syringes: [
      { tipModelPermanent: "MYTIPMODEL1000" },
      ...
    ],
    // Sites that the LIHA can access
    sites: ["MYSITE1", ...],
    // Specifications for how to wash the tips
    washPrograms: {
      // For Example: Specification for flushing the tips with `programCode == 1000`
      flush_1000: { ... },
      ...
    }
  },
  // Additional user-defined command handlers
  commandHandlers: {
    "MYCOMMAND1": function(params, parsed, data) { ... },
    ...
  },
  // Optional functions to choose among planning alternatives
  planAlternativeChoosers: {
    // For Example: when the `shaker.shakePlate` command has
    // multiple shakers available, you might want to use
    // the one name `MYEQUIPMENT1`
    "shaker.canAgentEquipmentSite": (alternatives) => {
            const l = alternatives.filter(x => x.equipment.endsWith("MYEQUIPMENT1"));
            if (l.length > 0)
                return l[0];
        }
  }
};

const EvowareConfigSpec = require('roboliq-evoware/dist/EvowareConfigSpec.js');
module.exports = EvowareConfigSpec.makeProtocol(evowareConfigSpec);

Details about the EvowareConfigSpec structure can be found below.

EvowareConfigSpec

This is a configuration specification for an Evoware robot.

Properties:

Name	Type	Description	Required
namespace	string	This is the namespace prefix for the robot. By convention, this can be a label for your lab. The value should not contain any spaces or periods.	required
name	string	This is the robot name. The value should not contain any spaces or periods.	required
config	/EvowareCompilerConfig	Settings for the Evoware compiler.
sites	object	These are the bench sites that Roboliq can use on the Evoware robot. `sites` is a map from site name to site specification. The name should not contain any spaces or periods.
models	object	These are the labware models that Roboliq can use on the Evoware robot. `models` is a map from model name to model specification. The name should not contain any spaces or periods.
siteModelCompatibilities	array	Specifications of which bench sites are compatible with which models.
lidStacking	array	Specifications of which labwares can be stacked. Normally, this means just specifying that the default lid `lidModel_standard` can go on various plate models. Within limit, plates can also be stacked on top of each other.
equipment	object	These are the equipment devices that are integrated with the Evoware robot. `equipment` is a map from equipment name to equipment specification. The name should not contain any spaces or periods.
romas	array	List of Evoware ROMAs (robotic arms for moving plates).
liha	/EvowareLihaSpec	Specification of the Evoware robot's LIHA (Liquid Handling Arm).
commandHandlers	object	This allows you to provide user-defined command handlers. It can also be used to override the command handlers provided by Roboliq, Evoware, or and equipment module. `commandHandlers` is a map from the command name to a command handling function. See the documention about command handlers for more information.
planAlternativeChoosers	object	This is an advanced property that will require some understanding of Roboliq's approach to planning. Please see the documenation for more information. `planAlternativeChoosers` is a map from a predicate ID to a function that takes a list of possible alternatives for that predicate. The function can then choose one of those alternatives by returning it. This allows you to configure planning preferences, such as if you have two shakers, you might always prefer to use a specific one when it's among the alternatives.

EvowareCompilerConfig

Settings for the Evoware compiler.

Properties:

Name	Type	Description	Required
TEMPDIR	string	Directory where measurement files can be temporarily stored during processing	required
ROBOLIQ	string	The evoware command to call the roboliq runtime	required
BROWSER	string	Path to the browser (e.g Google Chrome) for opening Roboliq's HTML files	required

Example:

TEMPDIR: "C:\\Users\\localadmin\\Desktop\\Ellis\\temp",
ROBOLIQ: "wscript C:\\Users\\localadmin\\Desktop\\Ellis\\roboliq\\roboliq-runtime-cli\\roboliq-runtime-cli.vbs",
BROWSER: "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe"

EvowareSiteSpec

Specification of an Evoware site

Properties:

Name	Type	Description	Required
evowareCarrier	string	Name of the Evoware carrier	required
evowareGrid	integer	The site's grid	required
evowareSite	integer	The site's index	required

Example:

evowareCarrier: "Hotel 4Pos Transfer Grid 69"
evowareGrid: 69
evowareSite: 1

EvowareModelSpec

Specification of an Evoware labware model

Properties:

Name	Type	Description	Required
type	string	The type of labware model (currenly only `PlateModel` is available) One of: PlateModel	required
description	string	An optional string to describe this model.
rows	integer	Number of rows on the plate	required
columns	integer	Number of columns on the plate	required
evowareName	string	Evoware name of the labware model	required

Example:

type: PlateModel
rows: 8
columns: 12
evowareName: "EK 96 well Greiner Black"

EvowareSiteModelCompatibilitySpec

Specification of which bench sites are compatible with which models. All such sites should be listed in the sites property, and the models in the models property.

Properties:

Name	Type	Description	Required
description	string	An optional string to describe this list.
sites	array	A list of sites that are compatible with the `models`. The names in this list should be defined in the `sites` property of the parent `EvowareConfigSpec` object.	required
models	array	A list of models that are compatible with the `sites`. The names in this list should be defined in the `models` property of the parent `EvowareConfigSpec` object.	required

Example:

description: "short-format plate sites (non-tall labware, not for deep well plates)",
sites: ["P1DOWNHOLDER", "HOTEL4_1", "HOTEL4_2", "HOTEL4_3", "HOTEL4_4", "READER", "ROBOPEEL", "ROBOSEAL"],
models: ["plateModel_96_round_transparent_nunc", "plateModel_96_square_transparent_nunc"]

EvowareLidStackingSpec

Specifies combinations of labwares can be stacked. Normally, this means just specifying that the default lid lidModel_standard can go on various plate models. Within limit, plates can also be stacked on top of each other. All items in lids will be stackable on all items in models.

Properties:

Name	Type	Description	Required
description	string	An optional string to describe this list.
lids	array	A list of lid models (or labware models) that can be stacked on `models`. The names in this list should either be `lidModel_standard` or be defined in the `model` property of the parent `EvowareConfigSpec` object.	required
models	array	A list of models that are compatible with the `sites`. The names in this list should be defined in the `models` property of the parent `EvowareConfigSpec` object.	required

Example:

description: "short-format plate sites (non-tall labware, not for deep well plates)",
lids: ["lidModel_standard"]
models: ["plateModel_96_round_transparent_nunc", "plateModel_96_square_transparent_nunc"]

EvowareEquipmentSpec

This allows you to specify a equipment module to load and the parameters that should be passed to the module.

Properties:

Name	Type	Description	Required
description	string	An optional string to describe this piece of equipment.
module	string	Filename of the equipment module to load. The available modules can be found in the directory `roboliq-evoware/src/equipment`.	required
params	object	The parameters to be passed to the equipment module. See the documentation for the equipment modules for more information.	required

Example:

module: "reader-InfiniteM200Pro.js"
params:
  evowareId: "ReaderNETwork"
  evowareCarrier: "Infinite M200"
  evowareGrid: 61
  evowareSite: 1
  site: "READER"
  modelToPlateFile:
    "plateModel_96_round_transparent_nunc": "NUN96ft"
    "plateModel_384_square": "GRE384fw"

EvowareRomaSpec

Specification of an Evoware ROMA (robotic arms for moving plates).

Properties:

Name	Type	Description	Required
description	string	An optional string to describe this ROMA.
safeVectorCliques	array	list of cliques of sites that the ROMA can safetly move plates between using a given vector

Example:

description: "roma1"
safeVectorCliques:
  - { vector: "Narrow", clique: ["P2", "P3", "P4", "P5", "P6", "P7", "P8", "REGRIP"] }
  - { vector: "Narrow", clique: ["CENTRIFUGE_1", "REGRIP"] }
  - { vector: "Narrow", clique: ["CENTRIFUGE_2", "REGRIP"] }
  - { vector: "Narrow", clique: ["CENTRIFUGE_3", "REGRIP"] }
  - { vector: "Narrow", clique: ["CENTRIFUGE_4", "REGRIP"] }

EvowareLihaSpec

Specification of the Evoware robot's LIHA (Liquid Handling Arm).

Properties:

Name	Type	Description
tipModels	object	These are the tip models that can be used with the Evoware robot. `tipModels` is a map from tip model name to specification. The name should not contain any spaces or periods.
syringes	array	A list of syringe specifications - one for each syringe on the LIHA. For robots with fixed tips, the `tipModelPermanent` must be set to one of the values in `tipModels`. For disposable tips, an empty object should be specified for each syringe.
sites	array	A list of sites that they LIHA can operate on. The names in this list should either be defined in the `sites` property of the parent `EvowareConfigSpec` object or in an `equipment` defintion.
washPrograms		These are the wash programs for the LIHA. `washPrograms` is a map from name to specification. The name is composed of a wash intensity, an underscore, and a tip model `programCode`. For example, to flush 1000ul tips with a program code of "1000", the washProgram name would be "flush_1000".

EvowareWashProgramSpec

Describes a method for washing tips in Evoware

Must be one of:

#/definitions/specProgram
#/definitions/specScript

Definitions:

specProgram

Name	Type	Description	Required
type	string	Type of this object One of: EvowareWashProgram	required
wasteGrid	integer		required
wasteSite	integer		required
cleanerGrid	integer		required
cleanerSite	integer		required
wasteVolume	numeric		required
wasteDelay	integer		required
cleanerVolume	numeric		required
cleanerDelay	integer		required
airgapVolume	numeric		required
airgapSpeed	integer		required
retractSpeed	integer		required
fastWash	boolean		required

specScript

Name	Type	Description	Required
type	string	Type of this object One of: EvowareWashProgram	required
script	string	Full path to evoware script to perform the washing.	required

EvowareTipModelSpec

This specifies a tip model that can be used with the Evoware robot.

Properties:

Name	Type	Description	Required
programCode	string	a string to use for generating the liquid class names for this tip model	required
min	string	minimum volume (requires volume units, e.g. "3ul")	required
max	string	maximum volume (requires volume units, e.g. "950ul")	required
canHandleSeal	boolean	true if this tip can be used with sealed plates (default = false)
canHandleCells	boolean	true if this tip can handle cells (default = false)

Example:

{"programCode": "1000", "min": "3ul", "max": "950ul", "canHandleSeal": false, "canHandleCells": true}