Merge pull request #1113 from TheDeanLab/asi-rst

Asi documentation + bug fixes

Author: AdvancedImagingUTSW

docs/source/02_user_guide/01_supported_hardware/daq.rst

@@ -145,6 +145,57 @@ outputs can be wired up as is most convenient.
 
 ------------------
 
+Applied Scientific Instrumentation
+----------------------------------
+
+Tiger Controller
+~~~~~~~~~~~~~~~~
+
+.. warning::
+
+    USE OF THE TIGER CONTROLLER AS A DATA ACQUISITION CARD IS STILL IN DEVELOPMENT.
+
+
+The ASI `Tiger Controller <https://www.asiimaging.com/controllers/tiger-controller/>`_ is
+a multi-purpose controller for ASI stages, filter wheels, and dichroic sliders.
+It can also control lasers, shutters, remote focusing devices, and galvanometers. More info 
+for these devices can be found on their respective documention pages.
+
+Remote focus device, galvanometer, and analog laser control is done by the `TGGALVO <https://asiimaging.com/docs/tggalvo>`_ control card. 
+Shutter and digital laser control is done by the `TGPLC <https://asiimaging.com/docs/tiger_programmable_logic_card>`_ control card.
+TGPLC output 1 delivers the camera trigger signal (equivalent to camera_trigger_out_line for the NI Card).
+
+We communicate with Tiger Controllers via a serial port. It is recommended that you
+first establish communication with the device using `ASI provided software <https://asiimaging.com/docs/products/tiger>`_.
+If not, simply install the `USB driver <https://www.asiimaging.com/support/downloads/usb-support-on-ms-2000-wk-controllers/>`_ 
+to communicate with the Tiger Controller
+
+.. note::
+
+    **navigate** has been tested with the following versions of the ASI's Tiger
+    Controller software:
+
+    - Tiger Controller 2.2.0.
+
+.. note::
+    Some users have reported intermittent connection issues at random intervals when
+    used with Coherent OBIS lasers. These issues, and how to address them, are discussed
+    in the :ref:`communication challenges <obis_tiger_connection>` section.
+
+.. collapse:: Configuration File
+
+    .. code-block:: yaml
+
+      microscopes:
+        microscope_name:
+          daq:
+            hardware:
+              type: ASI
+              port: COM4
+
+|
+
+------------------
 
 Synthetic Data Acquisition Card
 -------------------------------

docs/source/02_user_guide/01_supported_hardware/galvo.rst

@@ -40,23 +40,22 @@ Multiple types of galvanometers have been used, including Cambridge Technologies
 
 ------------
 
-ASI
----
-
-Multiple types of galvanometers have been used, including Cambridge
-Technologies/Novanta, Thorlabs, and ScannerMAX. Each of these devices
-are externally controlled via analog signals delivered from the ASI 
-Tiger Controller.
-
-The ASI Tiger Controller has a few limitations for the analog signals. First, the 
-minimum voltage must be zero volts. Second, the period value needs to be a whole number.
-Third, there are three analog waveforms offered, sawtooth,  
-triangle, and sine waves.
-
+Applied Scientific Instrumentation
+----------------------------------
+
+In principle, this hardware type can support any analog-controlled galvanometer,
+including those from Cambridge Technologies/Novanta, Thorlabs, and ScannerMAX. 
+Each of these devices are externally controlled via analog signals delivered from the ASI Tiger Controller (`TG-1000 <https://asiimaging.com/docs/products/tiger>`_).
+ 
+Galvanometers can take two types of analog waveforms: sawtooth and sine.
 The sawtooth waveform is a periodic analog waveform. There are three duty cycle values 
 accepted, 0, 50, and 100. If the duty cycle is 0, the waveform is a falling sawtooth 
 waveform. If the duty cycle is 50, then it is a triangle wave. If the duty cycle is 100, 
-the waveform is a rising sawtooth waveform. 
+the waveform is a rising sawtooth waveform. The duty cycle will be rounded to the nearest acceptable value.
+
+The ASI Tiger Controller has a few limitations for the analog signals.
+The period value will be rounded to the nearest whole number of milliseconds,
+and for the triangle wave, the period will be rounded to the nearest even number.
 
 
 .. collapse:: Configuration File
@@ -78,10 +77,10 @@ the waveform is a rising sawtooth waveform.
                 hardware:
                   type: ASI
                   axis: B
-                  min: 0
-                  max: 1.0
-                waveform: sine
-                phase: 1.57079632679
+                  min: -5.0
+                  max: 5.0
+                waveform: sawtooth
+                phase: 1.57
 
 |
 

docs/source/02_user_guide/01_supported_hardware/laser.rst

@@ -8,11 +8,10 @@ We currently support laser control via voltage signals. In the near-future, we w
 Applied Scientific Instrumentation
 ----------------------------------
 
-
-Tiger Controller
-~~~~~~~~~~~~~~~~~~
-
-The Tiger Controller from ASI can also be used to perform analog, digital, and mixed modulation of lasers. Digital modulation is controlled with a `TGPLC <https://asiimaging.com/docs/tiger_programmable_logic_card>`_ or `TGGALVO <https://asiimaging.com/docs/tggalvo>`_ control cards, while analog modulation is controlled with a TGGALVO control card.
+The Tiger Controller (`TG-1000 <https://asiimaging.com/docs/products/tiger>`_) from ASI can also be used to perform analog, digital, and mixed modulation of lasers. 
+Digital modulation is controlled with a `TGPLC <https://asiimaging.com/docs/tiger_programmable_logic_card>`_ 
+or `TGGALVO <https://asiimaging.com/docs/tggalvo>`_ control cards, while analog modulation is controlled with a TGGALVO control card.
+TGPLC output 1 is reserved for the camera trigger.
 
 --------------------------------
 
@@ -28,7 +27,7 @@ The Tiger Controller from ASI can also be used to perform analog, digital, and m
                 onoff:
                   hardware:
                     type: ASI
-                    axis: [2-8]
+                    axis: 2
                     min: 0.0
                     max: 5.0
                 power:
@@ -42,7 +41,7 @@ The Tiger Controller from ASI can also be used to perform analog, digital, and m
                 onoff:
                   hardware:
                     type: ASI
-                    axis: [2-8]
+                    axis: 3
                     min: 0.0
                     max: 5.0
                 power:

docs/source/02_user_guide/01_supported_hardware/remote_focus.rst

@@ -112,15 +112,20 @@ Optotune Focus Tunable Lens
 
 ------------------
 
-ASI
----
+Applied Scientific Instrumentation
+----------------------------------
 
-The ASI Tiger Controller has a few limitations for the analog signals. First, the 
-minimum voltage must be zero volts. Second, the period value needs to be a whole number.
+In principle, this hardware type can support any analog-controlled voice coil or tunable lens. 
+The `BLINK <https://www.thorlabs.com/thorproduct.cfm?partnumber=BLINK>`_ and the `Optotune Focus Tunable Lens <https://www.optotune.com/tunable-lenses>`_ 
+can be controlled with an analog signal from the ASI Tiger Controller (`TG-1000 <https://asiimaging.com/docs/products/tiger>`_).
 
-There are two analog waveforms offered, triangle and ramp waves. The triangle waveform is 
-a periodic analog waveform, with no delay periods. The sawtooth waveform is a periodic 
-analog waveform with a delay period between each cycle. 
+The ASI Tiger Controller has a few limitations for the analog signals. 
+The remote focus waveform is a periodic ramp waveform with a delay period between each ramp. 
+The ramp lasts for the exposure time, falls very quickly and rests until the next exposure time.
+Fall time is not configurable so there is no 'gentle' fall with this hardware.
+
+The ramp waveform must last a whole number of milliseconds. If exposure time is not a whole number, 
+the ramp time will be rounded to the nearest whole number.
 
 .. collapse:: Configuration File
 
@@ -134,8 +139,8 @@ analog waveform with a delay period between each cycle.
               axis: A
               min: 0
               max: 5
-              port: COM2
-              baudrate: 9600
+              port: COM4
+
 |
 
 ------------------

docs/source/02_user_guide/01_supported_hardware/shutter.rst

@@ -19,12 +19,9 @@ is closed.
 Applied Scientific Instrumentation
 ----------------------------------
 
-Tiger Controller
-~~~~~~~~~~~~~~~~~~
-
------------------
-
-The `tgplc <https://asiimaging.com/docs/tiger_programmable_logic_card>`_ control card from ASI can be used to trigger shutter operation.
+The `TGPLC <https://asiimaging.com/docs/tiger_programmable_logic_card>`_ control card for the 
+Tiger Controller (`TG-1000 <https://asiimaging.com/docs/products/tiger>`_) from ASI can be used to trigger shutter operation.
+TGPLC output 1 is reserved for the camera trigger.
 
 -----------------
 
@@ -37,9 +34,10 @@ The `tgplc <https://asiimaging.com/docs/tiger_programmable_logic_card>`_ control
             shutter:
               hardware:
                 type: ASI
-                axis: [1-8]
+                axis: 2
                 min: 0.0
                 max: 5.0
+                port: COM4
 
 |
 

docs/source/05_reference/api.rst

@@ -8,6 +8,7 @@ Software API
 
    navigate.config
    navigate.controller
+   navigate.controller.configurator
    navigate.log_files
    navigate.model
    navigate.tools

src/navigate/config/configuration_database.py

@@ -108,7 +108,7 @@
 
 daq_device_types = {
     "National Instruments": "NI",
-    "Applied Scientific Instrumentation": "ASI",
+    "Applied Scientific Instrumentation": ("ASI", "asi"),
     "Virtual Device": "Synthetic",
 }
 

src/navigate/model/device_startup_functions.py

@@ -539,9 +539,7 @@ def start_daq(
 
         return NIDAQ(configuration)
 
-    elif device_type == "asi.ASI":
-        # from navigate.model.devices.daq.asi import ASIDaq
-        # name = "Microscope-0"
+    elif device_type == "ASI":
         return start_device(name, configuration, "daq")
 
     elif device_type.lower().startswith("synthetic"):

src/navigate/model/devices/laser/asi.py

@@ -80,7 +80,7 @@ def __init__(self, microscope_name, device_connection, configuration, device_id:
             "laser"
         ][device_id]["onoff"]["hardware"].get("type", None)
 
-        if analog == "asi.ASI" and digital == "asi.ASI":
+        if "ASI" in analog and "ASI" in digital:
             modulation_type = "mixed"
             #: float: The minimum digital modulation voltage.
             self.laser_min_do = self.device_config["onoff"]["hardware"]["min"]
@@ -93,15 +93,15 @@ def __init__(self, microscope_name, device_connection, configuration, device_id:
             #: str: Output axes on Tiger Controller
             self.analog_axis = self.device_config["power"]["hardware"]["axis"]
             self.digital_axis = self.device_config["onoff"]["hardware"]["axis"]
-        elif analog == "asi.ASI":
+        elif "ASI" in analog:
             modulation_type = "analog"
             #: float: The minimum analog modulation voltage.
             self.laser_min_ao = self.device_config["power"]["hardware"]["min"]
             #: float: The maximum analog modulation voltage.
             self.laser_max_ao = self.device_config["power"]["hardware"]["max"]
             #: str: Output axis on Tiger Controller
             self.analog_axis = self.device_config["power"]["hardware"]["axis"]
-        elif digital == "asi.ASI":
+        elif "ASI" in digital:
             modulation_type = "digital"
             #: float: The minimum digital modulation voltage.
             self.laser_min_do = self.device_config["onoff"]["hardware"]["min"]

src/navigate/model/microscope.py

@@ -564,11 +564,11 @@ def end_acquisition(self) -> None:
         4 must be manually shut off).
         """
         self.daq.stop_acquisition()
-        galvo_type = self.configuration["configuration"]["microscopes"][
-            self.microscope_name
-        ]["galvo"][0]["hardware"]["type"]
-        if galvo_type == "asi.ASI":
-            for k in self.galvo:
+        for i, k in enumerate(self.galvo):
+            galvo_type = self.configuration["configuration"]["microscopes"][
+                self.microscope_name
+            ]["galvo"][i]["hardware"]["type"]            
+            if galvo_type in ("asi.ASI", "ASI"):
                 self.galvo[k].turn_off()
 
         self.stop_stage()