Add speedrate parameter for insert() / eject() functions in `wi…

…regrid_actuator` (#574)

* update wiregrid_actuator.rst

* add speedrate parameter in insert/eject() in wiregrid_actuator

* add high_speed (bool) parameters to insert/eject

* Add method signature overrides and format docstrings

---------

Co-authored-by: d1ssk <[email protected]>
Co-authored-by: Brian Koopman <[email protected]>

docs/agents/wiregrid_actuator.rst

@@ -98,7 +98,10 @@ In the test mode, you can choose the moving distance [mm] and speed rate.
 The parameter details are here:
 
 - distance: Actuator moving distance [mm] (default: 10)
-- speedrate: Actuator speed rate [0.0, 1.0] (default: 0.2)
+- speedrate: Actuator speed rate [0.0, 5.0] (default: 0.2)
+
+.. warning::
+  DO NOT use ``speedrate > 1.0`` if ``el != 90 deg``!
 
 
 Hardware Configurations

socs/agents/wiregrid_actuator/agent.py

@@ -276,13 +276,29 @@ def _eject(self, main_distance=920, main_speedrate=1.0):
     ##################
     # Return: status(True or False), message
 
+    @ocs_agent.param('speedrate', default=1.0, type=float,
+                     check=lambda x: 0.0 < x <= 5.0)
+    @ocs_agent.param('high_speed', default=False, type=bool)
     def insert(self, session, params=None):
-        """insert()
+        """insert(speedrate=1.0, high_speed=False)
 
         **Task** - Insert the wire-grid into the forebaffle interface above the
         SAT.
 
+        Parameters:
+            speedrate (float): Actuator speed rate [0.0, 5.0] (default: 1.0)
+                DO NOT use ``speedrate > 1.0`` if ``el != 90 deg``!
+            high_speed (bool): If False, speedrate is limited to 1.0. Defaults
+                to False.
         """
+        # Get parameters
+        speedrate = params.get('speedrate')
+        high_speed = params.get('high_speed')
+        if not high_speed:
+            speedrate = min(speedrate, 1.0)
+        self.log.info('insert(): set speed rate = {}'
+                      .format(speedrate))
+
         with self.lock.acquire_timeout(timeout=3, job='insert') as acquired:
             if not acquired:
                 self.log.warn(
@@ -293,22 +309,38 @@ def insert(self, session, params=None):
             # Wait for a second before moving
             time.sleep(1)
             # Moving commands
-            ret, msg = self._insert(920, 1.0)
+            ret, msg = self._insert(920, speedrate)
             if not ret:
                 msg = 'insert(): '\
-                      'ERROR!: Failed insert() in _insert(850,1.0) | {}'\
-                      .format(msg)
+                      'ERROR!: Failed insert() in _insert(920,{}) | {}'\
+                      .format(speedrate, msg)
                 self.log.error(msg)
                 return False, msg
             return True, 'insert(): Successfully finish!'
 
+    @ocs_agent.param('speedrate', default=1.0, type=float,
+                     check=lambda x: 0.0 < x <= 5.0)
+    @ocs_agent.param('high_speed', default=False, type=bool)
     def eject(self, session, params=None):
-        """eject()
+        """eject(speedrate=1.0, high_speed=False)
 
         **Task** - Eject the wire-grid from the forebaffle interface above the
         SAT.
 
+        Parameters:
+            speedrate (float): Actuator speed rate [0.0, 5.0] (default: 1.0)
+                DO NOT use ``speedrate > 1.0`` if ``el != 90 deg``!
+            high_speed (bool): If False, speedrate is limited to 1.0. Defaults
+                to False.
         """
+        # Get parameters
+        speedrate = params.get('speedrate')
+        high_speed = params.get('high_speed')
+        if not high_speed:
+            speedrate = min(speedrate, 1.0)
+        self.log.info('eject(): set speed rate = {}'
+                      .format(speedrate))
+
         with self.lock.acquire_timeout(timeout=3, job='eject') as acquired:
             if not acquired:
                 self.log.warn(
@@ -319,10 +351,10 @@ def eject(self, session, params=None):
             # Wait for a second before moving
             time.sleep(1)
             # Moving commands
-            ret, msg = self._eject(920, 1.0)
+            ret, msg = self._eject(920, speedrate)
             if not ret:
-                msg = 'eject(): ERROR!: Failed in _eject(850,1.0) | {}'\
-                    .format(msg)
+                msg = 'eject(): ERROR!: Failed in _eject(920,{}) | {}'\
+                    .format(speedrate, msg)
                 self.log.error(msg)
                 return False, msg
             return True, 'eject(): Successfully finish!'
@@ -451,20 +483,27 @@ def eject_homing(self, session, params=None):
 
     @ocs_agent.param('distance', default=10., type=float)
     @ocs_agent.param('speedrate', default=0.2, type=float,
-                     check=lambda x: 0.0 < x <= 1.0)
+                     check=lambda x: 0.0 < x <= 5.0)
+    @ocs_agent.param('high_speed', default=False, type=bool)
     def insert_test(self, session, params):
-        """insert_test(distance=10, speedrate=0.1)
+        """insert_test(distance=10, speedrate=0.2, high_speed=False)
 
         **Task** - Insert slowly the wire-grid into the forebaffle interface
         above the SAT with a small distance.
 
         Parameters:
             distance (float): Actuator moving distance [mm] (default: 10)
-            speedrate (float): Actuator speed rate [0.0, 1.0] (default: 0.2)
+            speedrate (float): Actuator speed rate [0.0, 5.0] (default: 0.2)
+                DO NOT use ``speedrate > 1.0`` if ``el != 90 deg``!
+            high_speed (bool): If False, speedrate is limited to 1.0. Defaults
+                to False.
         """
         # Get parameters
         distance = params.get('distance')
         speedrate = params.get('speedrate')
+        high_speed = params.get('high_speed')
+        if not high_speed:
+            speedrate = min(speedrate, 1.0)
         self.log.info('insert_test(): set distance   = {} mm'
                       .format(distance))
         self.log.info('insert_test(): set speed rate = {}'
@@ -502,20 +541,27 @@ def insert_test(self, session, params):
 
     @ocs_agent.param('distance', default=10., type=float)
     @ocs_agent.param('speedrate', default=0.2, type=float,
-                     check=lambda x: 0.0 < x <= 1.0)
+                     check=lambda x: 0.0 < x <= 5.0)
+    @ocs_agent.param('high_speed', default=False, type=bool)
     def eject_test(self, session, params):
-        """eject_test(distance=10, speedrate=0.1)
+        """eject_test(distance=10, speedrate=0.2, high_speed=False)
 
         **Task** - Eject slowly the wire-grid from the forebaffle interface
         above the SAT with a small distance.
 
         Parameters:
-            distance:  Actuator moving distance [mm] (default: 10)
-            speedrate: Actuator speed rate [0.0, 1.0] (default: 0.2)
+            distance (float): Actuator moving distance [mm] (default: 10)
+            speedrate (float): Actuator speed rate [0.0, 5.0] (default: 0.2)
+                DO NOT use ``speedrate > 1.0`` if ``el != 90 deg``!
+            high_speed (bool): If False, speedrate is limited to 1.0. Defaults
+                to False.
         """
         # Get parameters
         distance = params.get('distance', 10)
         speedrate = params.get('speedrate', 0.2)
+        high_speed = params.get('high_speed')
+        if not high_speed:
+            speedrate = min(speedrate, 1.0)
         self.log.info('eject_test(): set distance   = {} mm'
                       .format(distance))
         self.log.info('eject_test(): set speed rate = {}'