From c609e8a3e88c703f944f3cd3001416f1c13dda29 Mon Sep 17 00:00:00 2001
From: Talley Lambert <talley.lambert@gmail.com>
Date: Tue, 26 Sep 2023 17:03:25 -0400
Subject: [PATCH] feat: make af-device name optional (#145)

* feat: make af-device name optional

* add tests
---
 src/useq/_actions.py            | 17 ++++++++++-------
 src/useq/_hardware_autofocus.py | 11 +++++++----
 tests/test_autofocus.py         |  9 +++++++++
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/src/useq/_actions.py b/src/useq/_actions.py
index d3399fab..c3faf421 100644
--- a/src/useq/_actions.py
+++ b/src/useq/_actions.py
@@ -1,4 +1,4 @@
-from typing import Union
+from typing import Optional, Union
 
 from typing_extensions import Literal
 
@@ -43,18 +43,21 @@ class HardwareAutofocus(Action):
     ----------
     type : Literal["hardware_autofocus"]
         This action can be used to trigger hardware autofocus.
-    autofocus_device_name : str
-        The name of the hardware autofocus device.
-    autofocus_motor_offset: float
+    autofocus_device_name : str, optional
+        The name of the autofocus offset motor device (if applicable).  If `None`,
+        acquisition engines may attempt to set the offset however they see fit (such as
+        using a current or default autofocus device.)
+    autofocus_motor_offset: float, optional
         Before autofocus is performed, the autofocus motor should be moved to this
-        offset.
+        offset, if applicable. (Not all autofocus devices have an offset motor.)
+        If None, the autofocus motor should not be moved.
     max_retries : int
         The number of retries if autofocus fails. By default, 3.
     """
 
     type: Literal["hardware_autofocus"] = "hardware_autofocus"
-    autofocus_device_name: str
-    autofocus_motor_offset: float
+    autofocus_device_name: Optional[str] = None
+    autofocus_motor_offset: Optional[float] = None
     max_retries: int = 3
 
 
diff --git a/src/useq/_hardware_autofocus.py b/src/useq/_hardware_autofocus.py
index 23c5da1d..d41da8d7 100644
--- a/src/useq/_hardware_autofocus.py
+++ b/src/useq/_hardware_autofocus.py
@@ -12,14 +12,17 @@ class AutoFocusPlan(FrozenModel):
 
     Attributes
     ----------
-    autofocus_device_name : str
-        Name of the hardware autofocus z device.
+    autofocus_device_name : str | None
+        Optional name of the offset motor device.  If `None`, acquisition engines may
+        attempt to set the offset however they see fit (such as using a current
+        or default autofocus device.)
     autofocus_motor_offset : float | None
         Before autofocus is performed, the autofocus motor should be moved to this
-        offset.
+        offset, if applicable. (Not all autofocus devices have an offset motor.)
+        If None, the autofocus motor should not be moved.
     """
 
-    autofocus_device_name: str
+    autofocus_device_name: Optional[str] = None
     autofocus_motor_offset: Optional[float] = None
 
     def as_action(self) -> HardwareAutofocus:
diff --git a/tests/test_autofocus.py b/tests/test_autofocus.py
index 4539a448..cf30aafc 100644
--- a/tests/test_autofocus.py
+++ b/tests/test_autofocus.py
@@ -113,3 +113,12 @@ def test_autofocus_z_pos_multi_plans() -> None:
     )
 
     assert all(e.z_pos == 200 for e in mda if isinstance(e.action, HardwareAutofocus))
+
+
+def test_af_no_name() -> None:
+    list(
+        MDASequence(
+            time_plan={"interval": 1, "loops": 2},
+            autofocus_plan=AxesBasedAF(axes=("t", "c")),
+        )
+    )