Merge pull request #877 from TheDeanLab/add-new-device

Add new device documentation

Author: AdvancedImagingUTSW

docs/source/add_new_device.rst

@@ -0,0 +1,149 @@
+======================================
+ Add a New Hardware Device (Advanced)
+======================================
+
+**navigate** includes several standard hardware device types. These include:
+
+- Cameras
+- Data Acquisition Cards
+- Filter Wheels
+- Galvo Scanners
+- Lasers
+- Deformable Mirrors
+- Remote Focusing Systems
+- Shutters
+- Stages
+- Zoom Devices
+
+To add a new piece of hardware to one of these device types requires knowledge about
+the software's device abstraction layer. Here’s a detailed guide to help you
+integrate new ``CustomStage`` device into **navigate**. The same principles work for
+other device types.
+
+.. note::
+    A strong knowledge of Python and object-oriented programming is required to
+    integrate new hardware devices into **navigate**.
+
+----------------
+
+What is the Device Abstraction Layer?
+-------------------------------------
+
+To ensure compatibility and extendability, **navigate** utilizes a device abstraction
+layer, which allows the same commands to be used across different hardware devices.
+For example, all stages in **navigate** are programmed to include the `stop()`
+command, which can be used to stop the stage's movement. When someone
+hits the :guilabel:`Stop Stage` button on the GUI, this action is relayed from the
+``Controller`` to the ``Model`` and ultimately the ``CustomStage``, which communicates
+with the hardware in a device-specific format to stop the stage's movement.
+
+--------------
+
+Device Integration Approaches
+-----------------------------
+
+There are two primary approaches to integrating new hardware into **navigate**:
+
+- **Plugin**:
+    If you want to continue to work with an up-to-date version of **navigate**, consider
+    integrating your new hardware device as a plugin. This allows you to pull
+    updates from the main repository without losing your custom hardware integration.
+    It also allows you to integrate non-standard device types.
+    Learn more about the plugin architecture :doc:`here <plugin/plugin_home>`, and
+    how to write a custom plugin :doc:`here <advanced>`.
+- **Fork**:
+    Alternatively, you can fork the **navigate** repository on GitHub and modify it
+    directly. This is useful for custom, in-house developments. In select
+    circumstances, you can contribute your changes back to the main repository
+    through a pull request. Please contact the **navigate** development team for
+    guidance on this approach.
+
+--------------
+
+Device Class Creation
+---------------------
+-   New hardware devices must have a corresponding device class in navigate. To ensure
+    consistency and reduce redundancy, each device must inherit the appropriate abstract
+    base class. For instance, a ``CustomStage`` device would inherit from ``StageBase``.
+-   Classes should follow CamelCase naming conventions and reflect the device they
+    control (e.g., ``NewportStage`` for a stage from the manufacturer Newport).
+-   Place the new device class within the appropriate device directory,
+    `src/navigate/model/devices/`.
+-   Place related API or hardware documentation within the appropriate manufacturer
+    directory, typically under `src/navigate/model/devices/APIs/`.
+
+--------------
+
+Establish Device Communication
+------------------------------
+
+-   Each device requires a unique method to initialize a connection, which may
+    involve APIs, serial communication, or other protocols. This method should be
+    separate from the device class and is typically located at the beginning of the
+    device file.
+-   For example, a function named `build_custom_stage_connection()` would handle
+    the connection setup for ``CustomStage`` class.
+-   By separating the connection setup from the device class, you can easily
+    interact with the hardware device outside of the larger **navigate** ecosystem,
+    which can be useful for debugging and testing (e.g., within a Jupyter notebook).
+
+--------------
+
+Device Class Constructor
+------------------------
+
+-   The constructor for the device class (`__init__`) should accept parameters for
+    the `microscope_name`, `device_connection`, `configuration_file`, and an optional
+    `device_ID` (useful when multiple instances of the same device are used).
+-   The constructor should load and enforce device settings from the
+    `configuration_file`. For a new stage, this could be defining the axes mapping
+    between **navigate** and the device, `{x:'X', y:'Y', z:'Z'}`.
+-   Ensure the device class uses the connection established by your
+    `build_custom_stage_connection` method.
+
+--------------
+
+Device Class Methods
+--------------------
+
+-   Implement any necessary device-specific methods within your device class.
+-   Essential methods are inherited from the base class (e.g., ``StageBase`` for the
+    ``CustomStage``), but you can override them or add new methods as needed for
+    specialized functionality.
+
+--------------
+
+Startup and Configuration
+-------------------------
+
+-   Utilize or modify methods within `src/navigate/model/device_startup_functions` to
+    configure and start your device upon system initialization.
+-   These functions should handle configuration parsing and the device communication
+    setup.
+-   Implement a retry mechanism, such as `auto_redial`, to handle communication
+    issues robustly, attempting multiple times before failing.
+
+--------------
+
+Integration with Microscope Object Configurations
+------------------------------------------------
+
+-   Each microscope configuration in **navigate** that uses the new device should
+    receive a reference to the established communication object.
+-   This setup is defined in the *configuration.yaml* and handled within the
+    `device_startup_functions`, ensuring each configuration has access to the
+    necessary hardware.
+
+--------------
+
+Testing and Validation
+----------------------
+-   Thoroughly test the new hardware integration to ensure it functions correctly
+    within navigate, across all intended use cases and configurations.
+-   The naming convention for test files is: `test_` + module name.
+-   Device test files are located in `test\model\devices\`
+-   Device testing utilizes the `pytest` package.
+
+By following these steps, you can effectively integrate new hardware into the
+**navigate** platform, enhancing its functionality and ensuring it meets specific
+experimental needs.

docs/source/advanced.rst

@@ -1,15 +1,15 @@
-==============================
-Write a Custom Plugin (Expert)
-==============================
+=======================================
+Write a Custom Device Plugin (Advanced)
+=======================================
 
 **navigate**'s :doc:`plugin system <plugin/plugin_home>` enables users to
-easily incorporate new devices and integrate new features and acquisition modes. In 
-this guide, we will add a new device, titled ``CustomDevice``, and a dedicated GUI 
+easily incorporate new devices and integrate new features and acquisition modes. In
+this guide, we will add a new device type, titled ``CustomDevice``, and a dedicated GUI
 window to control it. This hypothetical ``CustomDevice`` is capable of moving a certain
-distance, rotating a specified number of degrees, and applying a force to halt its 
+distance, rotating a specified number of degrees, and applying a force to halt its
 movement.
 
-**navigate** plugins are implemented using a Model-View-Controller architecture. The 
+**navigate** plugins are implemented using a Model-View-Controller architecture. The
 model contains the device-specific code, the view contains the GUI code, and the
 controller contains the code that communicates between the model and the view.
 
@@ -18,7 +18,7 @@ controller contains the code that communicates between the model and the view.
 Initial Steps
 -------------
 
-To ease the addition of a new plugin, we have created a template plugin that can be 
+To ease the addition of a new plugin, we have created a template plugin that can be
 used as a starting point.
 
 * Go to `navigate-plugin-template <https://github.com/TheDeanLab/navigate-plugin-template>`_.
@@ -89,9 +89,9 @@ Create a new custom device using the following code.
             }
 
 
-All devices should be accompanied by synthetic versions, which enables the software 
-to run without the hardware connected. Thus, in a manner that is similar to the 
-``CustomDevice`` class, we edit the code in ``synthetic_device.py``, albeit without 
+All devices should be accompanied by synthetic versions, which enables the software
+to run without the hardware connected. Thus, in a manner that is similar to the
+``CustomDevice`` class, we edit the code in ``synthetic_device.py``, albeit without
 any calls to the device itself.
 
 .. code-block:: python
@@ -150,15 +150,15 @@ any calls to the device itself.
             }
 
 
-Edit ``device_startup_functions.py`` to tell **navigate** how to connect to and start 
+Edit ``device_startup_functions.py`` to tell **navigate** how to connect to and start
 the ``CustomDevice``. This is the portion of the code that actually makes a connection
-to the hardware. ``load_device()`` should return an object that can control the 
+to the hardware. ``load_device()`` should return an object that can control the
 hardware.
 
-**navigate** establishes communication with each device independently, and passes the 
-instance of that device to class that controls it (e.g., in this case, the 
-`CustomDevice` class). This allows **navigate** to be initialized with multiple 
-microscope :ref:`configurations <user_guide/software_configuration:configuration file>`, 
+**navigate** establishes communication with each device independently, and passes the
+instance of that device to class that controls it (e.g., in this case, the
+`CustomDevice` class). This allows **navigate** to be initialized with multiple
+microscope :ref:`configurations <user_guide/software_configuration:configuration file>`,
 some of which may share devices.
 
 .. code-block:: python
@@ -325,17 +325,17 @@ to ``custom_device_frame.py``, and edit the code as follows.
 .. tip::
 
     **navigate** comes equipped with a large number of validated widgets,
-    which prevent users from entering invalid values that can crash the program or 
-    result in undesirable outcomes. It is highly recommended that you use these, 
+    which prevent users from entering invalid values that can crash the program or
+    result in undesirable outcomes. It is highly recommended that you use these,
     which include the following:
 
-        * The ``LabelInput`` widget conveniently combines a label and an input widget 
+        * The ``LabelInput`` widget conveniently combines a label and an input widget
           into a single object. It is used to create the ``step_size`` and ``angle``
           widgets in the code above.
         * The ``LabelInput`` widget can accept multiple types of ``input_class`` objects,
-          which can include standard tkinter widgets (e.g., spinbox, entry, etc.) or 
+          which can include standard tkinter widgets (e.g., spinbox, entry, etc.) or
           custom widgets. In this example, we use the ``ttk.Entry`` widget.
-        * Other examples of validated widgets include a ``ValidatedSpinbox``, 
+        * Other examples of validated widgets include a ``ValidatedSpinbox``,
           ``ValidatedEntry``, ``ValidatedCombobox``, and ``ValidatedMixin``.
         * Please see the :any:`navigate.view.custom_widgets` module for more details.
 
@@ -420,17 +420,17 @@ as follows.
             self.parent_controller.execute("stop_custom_device")
 
 
-In each case above, the sub-controller for the ``custom-device`` establishes what 
-actions should take place once a button in the view is clicked. In this case, the 
-methods ``move_device``, ``rotate_device``, and ``stop_device``. This triggers a sequence 
+In each case above, the sub-controller for the ``custom-device`` establishes what
+actions should take place once a button in the view is clicked. In this case, the
+methods ``move_device``, ``rotate_device``, and ``stop_device``. This triggers a sequence
 of events:
 
-    * The sub-controller passes the command to the parent controller, which is the 
+    * The sub-controller passes the command to the parent controller, which is the
       main controller for the software.
-    * The parent controller passes the command to the model, which is operating in 
-      its own sub-process, using an event queue. This eliminates the need for the 
+    * The parent controller passes the command to the model, which is operating in
+      its own sub-process, using an event queue. This eliminates the need for the
       controller to know anything about the model and prevents race conditions.
-    * The model then executes command, and any updates to the controller from the 
+    * The model then executes command, and any updates to the controller from the
       model are relayed using another event queue.
 
 -----------------
@@ -459,18 +459,18 @@ the file ``plugin_acquisition_mode.py``. The plugin folder structure is as follo
         │       └── custom_device/
         │           ├── device_startup_functions.py
         │           ├── custom_device.py
-        │           └── synthetic_device.py              
+        │           └── synthetic_device.py
         ├── view/
         |   └── custom_device_frame.py
         │
-        └── plugin_config.yml 
+        └── plugin_config.yml
 
 
 Install the plugin using one of two methods:
-    * Install a plugin by putting the whole plugin folder directly into 
-      ``navigate/plugins/``. In this example, put ``custom_device`` folder 
+    * Install a plugin by putting the whole plugin folder directly into
+      ``navigate/plugins/``. In this example, put ``custom_device`` folder
       and all its contents into ``navigate/plugins``.
-    * Alernatively, install this plugin through the menu 
+    * Alernatively, install this plugin through the menu
       :menuselection:`Plugins --> Install Plugin` by selecting the plugin folder.
 
 The plugin is ready to use. For this plugin, you can now specify a CustomDevice in the
@@ -489,7 +489,7 @@ The plugin is ready to use. For this plugin, you can now specify a CustomDevice
                 hardware:
                     type: CustomDevice
             ...
-            
+
 
 The ``custom_device`` will be loaded when **navigate** is launched, and it can be
 controlled through the GUI.

docs/source/conf.py

@@ -20,7 +20,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "navigate"
-copyright = "2023, Dean Lab, UT Southwestern Medical Center"
+copyright = "2024, Dean Lab, UT Southwestern Medical Center"
 author = "Dean Lab, UT Southwestern Medical Center"
 
 # The full version, including alpha/beta/rc tags
@@ -111,17 +111,25 @@
 
 # -- LaTeX output options ----------------------------------------------------
 
-latex_elements = {'preamble': r'''
+latex_elements = {
+    "preamble": r"""
                   \usepackage[utf8]{inputenc}
                   \usepackage{enumitem}
                   \setlistdepth{99}
                   \DeclareUnicodeCharacter{03BC}{$\mu$}
-                  ''',
-                  'extraclassoptions': 'openany,oneside'}
+                  """,
+    "extraclassoptions": "openany,oneside",
+}
 
 latex_documents = [
-  ('index', 'navigate.tex', 'navigate Documentation',
-   'Dean Lab, UT Southwestern Medical Center', 'manual', True),
+    (
+        "index",
+        "navigate.tex",
+        "navigate Documentation",
+        "Dean Lab, UT Southwestern Medical Center",
+        "manual",
+        True,
+    ),
 ]
 
-latex_domain_indices = False
+latex_domain_indices = False

docs/source/i_want_to.rst

@@ -2,17 +2,17 @@
 I Want To...
 ============
 
-This section contains how-to documents organized into three levels of difficulty: 
+This section contains how-to documents organized into three levels of difficulty:
 beginner, intermediate, and advanced.
 
 - The beginner how-to is intended for users who have little to no experience with
   computer programming and simply wish to acquire an image.
 
-- The intermediate how-to is intended for users who want to learn how to use the 
+- The intermediate how-to is intended for users who want to learn how to use the
   graphical user interface to create their own smart acquisition workflows.
 
 - The advanced how-to is intended for users who have experience with computer
-  programming and wish to extend the functionality of **navigate** by adding new 
+  programming and wish to extend the functionality of **navigate** by adding new
   devices or writing their own acquisition features.
 
 Through this tiered approach, we hope to provide a gentle introduction to the software
@@ -23,4 +23,5 @@ while also reaching the maximum number of users.
 
    beginner
    intermediate
-   advanced
+   advanced
+   add_new_device