Add z-direction calibration action to sangaboard

src/openflexure_microscope_server/things/stage/__init__.py

@@ -166,8 +166,14 @@ class BaseStage(lt.Thing):
     )
     """Used to convert coordinates between the program frame and the hardware frame."""
 
-    calibration_required: bool = lt.setting(default=False)
-    """Whether calibration of the stage z axis is required."""
+    @lt.property
+    def calibration_required(self) -> bool:
+        """Whether the stage requires calibration.
+
+        Currently the only calibration method for the stage is the z-gear rotation
+        direction in the sangaboard stage.
+        """
+        return False
 
     def update_position(self) -> None:
         """Update the position property from the stage."""
@@ -538,8 +544,3 @@ class BaseStage(lt.Thing):
         This method provides the interface expected by the camera_stage_mapping.
         """
         self.move_absolute(x=xyz_pos[0], y=xyz_pos[1], z=xyz_pos[2])
-
-    @lt.action
-    def mark_calibration_complete(self) -> None:
-        """Mark stage calibration as complete."""
-        self.calibration_required = False

src/openflexure_microscope_server/things/stage/sangaboard.py

@@ -80,6 +80,37 @@ class SangaboardThing(BaseStage):
     )
     """Used to convert coordinates between the program frame and the hardware frame."""
 
+    z_axis_calibrated: bool = lt.setting(default=False, readonly=True)
+
+    @lt.property
+    def calibration_required(self) -> bool:
+        """Whether the stage requires calibration.
+
+        Return False only if z-direction has been calibrated.
+        """
+        return not self.z_axis_calibrated
+
+    @lt.action
+    def calibrate_z_direction(
+        self, positive_motion: Literal["clockwise", "anti-clockwise"]
+    ) -> None:
+        """Calibrate the z motor direction based on the gear rotation direction.
+
+        Positive z motion should turn the exposed gear anti-clockwise. Calling this
+        action marks the z motor as calibrated.
+
+        :param positive_motion: The direction the gear moved during pisitive z motion.
+        """
+        if positive_motion == "clockwise":
+            # Wrong direction, mark as such.
+            self.invert_axis_direction(axis="z")
+        elif positive_motion != "anti-clockwise":
+            raise ValueError(
+                "Motion should be reported as either 'clockwise' or 'anti-clockwise'."
+            )
+        # Set z_axis_calibrated to true once this function is called.
+        self.z_axis_calibrated = True
+
     def _hardware_update_position(self) -> None:
         """Read position from the stage and set internal attribute _hardware_position.
 
@@ -236,6 +267,3 @@ class SangaboardThing(BaseStage):
                 self._sangaboard.query(f"{led_command} {on_brightness}")
             else:
                 self._sangaboard.query(f"{led_command} 0")
-
-    calibration_required: bool = lt.setting(default=True)
-    """By default, Sangaboard stage will require calibration of z direction."""