4. Interface Specification

4.1. Copyright

Copyright Creare LLC 2016. This software specification is proprietary and should be considered confidential. Reproduction or distribution prohibited without written permission from Creare.

4.2. Revision Log

Table 4.1 Revision Log

Date	Author	Changes
4/7/2017	MCR	Added mode and error check to BioTek Application Interface section.
4/7/2017	MCR	Added firmware update.
3/29/2017	MCR	Broke example-interface section out into new Development Interface section.
3/8/2017	MCR	Minor tweaks to example-interface section.
3/3/2017	MCR	Added example-interface section.

4.3. Overview

This document describes the software interface that interacts with the DMS firmware. The host software invokes the commands enumerated in the Interface Control Document (which call the DMS to execute the functions defined in the Firmware Specification) and then handles any results returned. There are two primary components of this interface:

1. A GUI which allows comprehensive interaction with the DMS for purposes of alignment, calibration, and debugging. This GUI will only be accessed by trained technicians, not by the end-user.
2. A simple, low level interface which the BioTek host application uses to send simple commands and recieve fault detection data from the DMS during normal operation.

4.4. Host

For product roll-out, the DMS will be controlled by a PC (Windows 7 or later) over a USB Interface. In the future, different devices may interact with the DMS and act as its host, such as the dispenser itself, which runs Windows CE. The expectation is that the same USB interface will be used in all cases.

4.5. Configuration GUI

A GUI is required to invoke the firmware commands enumerated in the Interface Control Document and display the results. This GUI will be activated from within the BioTek host’s user interface. It will be used only by technicians trained to align, calibrate, and debug the device. It will not be available to end-users.

4.5.1. GUI Paramters

Parameters stored in the GUI are tabulated in Table 4.2:

Table 4.2 GUI Parameters

Parameter	Description
dms_id	The ID of the currently connected DMS (See ID).
file_string	A string that is inserted into all saved filenames for identification purposes. Default is an empty string.
save_path	Path where all files are saved. Default is a data folder in the DMS GUI software base path.

4.5.2. GUI Functions

The GUI should have buttons to perform the following operations. (See Supported Commands Summary.)

1. Connect to DMS. List all DMS systems physically connected to the host and allow the user to select one to activate. Assign the result to dms_id (See Table 4.2 above.) Display the ID of the active DMS at all times, and send commands only to this unit. (See ID command.)
2. Edit dispense parameters. Display an editable list of the Table 3.8 Configuration Data in a pop-up window. Provide confirmation and cancel buttons. (See CONFIG-GET and CONFIG-SET commands.)
3. Edit file strings. Allow user to edit file_string and save_path. It would be nice if there was a ‘browse’ button for the file_path. (See Table 4.2 above.)
4. View background. Invoke GET_CALIBRATION and display Background as a bar plot. For display, the data should be normalized at the ADC full scale and the y-limit fixed at 1. If cal_bin_edges is defined, indicate these values on the bar plot by overlaying bold vertical lines at the appropriate pixel locations. (See Get Calibration.)
5. View calibration parameters. Invoke GET_CALIBRATION and display the Table 3.10 Calibration Data (except cal_background and cal_image) in a text format in a pop-up window. Also display cal_image as a bar plot. For display, the data should be normalized at the ADC full scale and the y-limit fixed at 1. If cal_bin_edges is defined, indicate these values on the bar plot by overlaying bold vertical lines at the appropriate pixel locations. (See Get Calibration.)
6. Initiate alignment mode. Show a live bar-graph of the raw detector signal using the STREAM function. Overlay a line plot of cal_background on top of this dynamic bar plot (see Get Calibration.) For display, the data should be normalized at the ADC full scale and the y-limit fixed at 1. Provide a button or keystroke to exit this mode.
7. Update dark level. Prompt the user to cover the sensor. After the user confirms, invoke CALIBRATE(1). Report both the original and the resulting Dark_Level (Calibration Data) in an informational pop-up window.
8. Collect new background. Prompt the user to confirm that they want to overwrite the current background. Prompt the user to confirm that the laser is aligned, no dispense cartridge is in place, and the optical path is clear. Then run the CALIBRATE(2). Display the resulting background using the function defined in item 4 above.
9. Calibrate. Prompt the user to install the calibration cassette. Then run CALIBRATE(3). Display the resulting calibration using the function defined in item 5 above. Upon user confirmation, run STORE_CALIBRATION.
10. Record raw data. Prompt user for a record duration in seconds (default 10). When user clicks go, run STREAM for duration seconds. Write the returned data to an ASCII file as a duration X 386 array (384 integer pixel values at 12 bit + 2 binary trigger input values). The file name should be [save_path]\[file_string]_DMS_raw_0000.dat. Increment the integer until either save_path or file_string changes. When complete, show the saved file name with full path in an informational popup.
11. Monitor dispense. Poll STATUS to confirm State is READY. If it is not, issue an error in a popup window and report State. Otherwise, invoke MONITOR_DISPENSE. Wait until dispense is complete. Poll STATUS until State is READY (timeout after 15 s). If Last_Reported_Error is not zero, report the error in a popup window. Invoke GET_DISPENSE_DATA. Save the resulting Table 2.6 Dispense Data to [save_path]\[file_string]_DMS_data_0000.dat on the host in some sensible format. Increment the integer index in the filename until either save_path or file_string changes.
12. Set reference dispense. Invoke SET_REFERENCE_DISPENSE. Poll STATUS. If Last_Reported_Error is DMS_ERR_NO_RECENT_HISTORY, show a popup error message and exit. Otherwise, if Ref_Mode (Calibration Data) is not 'user', prompt to set this value, with confirm and cancel buttons. Upon user confirmation, apply this value using CONFIG-GET and CONFIG-SET. (See Fault Detection.)
13. Set reference mode. Provide a listbox for the user to select one of the valid values of Ref_Mode (Calibration Data) as defined in Table 2.2 Configuration Parameters. Upon user confirmation, apply this value using CONFIG_GET and CONFIG_SET (Supported Commands Summary).
14. Update Firmware. Prompt user to select a valid DMS.bin firmware file. Invoke FIRMWARE_BLOCK multiple times to upload this file to the DMS. Invoke FIRMWARE_GET_CRC32 to get the checksum. Compute the CRC32 of the local file. If the checksums are equal, invoke FIRMWARE_PROGRAM to install the uploaded binary to non-volatile memory.

4.5.3. GUI Layout

The layout of the configuration GUI should be designed around the following typical workflow:

1. Connect to DMS will always be the first operation. This should be at the top and always visible.

2. To calibrate a newly installed DMS unit:

   1. Initiate alignment mode.
   2. Update dark level.
   3. Collect new background.
   4. Calibrate.
   5. View background.
   6. View calibration paramters.

3. Update Firmware will not be used often, but should be easily accessible.

4. Manual dispense monitoring for debugging purposes. These commands are only likely to be used by Creare, and are the lowest priority for the BioTek configuration GUI.

   1. Edit file strings.
   2. Record raw data.
   3. Edit dispense parameters.
   4. Monitor dispense.
   5. Set reference dispense.
   6. Set reference mode.

4.6. BioTek Application Interface

In addition to being able to launch the GUI described above, the BioTek LHC should also be able to talk automatically to the DMS to do the following during normal operation:

1. When initiating a dispense, activate the specific DMS associated with the active dispenser given its known ID.
2. Automatically set the Configuration Data with correct values for the current dispense using CONFIG-GET and CONFIG-SET.
3. Run MONITOR_DISPENSE at least 500 ms prior to each dispense.
4. Poll GET_STATUS until the DMS mode returns to READY. Take appropriate action if there is an error code.
5. Retrieve fault data (GET_WELL_FAULTS) after each dispense and make this data available and actionable.
6. Give the user the ability to run SET_REFERENCE_DISPENSE at any time.
7. Give the user the option to set the Ref_Mode (Calibration Data) or run CLEAR_HISTORY (Supported Commands Summary) at any time.
8. Automatically run CLEAR_HISTORY any time the Configuration Data changes (i.e. new cassette or dispense parameters.)

4.7. Development Interface

Creare has created a development interface in Matlab. It is documented in Section 5.