Merge pull request #1024 from TheDeanLab/docs

Docs

docs/source/user_guide/communication_challenges.rst

@@ -0,0 +1,61 @@
+========================
+Hardware Troubleshooting
+========================
+
+In this section, we outline some common challenges encountered in setting up a
+microscope system and provide solutions to address these issues effectively.
+
+-------------------------------------
+
+.. _obis_tiger_connection:
+
+Intermittent USB Connectivity
+#############################
+
+Overview
+--------
+For setups that include **Coherent OBIS lasers** and an **ASI Tiger Controller**, some
+users have reported intermittent connection issues. These errors
+were first observed at CU Boulder, where the Coherent OBIS laser and the ASI
+Tiger controller appeared to experience conflicts over COM port assignments.
+
+Reported Issues
+---------------
+1. **Connection Failure with the ASI Stage**:
+   - The ASI stage intermittently fails to connect, with an error message reading:
+   "Unable to connect to the serial port: Access to the port ‘COM13’ is denied."
+   - This error has occurred in both the Tiger control software and *navigate*.
+
+2. **Error Logs in Navigate**:
+   - In the navigate software, the error is logged as:
+   `"model - ERROR - asi: ASI stage connection failed"`.
+
+3. **Stage Malfunction During Imaging**:
+   - When a connection was achieved, the ASI stages exhibited sporadic movements during
+   image acquisition.
+
+Suspected Cause
+---------------
+Upon investigation, the issue appeared to stem from **port competition** between the Coherent OBIS laser and the ASI Tiger controller. In this setup:
+   - The ASI Tiger controller was assigned to **COM port 13**.
+   - The Coherent OBIS 561 nm laser was initially assigned to **COM port 14**.
+
+Despite this configuration, the Coherent OBIS laser intermittently attempted to connect through COM port 13, effectively displacing the ASI Tiger controller's access to the port and causing a conflict.
+
+Solution and Verification
+-------------------------
+To address this issue, the following corrective actions were implemented:
+
+1. **Reassigning the Coherent OBIS Laser**:
+   - The Coherent OBIS laser was reassigned from COM port 14 to **COM port 9** to
+   prevent interference with the ASI Tiger controller. This port was chosen since it was
+   in close proximity to the other Coherent OBIS laser instances.
+
+2. **System Reboot**:
+   - Following the reassignment, both the computer and hardware were rebooted to ensure the new COM port configurations took effect.
+
+Results
+-------
+Since reassigning the Coherent OBIS laser to COM port 9, the ASI stage has maintained
+a stable connection on COM port 13 without interruptions and uncontrolled stage
+movements are no longer occurring.

docs/source/user_guide/hardware/laser.rst

@@ -25,6 +25,13 @@ modulation.
     for the slew rate from the data acquisition card to be insufficient to drive the modulation
     of the laser if the laser is set to an analog modulation mode.
 
+.. note::
+    Users have reported intermittent connection issues at random intervals arising
+    from USB-based communication instance with Coherent Obis controllers. Specifically,
+    these errors were observed as a conflict over COM port assignments between the
+    Coherent OBIS laser and the ASI Tiger controller. These issues are discussed in
+    depth in the :ref:`communication challenges <obis_tiger_connection>` section.
+
 
 .. collapse:: Configuration File
 

docs/source/user_guide/hardware/stage.rst

@@ -40,7 +40,10 @@ first establish communication with the device using `ASI provided software <http
 
     - 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.
 
 .. warning::
     If you are using the FTP-2000 stage, do not change the F stage axis. This

docs/source/user_guide/setup_microscope.rst

@@ -7,3 +7,4 @@ Setting Up A Microscope
 
    software_configuration
    multiple_cameras
+   communication_challenges