Open topic with navigation

F.A.S.T. API Integration

Introduction

F.A.S.T. liquid handler API (Application Programming Interface) enables you to integrate the F.A.S.T. instrument with your devices for automation purposes. Go to the Your F.A.S.T. instrument hostname:5003/restapi/ on your internet browser to see the detailed description of the F.A.S.T. API commands.

Note: For example your instrument number is 205, the host number will be fa100005. Only the last two digits of your instrument number being used.

Important: The F.A.S.T. API can only be accessed by your automation engineer or authorized IT personnel, any violation could result in instrument damage or error.

How to Access the API Integration Page

API Integration Flowchart

The flowchart below demonstrates the workflow of the F.A.S.T. API integration.

The API Integration Flowchart

F.A.S.T. API Page Overview

The F.A.S.T. liquid handler API page consists of five tabs: Instrument, Manual Operation, Protocol, Tray, and Schemas. Each tab includes a set of commands and functions to be used for the integration, except for the last tab Schemas. This tab displays detailed information on the other four tabs. See the picture below to overview the F.A.S.T. API Integration page and read the table for the details of the commands.

F.A.S.T. API Integration Page

Running the F.A.S.T. API Integration

The F.A.S.T. API also provides a set of protocols written in a .CSV format and some of its examples. For more information, download the Integration CSV Protocol Example here.

Prerequisites:

• You have turned on the F.A.S.T. Instrument.
• You have connected your computer to the same network as the F.A.S.T. instrument.
• You have set a plate list using the format from the CSV file above.

To run the F.A.S.T. API integration:

1. Call /manualoperation/move/idleposition to move the deck to its idle position, where the deck is ejected from the instrument.

Tip: You can call /status periodically until currentState shows that the device is idle while waiting for this movement to finish.

Instrument is in Idle Position

2. Place the plate on the tray insert.

3. Optional: If you haven’t set the plate list using the CSV above, call /tray/setcaddy and /tray/setplate to manually set the plate to the instrument. Skip this step if you have set the plate list.

4. To start running the protocol, you can call /protocol/run with a string of CSV protocol.

5. Wait while the system is validating the protocol and the instrument status. If an error occurs, see how to handle it from the Validation Error Handling.

6. When the validation has finished, the instrument will scan tips on the caddy and identify whether the number of tips on the caddy are enough for the current protocol execution. If an error occurs, see how to handle it from the Scan Tips Error Handling.

7. Then, F.A.S.T. will execute the protocol.

Tip: You can periodically call /status to check for execution status while the process is running.

Note: While the F.A.S.T. instrument is executing a protocol, errors might happen and require users' action. See Runtime Error Handling for more information.

8. Execution is completed when the currentState is back to idle with lastEvent contains messageType: 5, described as executionDone and the execution errorCode: 0, described as NoError.

Protocol Execution is Done

Error Handling

There are three kinds of error handling in the F.A.S.T. API integration: Validation, Scan Tips, and Runtime. See the provided table in each section to get the details of the errors.

Validation Error Handling

The instrument will validate each string first before executing it. There are several errors that might happen, whether from the specified string or the instrument.

Error Source	Error Code	Description	Solution
String from the CSV Protocol	-801, FailedToParse	Instrument has failed to parse the specified CSV protocol string. There might be a typo or unknown keyword. In most cases, this response will also include integer as payload. This integer indicates validation error happens around integer line number.	Check the CSV protocol string and make sure there is no typo or unknown keyword.
	-802, PickTipTwice	Pick specified tips twice in a row.	Check the CSV string to make sure there is no double picking.
	-803, PickTipLocationIsNotCaddy	The pick tip task specified to pick tips from a location that is not the caddy.	Check the CSV string to make sure the system picks the tips only from the caddy.
	-805, InvalidApirateOptions	Specified aspirate options in the CSV are invalid. For example, the aspirate volume, aspirate speed, or mixing speed exceeds the maximum value, etc.	Check the CSV string, make sure the aspirate options are valid.
	-806, InvalidDispenseOptions	Specified dispense options in the CSV are invalid. For example the dispense volume, dispense speed, or mixing speed exceeds the maximum value, etc.	Check the CSV string, make sure the dispense option is valid.
	-807, TipCountMissMatch	The pick up tips count does not match with tip count that will be used for aspirate or dispense.	Check the CSV string file, make sure the pick up tips match with the tips used for aspirate or dispense.
	-809, PlateNotSet	It appears if your CSV does not contain plates.	Please set the plate manually to the instrument.
	-810, MissmatchPlateDefinitionAndWellTarget	The number of the current attached tips is not enough for the aspirate and dispense processes.	Check the CSV string, make sure the number of the attached tips can accommodate the aspirate and dispense processes.
	-812, InvalidPickTipCount	The number of tips you have picked is not in a valid range, maximum row is 8 and maximum column is 12.	Check the CSV string, make sure it doesn’t exceed the range.
	-813, UnknownPlateID	The specified plate ID is not found.	Check the CSV string, make sure you put the correct plate ID.
	-814, InvalidDeckNumberLocation	The specified deck number is incorrect/invalid.	Check the CSV string, make sure you write the correct deck number.
	-815, InvalidAspirateDispenseVolumeSum	The total volume of aspirate and dispense is invalid.	Check the CSV string, make sure you have a valid total volume of aspirate and dispense.
	-816, PlatePosSuggestionAvailable	The instrument cannot execute the current protocol because it cannot support the t position.	Please change the plate position based on the response payload.
Instrument	-12, Busy	The instrument cannot run a new protocol because it is still running another protocol.	Please wait until the current execution is completed.
	-206, TrayUncalibrated	The tray is not calibrated.	Tray must be calibrated first before running any protocol.
	-205, TouchProbeExpanded	Touch probe is expanded.	Retract the touch probe before running any protocol.
	-203, MissingTray	There is no tray on the deck.	Insert the tray before executing a protocol.
	-11, NotReady	There is a latching error in the instrument.	Try to restart the instrument. If this problem persists please contact support@formulatrix.com for assistance.

Scan Tips Error Handling

If the F.A.S.T. instrument fails to scan the tips on the caddy, the protocol execution will be paused and you can see the error detail by calling /status and look at the lastEvent error code.

Error Code	Description	Solution
-604, CaddyNotExist	F.A.S.T. detects that there is no caddy attached in the instrument.	Put the caddy on the tray and resume the protocol execution.
-603, FailedToCalculateTips -605, VisionNotConfident	F.A.S.T. fails to calculate the number of tips.	You can resume the protocol execution and let F.A.S.T. instrument to retry scan tips in the caddy, if the result stays the same, you can call /protocol/settips to set tips manually and skip the scanning process.

Runtime Error Handling

The F.A.S.T. instrument might experience error while executing a protocol. When it happens, protocol execution will be paused and you can see the error detail by calling /status and look at the lastEvent error code.

Error Code	Description	Solution
-301, TipsNotEnough	Remaining tips on the caddy are not enough to execute the current protocol.	You have to add more tips on the caddy and resume the protocol execution.
-302, TipsNotEnoughPartially	Tips on the caddy are only enough to execute protocol partially. The instrument will be running out of tips in the middle of the protocol execution.	You can add more tips to the caddy and resume the protocol execution. You can ignore this error by resuming the protocol execution, and later on, add more tips when the system pauses again and shows the TipsNotEnough error code.
-601, TipsNotEnoughPartiallyYouHaveNoChoice	Tips on the caddy are full, but they are still not enough to execute the current protocol (long protocol).	You just need to resume protocol and wait for the execution to pause again when tips on caddy are not enough to do the liquid transfer.
-304, TipsNeedArrangement	The tips are not arranged well.	Resume the protocol and the system will rearrange the tips on the caddy for you.
-107, ActuatorAborted	An object collides with the F.A.S.T. head, which triggers the collision sensor.	Manually check the instrument and remove the object, then resume to continue the last task or abort the current protocol execution.
-109, ActuatorFollowingErrorMoving	The motor encoder position is skipped while moving. There is probably an object blocking the instruments' movement.	Manually check the instrument and remove the object, then resume to continue the last task or abort the current protocol execution.
-113, ActuatorEmergencyStop	The emergency button is pressed.	Resume to continue the last task.

FAOWH-V130R024	Unit 6, Level 13, Gate District, Gate Building Dubai International Financial Centre Dubai, United Arab Emirates   +1-781-788-0228 support@formulatrix.com publications@formulatrix.com