.. _interface-spec: ======================= Interface Specification ======================= Copyright ========= Copyright Creare LLC 2016. This software specification is proprietary and should be considered confidential. Reproduction or distribution prohibited without written permission from Creare. Revision Log ============ .. csv-table:: Revision Log :header: "Date", "Author", "Changes" :widths: 10, 10, 80 :name: Interface Spec Revision Log "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 :ref:`development-interface` section." "3/8/2017", "MCR", "Minor tweaks to example-interface section." "3/3/2017", "MCR", "Added example-interface section." Overview ======== This document describes the software interface that interacts with the DMS firmware. The host software invokes the commands enumerated in the :ref:`icd` (which call the DMS to execute the functions defined in the :ref:`firmware-spec`) and then handles any results returned. There are two primary components of this interface: #. A :ref:`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. #. A simple, low level :ref:`interface` which the BioTek host application uses to send simple commands and recieve fault detection data from the DMS during normal operation. Host ==== For product roll-out, the DMS will be controlled by a PC (Windows 7 or later) over a :ref:`icd-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. .. _is-configuration-gui: Configuration GUI ================= A GUI is required to invoke the firmware commands enumerated in the :ref:`icd` 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. .. _is-gui_paramters: GUI Paramters ------------- Parameters stored in the GUI are tabulated in :numref:`is-gui-parameters-table`: .. csv-table:: GUI Parameters :header: "Parameter", "Description" :widths: 10, 30 :name: is-gui-parameters-table "``dms_id``", "The ID of the currently connected DMS (See :ref:`icd-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. " .. _is-gui-functions: GUI Functions ------------- The GUI should have buttons to perform the following operations. (See :ref:`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 :numref:`is-gui-parameters-table` 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 :numref:`Configuration Data` :ref:`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 :numref:`is-gui-parameters-table` 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 :ref:`icd-get-calibration`.) 5. **View calibration parameters.** Invoke ``GET_CALIBRATION`` and display the :numref:`Calibration Data` :ref:`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 :ref:`icd-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 :ref:`icd-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`` (:ref:`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 :numref:`Dispense Data` :ref:`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`` (:ref:`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 :ref:`fault-detection`.) 13. **Set reference mode.** Provide a listbox for the user to select one of the valid values of ``Ref_Mode`` (:ref:`Calibration Data`) as defined in :numref:`Configuration Parameters` :ref:`Configuration Parameters`. Upon user confirmation, apply this value using ``CONFIG_GET`` and ``CONFIG_SET`` (:ref:`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. .. _is-gui-layout: 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: a. **Initiate alignment mode**. b. **Update dark level**. c. **Collect new background**. d. **Calibrate**. e. **View background**. f. **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. a. **Edit file strings.** b. **Record raw data.** c. **Edit dispense parameters.** d. **Monitor dispense.** e. **Set reference dispense.** f. **Set reference mode.** .. _is-biotek-interface: 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: #. When initiating a dispense, activate the specific DMS associated with the active dispenser given its known ``ID``. #. Automatically set the :ref:`Configuration Data` with correct values for the current dispense using ``CONFIG-GET`` and ``CONFIG-SET``. #. Run ``MONITOR_DISPENSE`` at least 500 ms prior to each dispense. #. Poll ``GET_STATUS`` until the DMS mode returns to ``READY``. Take appropriate action if there is an error code. #. Retrieve fault data (``GET_WELL_FAULTS``) after each dispense and make this data available and actionable. #. Give the user the ability to run ``SET_REFERENCE_DISPENSE`` at any time. #. Give the user the option to set the ``Ref_Mode`` (:ref:`Calibration Data`) or run ``CLEAR_HISTORY`` (:ref:`Supported Commands Summary`) at any time. #. Automatically run ``CLEAR_HISTORY`` any time the :ref:`Configuration Data` changes (i.e. new cassette or dispense parameters.) .. _is-development-interface: Development Interface ===================== Creare has created a development interface in Matlab. It is documented in :numref:`development-interface`.