Stage: remove need_homed and add may_move_on_enable (#246)

This commit removes the recent `need_homed` abstract property and
optional `home` method (added in 9c50cb9) and adds a new abstract
method `may_move_on_enable`.

This commit also implements the new method in the zaber and ludl
stages.

Author: carandraug

NEWS.rst

@@ -13,6 +13,11 @@ Version 0.7.0 (upcoming)
     `Camera.get_trigger_type` does not return the same as
     `Camera.trigger_type` property.
 
+* Changes to device ABCs:
+
+  * The `Stage` ABC has a new method `may_move_on_enable` to hint
+    whether calling `enable` will cause the stage to move.
+
 * New devices supported:
 
   * Toptica iChrome MLE

microscope/abc.py

@@ -1396,7 +1396,7 @@ class Stage(Device, metaclass=abc.ABCMeta):
     .. code-block:: python
 
         stage = SomeStageDevice()
-        stage.enable() # may trigger a stage move
+        stage.enable()  # may trigger a stage move
 
         # move operations
         stage.move_to({'x': 42.0, 'y': -5.1})
@@ -1447,7 +1447,7 @@ class documentation for hardware specific details.
 
     Some stages need to find a reference position, home, before being
     able to be moved.  If required, this happens automatically during
-    :func:`enable`.
+    :func:`enable` (see also :func:`may_move_on_enable`).
     """
 
     @property
@@ -1468,27 +1468,34 @@ def axes(self) -> typing.Mapping[str, StageAxis]:
         """
         raise NotImplementedError()
 
-    @property
-    def need_homed(self) -> bool:
-        """Boolean flag to say if the stage needs to be homed. Many stages 
-        need to be driven to their limts at startup to find a repeatable zero
-        position and sometimes to find their limits as well. 
-
-        By default this function returns "False". If the stage needs
-        to be homed then this function should be overwritten to return
-        "True" until the homing operation has been performed.
-        Additionaly a stage that needs to be homed should implement a
-        home() fucntion that performs the home move, sets limits and
-        leaves the stage somewhere sensible.  This function should
-        also set the need_homed propety to False.
-
-        Stages that dont need homing can leave this default function
-        and dont need to implment the home() function.
+
+    @abc.abstractmethod
+    def may_move_on_enable(self) -> bool:
+        """Whether calling :func:`enable` is likely to make the stage move.
+
+        Most stages need to be driven to their limits at startup to
+        find a repeatable zero position and sometimes to find their
+        limits as well.  This is typically called "homing".
+
+        Stages that need to "home" differ on how often they need it
+        but they only do it during :func:`enable`.  They may need to
+        move each time `enable` is called, the first time after the
+        `Stage` object has been created, or even only the first time
+        since the device was powered up.
+
+        Note the "*may*" on "may_move_on_enable".  This is because it
+        can be difficult to know for certain if `enable` will cause
+        the stage to home.  Still, knowing that the stage *may* move
+        is essential for safety.  An unexpected movement of the stage,
+        particularly large movements such as moving to the stage
+        limits, can destroy a sample on the stage --- or even worse,
+        it can damage an objective or the stage itself.  When in
+        doubt, implementations should return `True`.
 
         """
-        return False
+        raise NotImplementedError()
+
 
-    
     @property
     def position(self) -> typing.Mapping[str, float]:
         """Map of axis name to their current position.

microscope/controllers/zaber.py

@@ -346,6 +346,9 @@ def _do_enable(self) -> bool:
             self._dev_conn.home()
         return True
 
+    def may_move_on_enable(self) -> bool:
+        return not self._dev_conn.been_homed()
+
     @property
     def axes(self) -> typing.Mapping[str, microscope.abc.StageAxis]:
         return self._axes

microscope/stages/ludl.py

@@ -133,9 +133,6 @@ def __init__(self, port: str, baudrate: int, timeout: float) -> None:
     def is_busy(self):
         pass
 
-    def been_homed(self):
-        return self.homed
-    
     def get_number_axes(self):
         return 2
 
@@ -348,16 +345,22 @@ def _do_enable(self) -> bool:
         # Before a device can moved, it first needs to establish a
         # reference to the home position.  We won't be able to move
         # unless we home it first.
+        if not self.homed:
+            axes=self.axes
+            for axis in axes:
+                self.axes[axis].home()
+            self.homed = True
         return True
 
+
+    def may_move_on_enable(self) -> bool:
+        return not self.homed
+
+
     @property
     def axes(self) -> typing.Mapping[str, microscope.abc.StageAxis]:
         return self._axes
 
-    @property
-    def need_homed(self):
-        return not self.homed
-
     def move_by(self, delta: typing.Mapping[str, float]) -> None:
         """Move specified axes by the specified distance. """
         for axis_name, axis_delta in delta.items():
@@ -375,13 +378,6 @@ def move_to(self, position: typing.Mapping[str, float]) -> None:
             )
         self._dev_conn.wait_until_idle()
 
-    def home(self):
-        if self.need_homed:
-            axes=self.axes
-            for axis in axes:
-                self.axes[axis].home()
-            self.homed = True
-                
 #    def assert_filterwheel_number(self, number: int) -> None:
 #        assert number > 0 and number < 4