You are here: Administrative Tasks : API Overview : MANTIS API Commands

MANTIS API Commands

API commands for the MANTIS software should be set by software developers or scientists only. The list below contains descriptions of the available API commands and/or functions for the MANTIS.

Note: Please be aware that MANTIS input in the following table includes a set of a MANTIS chip, input source type (tube/pipette), and reagent (stock/ingredient).

API Command Description Parameters Return Value
Attach

Use this command to attach a chip from the Automatic Chip Changer (ACC) to the MANTIS hand. This method cannot be applied to attach the chips from LC3 chip changers.

InputNumber

Type: System. Int32

Defines the numbers of input.

Type: void

If the operation fails, the method will throw an exception.

AttachBySerialNumber

Use this command to attach a specific chip to the MANTIS hand based on the chip’s serial number.

SerialNumber

Type: System. String

Defines the chip’s serial number to be attached.

Type: void

If the operation fails, the method will throw an exception.

AttachV2

This method is an improvement of the Attach API command. The AttachV2 can now attach chips from both ACC and LC3 chip changers to the MANTIS hand.

InputId

Type: System. String

Defines the input identifier. The input identifier values are:

  • 1-6 for MANTIS ACC
  • L1-L24 for the Left LC3
  • R1-R24 for the Right LC3

Type: void

If the operation fails, the method will throw an exception.

ClearDispenseList

Clear the current dispense list from the Dispense List Designer in the MANTIS software.

Use the ClearDispenseList command for the following common cases.

  • To avoid running dispense using the same dispense list twice after an error occurred when the dispense process is finished.
  • When a recovery handler error occurred , e.g. the dispense process stopped because the motor skipped unexpectedly, etc.

No parameter

Type: void

If the operation fails, the method will throw an exception.

ClearError

Use this command to clear the current error. You must call a ClearError API command after you received an error via a GetStatus API command. Otherwise, the GetStatus will always return an ERROR.

No parameter

Type: void

If the operation fails, the method will throw an exception.

Detach

Detach a chip from the MANTIS hand. Use this command after you call the Attach or AttachV2 command (i.e during reagent priming, washing, or recovery process via API).

No parameter

Type: void

If the operation fails, the method will throw an exception.

GetAllAvailableInputs

Use this command to retrieve the following list of inputs information:

  • Number of input
  • Chip type
  • Chip’s serial number
  • Input source type (pipette or tube)
  • Stock/reagent name
  • Chip changer location
  • Chip changer type
  • Input state (unprimed, primed, empty, etc)

No parameter

Type: List<InputInfo>

The return value is the list of all available chips info.

GetAllPlateInfo

Use this command to get the following plates’ information:

  • Numbers of columns
  • Number of rows
  • Number of wells
  • Column pitch
  • Row pitch
  • Plate definition file name, etc.

No parameter

Type: List< MicroplateInfo>

If the operation succeeds, the return value will be a list of plates’ information.

GetAppErrorMessages

Retrieve all recent error messages from the MANTIS software when it encounters an error.

Use this command to get the details of the error after the GetStatus API returns an ERROR.

No parameter

Type: List< String>

The return value is a string representing the recent error messages shown in the MANTIS software.

GetAvailablePlateNames

Get a list of available plate definition file names.

Use this command if you want to create your own dispense list from the MANTIS software and want to know what plate definition is available to use.

No parameter

Type: String[]

If the operation succeeds, the return value will be an array of plate names.

GetAvailableStockNames

Use this command to:

  • Get a list of available reagents (stocks) that are ready to use, especially when you are assigning reagents to the input by using SetInputStock API command.
  • Create a new dispense list using reagents from the list.

No parameter

Type: String[]

If the operation succeeds, the return value will be an array of stock names.

GetDeviceStatus

Use this command to retrieve the following MANTIS instrument’s statuses:

  • Software and instrument connection status
  • Simulation mode status
  • Running dispense status
  • Plate clamp status

No parameter

Type: Int32

The return value is an integer representing bit status (1 means True). Here is the list of the return values:

Bit 1: MANTIS instrument is connected.

Bit 2: Simulation mode is activated.

Bit 3: Pressure in range (Only applicable in TEMPEST)

Bit 4: Vacuum in range (Only applicable in TEMPEST)

Bit 5: Dispense is running.

Bit 6: Plate is present (Only applicable in TEMPEST).

Bit 7: Plate clamp is opened.

Bit 8: Barcode is supported (Only applicable in TEMPEST).

GetDispenseListInfo

Use this command to get a dispense list information, such as:

  • Dispense list filename
  • Plate type definition
  • Estimated execution time
  • Dispense list items information (stock name, liquid class, minimum volume, and required volume)

No parameter

Type: DispenseListInfo

The return value will be the summary of the current dispense list, and will return null if the dispense list is empty.

GetDispenseListStatus

Use this command to retrieve the following dispense list statuses:

  • Dispense list type
  • Dispense list file status (loaded or unloaded)
  • Ingredients/reagents status (assigned or unassigned to input)
  • The status of dispense list, whether it has been changed or not.

Note: If you are using the MANTIS Dispense List file (.dl.txt) and call the GetDispenseListStatus command, the default return value is type. If you load a dispense sequence file via LoadSequence, the dispense list status will return sequence.

No parameter

Type: Int32

The return value is an integer representing bit status (1 means True). Here is the list of the return values:

Bit 1: type (0: dispense list (default), 1: sequence)

Bit 2: File is loaded.

Bit 3: Ingredients/reagents have been assigned to inputs and ready to use.

Bit 4: Protocol uses barcode (Only applicable in TEMPEST)

Bit 5: Protocol has default dispense list (Only applicable in TEMPEST).

Bit 6: Dispense list has been changed.

GetLastDispensedWellName

Retrieve the last well’s position to be dispensed.

Use this command to:

  • Get the latest dispensed well position for error recovery mechanism.
  • Re-create a new dispense list starting from the latest well position and continue the dispense.

No parameter

Type: String

The return value is the last well’s position to be dispensed.

GetLc3Serial

Get the serial number of the active LC3 instruments that are connected to your computer and MANTIS instrument.

Call this API command if you want to use the RotateLc3 command that requires LC3 instrument serial number in its parameter.

No parameter

Type: List< String>

The return value will be a list of the LC3 instrument’s serial numbers.

GetPlateInfo

Use GetPlateInfo to get the following plate information based on the PlateName parameter:

  • Dispense list filename
  • Plate type definition
  • Estimated execution time
  • Dispense list items information (reagent name, liquid class, minimum volume, and required volume)

fileName

Type: System. String

Type: MicroplateInfo

If the operation succeeds, the return value will be a list of plate information based on the PlateName parameter.

GetServiceStatus

Retrieve the integration service status as follow:

  • Running
  • Stopped
  • Wait for user confirmation
  • Denied

Use GetServiceStatus if you want to start and stop the integration service by your device/application using the StartService or StopService API command.

computerName

Type: System. String

Defines the particular computer's name on the network.

Type: Int32

The return value is an integer:

  • 0: Running
  • 1: Stopped
  • 2: Wait for user confirmation
  • 3: Deny
GetStatus

Retrieve the current dispense status. The potential returned statuses are as follow:

  • Ready: It is not recommended to call the Run API command, even though MANTIS is not busy and you are able to call other API commands, such as Prime, PrimeAll, Wash, WashAll, etc.
  • Ready to dispense: You can call the Run API command, where the dispense list has been loaded and the reagents have been assigned to inputs.
  • Busy: MANTIS is executing a dispense list.
  • Error: An error occurred during dispense execution.

Important: This API command is fundamental in FORMULATRIX API system. You need to poll the API execution status by using this API command, and make sure that the status is not busy before calling another API command. For more information on how to poll the execution status, see Using the API Commands in MANTIS.

No parameter

Type: DispenseStatus

The return value is the current dispense status.

GetStatusBlocking

Retrieve the current dispense status with unlimited blocking timeout.

By using this API command, the API will not return to the dispense status until the execution is finished. You can use this to wait for an API execution.

Important: Please beware that the Windows Communication Foundation (WCF) default communication timeout is 60 seconds. If the execution takes more than the default timeout, it will throw an exception. To fix this, you may need to increase the timeout or use the GetStatus API command.

No parameter

Type: DispenseStatus

The return value is the current dispense status with unlimited blocking timeout.

GetStatusBlockingWithTimeout

Retrieve the current dispense status with the predefined maximum blocking timeout.

Note: The GetStatusBlockingWithTimeout API command has similar behaviour to the GetStatusBlocking command. However, this API has a timeout parameter that can be set as needed.

maxTimeout

Type: System. Int64

Defines the maximum blocking timeout before the API command retrieves the dispense status.

Type: DispenseStatus

The return value is the current dispense status with a defined maximum blocking timeout.

GetUserDirectory

Get the active user directory file path.

Use the GetUserDirectory command to get or create all user data files, such as dispense list, protocols, and plate definition files.

No parameter

Type: String

If the operation succeeds, the return value will be a string of user directory file path.

HomeArms

Use this command to return the MANTIS arm to the homing position. You may also want to use the HomeArms command after you received an error via GetStatus API command.

Note: This is a blocking method, where the API command will complete the current activities first before proceeding to the next method.

No parameter

Type: void

If the operation succeeds, the return value will be the MANTIS arms return to the homing position. If the operation fails, the method will throw an exception.

HomeLc3

Use this command to return the active connected LC3 instruments to the homing position. You may also want to use the HomeLc3 command after you received an error via GetStatus API command.

Note: This is a blocking method, where the API command will complete the current activities first before proceeding to the next method.

No parameter

Type: void

If the operation succeeds, the return value will be the LC3 instrument returning to the homing position.

If the operation fails, the method will throw an exception.

HomeStages

This API command is similar to the HomeArms command. Use this command to return the MANTIS arm to the homing position. You may also want to use the HomeArms command after you received an error via GetStatus API command.

Note: This is a blocking method, where the API command will complete the current activities first before proceeding to the next method.

No parameter

Type: void

If the operation succeeds, the return value will be the MANTIS arms returning to the homing position.

If the operation fails, the method will throw an exception.

InitializeLc3

Initialize any active LC3 instruments that are connected to your computer and MANTIS instrument.

You can call this API when you need to restart the LC3 if an unexpected error occurs. For example, when the power is suddenly cut off and you need to re-initialize the LC3 before you are able to call LC3 related API commands.

No parameter

Type: void

If the operation fails, the method will throw an exception.

LoadDispenseList

Load a dispense list from a file that has been specified by using the fileName parameter.

You can use the LoadDispenseList command before calling the Run API command.

fileName

Type: System. String

Defines the dispense list file path to be loaded for a dispense.

Type: void

If the operation fails, the method will throw an exception.

LoadProtocol

Load a protocol from a file that has been specified using the protocolFile parameter.

You can use the LoadProtocol command before calling the Run API command.

protocolFile

Type: System. String

Defines the protocol file path to be loaded for a dispense.

Type: Boolean

If the operation is successful, the return value will be true.

LoadReagentConfiguration

Load a reagent configuration from a file that has been specified by using the reagentConfigurationFile parameter.

You can use the LoadReagentConfiguration command to configure the MANTIS’ input, such as assigned reagents, prime volume, pre-dispense volume, etc by using a specified reagent configuration file.

Important: This API command only applies to the non-RFID MANTIS instrument.

reagentConfigurationFile

Type: System. String

Defines the reagent configuration file path to be loaded for a dispense.

Type: Boolean

If the operation is successful, the return value will be true.

LoadSequence

Load a dispense sequence from a file that has been specified by using the fileName parameter.

Use this API command if you prefer to run a dispense sequence file (.seq.txt) rather than a dispense list (.dl.txt) in MANTIS.

fileName

Type: System. String

Defines the sequence file path to be loaded for a dispense.

Type: void

If the operation fails, the method will throw an exception.

Prime

Prime a chip that is currently attached to the MANTIS hand.

If there is no chip on the MANTIS hand, use the Attach or AttachV2 command to attach the chip on the MANTIS hand and proceed with the priming.

No parameter

Type: void

If the operation fails, the method will throw an exception.

PrimeAll

Prime all of the chips that have been assigned to the MANTIS chip changers.

No parameter

Type: void

If the operation fails, the method will throw an exception.

PrimeAllWithVolume

Prime all of the assigned chips using a specified volume (in μL).

volume

Type: System. Double

The volume (in μL) used to prime all of the assigned chips.

Type: void

If the operation fails, the method will throw an exception.

PrimeWithVolume

Prime a chip that has been attached to the MANTIS hand using a specified volume (in μL).

volume

Type: System. Double

The volume (in μL) used to prime the current chip.

Type: void

If the operation fails, the method will throw an exception.

Recover

Recover excess reagent from the chip that is currently attached to the MANTIS hand.

If there is no chip on the MANTIS hand, use the Attach or AttachV2 command to attach the chip on the MANTIS hand and proceed with the reagent recovery.

No parameter

Type: void

If the operation fails, the method will throw an exception.

RecoverAll

Recover excess reagent from all of the chips that have been assigned to the MANTIS chip changers.

No parameter

Type: void

If the operation fails, the method will throw an exception.

RecoverAllWithVolume

Recover excess reagent from all of the chips that have been assigned to the MANTIS chip changers using a specified volume (in μL).

volume

Type: System. Double

The volume (in μL) to recover reagents from chips.

Type: void

If the operation fails, the method will throw an exception.

RecoverWithVolume

Recover excess reagent from the chip that is currently attached to the MANTIS hand using a specified volume (in μL).

If there is no chip on the MANTIS hand, use the Attach or AttachV2 command to attach the chip on the MANTIS hand and proceed with the reagent recovery.

volume

Type: System. Double

The volume (in μL) to recover reagents from the current chip.

Type: void

If the operation fails, the method will throw an exception.

RotateCarousel

Rotate the LC3 carousel to the specified input index position using the position and index parameters.

The available carousel positions that can be rotated are LeftFront and RightFront.

position

Type: LC3Location

Defines the LC3 instrument’s right or left position on the MANTIS instrument.

index

Type: System. Int32

Defines the carousel index.

Type: void

If the operation fails, the method will throw an exception.

RotateLc3

Rotate the LC3 carousel based on the LC3 instrument serial number and the predefined rotation degree.

Note: RotateLc3 and RotateCarousel are different API commands. To call the RotateLc3 command, you need to use the rotation degree and instrument serial number parameter. While in the RotateCarousel API command, you will need to specify the carousel destination index and location.

serialNum

Type: System. String

Defines the LC3 instrument serial number.

degree

Type: System. Double

Defines the degree of carousel rotation.

Type: void

If the operation fails, the method will throw an exception.

Run

Execute current dispense list or sequence.

No parameter

Type: void

If the operation fails, the method will throw an exception.

RunWithProtocol

Run a dispense with protocol.

Before calling the RunWithProtocol command, you will need to specify the protocol first by creating a protocol either from the MANTIS software or from the available spreadsheet program on your computer. Follow the MANTIS protocol .CSV file format.

protocolFile

Type: System. String

Defines the protocol file path to be loaded for a dispense.

Type: Boolean

If the operation is successful, the return value will be true.

ScanAllChips

Scan all of the assigned RFID inputs.

Use the ScanAllChips command to synchronize the MANTIS software and instrument, especially after you manually rearranged the chips’ location on the chip changers. This command is also helpful for the MANTIS and LC3 with the RFID instrument synchronization.

No parameter

Type: void

If the operation fails, the method will throw an exception.

ScanChip

Scan an assigned RFID input with the specified chip position in the MANTIS instrument.

inputId

Type: System. String

Defines the RFID chip’s Position ID (chip’s position in the chip changer) to be scanned.

Type: void

If the operation fails, the method will throw an exception.

SetAirPumpState

Set the air pump's ON/OFF state.

state

Type: System.Boolean

Defines the air pump's state to be set. True turns on the air pump, and False turns off the air pump.

Type: Boolean

If the return value is true, the air pump's state has been successfully set.

SetIgnoringChipLifetimeExceededWarning Use this command to make the MANTIS software ignore the Chip Lifetime Exceeded dialog message after a chip has reached its maximum lifetime cycle during a dispense execution.

Defines the Chip Lifetime Exceeded dialog message status.

Setting the SetIgnoringChipLifetimeExceededWarning command to True causes MANTIS to ignore the chip lifetime exceeded warning, while setting it to False displays the warning message.

No return value.
SetInputStock

Assign a reagent (stock) to an input.

Use the SetInputStock command to assign the unassigned reagents to inputs in a dispense list.

inputStock

Type: Formulatrix.LiquidDispenser.API. InputStock

Defines the reagents to be used with the MANTIS inputs.

Type: void

If the operation fails, the method will throw an exception.

SetInputStockRfid

Pair the reagent (stock) and input with a certain chip’s serial number.

Important: The SetInputStockRfid command only applies to MANTIS with RFID chips.

stockName

Type: System. String

Defines the reagent name.

serialNumber

Type: System. String

Defines the chip serial number target.

Type: void

If the operation fails, the method will throw an exception.

SetPlateClamp

Set the plate clamp's OPEN/CLOSED state.

state

Type: System. Boolean

Defines the plate clamp's state to be set. True closes the plate clamp, and False opens the plate clamp.

Type: Boolean

If the return value is True, the operation has successfully set the plate clamp to close. If the return value is False, the plate clamp will open.

StartService

Start the Integration Service.

You can use the StartService command, especially if you want to restart the MANTIS Integration Service after calling the StopService API command.

computerName

Type: System. String

Defines the specific computer name on the network.

Type: Int32

The return value is an integer,

  • 0: Allow (or the service has already started)
  • 1: Deny
  • 2: Wait for user confirmation
Stop

The operation is used to stop the current sequence execution.

No parameter

Type: void

If the operation fails, the method will throw an exception.

StopService

This operation is used to stop the integration service.

Although this command is rarely used, you may need to call this API if you want to stop the integration service i.e. for restart purpose.

computerName

Type: System. String

Defines the specific computer name on the network.

Type: Int32

The return value is an integer:

  • 0: Allow (or the service has already stopped)
  • 1: Deny
  • 2: Wait for user confirmation
Wash

Wash the chip that is currently attached to the MANTIS hand.

If there is no chip on the MANTIS hand, use the Attach or AttachV2 command to attach the chip on the MANTIS hand in order for it to be washed.

No parameter

Type: void

If the operation fails, the method will throw an exception.

WashAll

Wash all available inputs that are assigned on the MANTIS chip changers.

No parameter

Type: void

If the operation fails, the method will throw an exception.

WashAllDoubleWithVolume

Wash all available chips in the MANTIS chip changers using a specified volume and wash stations.

primeVolume

Type: System. Double

Defines the wash volume (in μL) in the Wash Station 1.

secondaryVolume

Type: System. Double

Defines the wash volume (in μL) in the Wash Station 2.

rinseVolume

Type: System. Double

Defines the rinse volume (in μL) to be used after the washing process.

Type: void

If the operation fails, the method will throw an exception.

WashAllInput

Wash the chip that is currently attached to the MANTIS hand.

Note: The WashAllInput command is available in the older version of MANTIS software.

Important: Ensure that you have attached the inputs to the MANTIS instrument before executing this operation. You can use the Attach or AttachV2 command to attach the chip on the MANTIS hand to be washed.

No parameter

Type: void

If the operation fails, the method will throw an exception.

WashAllWithVolume

Wash all available chips in the MANTIS chip changers using a specified volume.

If there is no chip on the MANTIS hand, use the Attach or AttachV2 command to attach the chip on the MANTIS hand to be washed.

volume

Type: System. Double

Defines the volume used to wash the chips.

Type: void

If the operation fails, the method will throw an exception.

WashDoubleWithVolume

Wash the chip that is currently attached to the MANTIS hand using a specified volume and wash stations.

primeVolume

Type: System. Double

Defines the wash volume (in μL) in the Wash Station 1.

secondaryVolume

Type: System. Double

Defines the wash volume (in μL) in the Wash Station 2.

rinseVolume

Type: System. Double

Defines the rinse volume (in μL) to be used after the washing process.

Type: void

If the operation fails, the method will throw an exception.

WashSelectedInput

Wash the selected input in MANTIS.

If there is no chip on the MANTIS hand, use the Attach or AttachV2 command to attach the chip on the MANTIS hand in order for it to be washed.

number

Type: System. Int32

Defines the input number to be washed.

Type: void

If the operation fails, the method will throw an exception.

WashWithVolume

Wash the chip that is currently attached to the MANTIS hand using a specified volume.

If there is no chip on the MANTIS hand, use the Attach or AttachV2 command to attach the chip on the MANTIS hand in order for it to be washed.

volume

Type: System. Double

Defines the volume used to wash the chip.

Type: void

If the operation fails, the method will throw an exception.

 

Related Topics


MAC-V47R321

10 DeAngelo Drive

Bedford, MA 01730

USA

 

+1-781-788-0228

support@formulatrix.com

publications@formulatrix.com