Update ADCore to match ADAravis (#807)

* Add to docstrings and change enum names

* Fix test and rename ImageMode references

* Amend references to old enum names

* Revert to ND identifier

Author: shihab-dls

src/ophyd_async/epics/adandor/_andor_controller.py

@@ -34,7 +34,7 @@ async def prepare(self, trigger_info: TriggerInfo):
             self.driver.num_images.set(
                 trigger_info.total_number_of_triggers or _MAX_NUM_IMAGE
             ),
-            self.driver.image_mode.set(adcore.ImageMode.MULTIPLE),
+            self.driver.image_mode.set(adcore.ADImageMode.MULTIPLE),
         )
 
     def _get_trigger_mode(self, trigger: DetectorTrigger) -> Andor2TriggerMode:

src/ophyd_async/epics/adaravis/_aravis_controller.py

@@ -36,9 +36,9 @@ async def prepare(self, trigger_info: TriggerInfo) -> None:
             raise ValueError(f"ADAravis does not support {trigger_info.trigger}")
 
         if trigger_info.total_number_of_triggers == 0:
-            image_mode = adcore.ImageMode.CONTINUOUS
+            image_mode = adcore.ADImageMode.CONTINUOUS
         else:
-            image_mode = adcore.ImageMode.MULTIPLE
+            image_mode = adcore.ADImageMode.MULTIPLE
         await asyncio.gather(
             self.driver.num_images.set(trigger_info.total_number_of_triggers),
             self.driver.image_mode.set(image_mode),

src/ophyd_async/epics/adcore/__init__.py

@@ -1,3 +1,8 @@
+"""Core components of the areaDetector software.
+
+https://github.com/areaDetector/ADCore
+"""
+
 from ._core_detector import AreaDetector
 from ._core_io import (
     ADBaseDatasetDescriber,
@@ -19,8 +24,8 @@
 from ._tiff_writer import ADTIFFWriter
 from ._utils import (
     ADBaseDataType,
-    FileWriteMode,
-    ImageMode,
+    ADFileWriteMode,
+    ADImageMode,
     NDAttributeDataType,
     NDAttributeParam,
     NDAttributePv,
@@ -48,8 +53,8 @@
     "ADJPEGWriter",
     "SingleTriggerDetector",
     "ADBaseDataType",
-    "FileWriteMode",
-    "ImageMode",
+    "ADFileWriteMode",
+    "ADImageMode",
     "NDAttributePv",
     "NDAttributeParam",
     "NDAttributeDataType",

src/ophyd_async/epics/adcore/_core_io.py

@@ -4,7 +4,7 @@
 from ophyd_async.core import DatasetDescriber, SignalR, SignalRW, StrictEnum
 from ophyd_async.epics.core import EpicsDevice, PvSuffix
 
-from ._utils import ADBaseDataType, FileWriteMode, ImageMode, convert_ad_dtype_to_np
+from ._utils import ADBaseDataType, ADFileWriteMode, ADImageMode, convert_ad_dtype_to_np
 
 
 class ADCallbacks(StrictEnum):
@@ -13,6 +13,12 @@ class ADCallbacks(StrictEnum):
 
 
 class NDArrayBaseIO(EpicsDevice):
+    """Class responsible for passing detector data from drivers to pluglins.
+
+    This mirrors the interface provided by ADCore/db/NDArrayBase.template.
+    See HTML docs at https://areadetector.github.io/areaDetector/ADCore/NDArray.html
+    """
+
     unique_id: A[SignalR[int], PvSuffix("UniqueId_RBV")]
     nd_attributes_file: A[SignalRW[str], PvSuffix("NDAttributesFile")]
     acquire: A[SignalRW[bool], PvSuffix.rbv("Acquire")]
@@ -40,6 +46,12 @@ async def shape(self) -> tuple[int, int]:
 
 
 class NDPluginBaseIO(NDArrayBaseIO):
+    """Base class from which plugins are derived.
+
+    This mirrors the interface provided by ADCore/db/NDPluginBase.template.
+    See HTML docs at https://areadetector.github.io/areaDetector/ADCore/NDPluginDriver.html
+    """
+
     nd_array_port: A[SignalRW[str], PvSuffix.rbv("NDArrayPort")]
     enable_callbacks: A[SignalRW[ADCallbacks], PvSuffix.rbv("EnableCallbacks")]
     nd_array_address: A[SignalRW[int], PvSuffix.rbv("NDArrayAddress")]
@@ -49,7 +61,11 @@ class NDPluginBaseIO(NDArrayBaseIO):
 
 
 class NDPluginStatsIO(NDPluginBaseIO):
-    """Plugin for computing statistics from an image or ROI within an image."""
+    """Plugin for computing statistics from an image or ROI within an image.
+
+    This mirrors the interface provided by ADCore/db/NDStats.template.
+    See HTML docs at https://areadetector.github.io/areaDetector/ADCore/NDPluginStats.html
+    """
 
     # Basic statistics
     compute_statistics: A[SignalRW[bool], PvSuffix.rbv("ComputeStatistics")]
@@ -91,10 +107,16 @@ class ADState(StrictEnum):
 
 
 class ADBaseIO(NDArrayBaseIO):
+    """Base class from which areaDetector drivers are derived.
+
+    This mirrors the interface provided by ADCore/db/ADBase.template.
+    See HTML docs at https://areadetector.github.io/areaDetector/ADCore/ADDriver.html
+    """
+
     acquire_time: A[SignalRW[float], PvSuffix.rbv("AcquireTime")]
     acquire_period: A[SignalRW[float], PvSuffix.rbv("AcquirePeriod")]
     num_images: A[SignalRW[int], PvSuffix.rbv("NumImages")]
-    image_mode: A[SignalRW[ImageMode], PvSuffix.rbv("ImageMode")]
+    image_mode: A[SignalRW[ADImageMode], PvSuffix.rbv("ImageMode")]
     detector_state: A[SignalR[ADState], PvSuffix("DetectorState_RBV")]
 
 
@@ -110,14 +132,20 @@ class ADCompression(StrictEnum):
 
 
 class NDFileIO(NDPluginBaseIO):
+    """Base class from which file plugins are derived.
+
+    This mirrors the interface provided by ADCore/db/NDFile.template.
+    See HTML docs at https://areadetector.github.io/areaDetector/ADCore/NDPluginFile.html
+    """
+
     file_path: A[SignalRW[str], PvSuffix.rbv("FilePath")]
     file_name: A[SignalRW[str], PvSuffix.rbv("FileName")]
     file_path_exists: A[SignalR[bool], PvSuffix("FilePathExists_RBV")]
     file_template: A[SignalRW[str], PvSuffix.rbv("FileTemplate")]
     full_file_name: A[SignalR[str], PvSuffix("FullFileName_RBV")]
     file_number: A[SignalRW[int], PvSuffix("FileNumber")]
     auto_increment: A[SignalRW[bool], PvSuffix("AutoIncrement")]
-    file_write_mode: A[SignalRW[FileWriteMode], PvSuffix.rbv("FileWriteMode")]
+    file_write_mode: A[SignalRW[ADFileWriteMode], PvSuffix.rbv("FileWriteMode")]
     num_capture: A[SignalRW[int], PvSuffix.rbv("NumCapture")]
     num_captured: A[SignalR[int], PvSuffix("NumCaptured_RBV")]
     capture: A[SignalRW[bool], PvSuffix.rbv("Capture")]
@@ -127,6 +155,12 @@ class NDFileIO(NDPluginBaseIO):
 
 
 class NDFileHDFIO(NDFileIO):
+    """Plugin for storing data in HDF5 file format.
+
+    This mirrors the interface provided by ADCore/db/NDFileHDF5.template.
+    See HTML docs at https://areadetector.github.io/areaDetector/ADCore/NDFileHDF5.html
+    """
+
     position_mode: A[SignalRW[bool], PvSuffix.rbv("PositionMode")]
     compression: A[SignalRW[ADCompression], PvSuffix.rbv("Compression")]
     num_extra_dims: A[SignalRW[int], PvSuffix.rbv("NumExtraDims")]

src/ophyd_async/epics/adcore/_core_logic.py

@@ -11,7 +11,7 @@
 )
 
 from ._core_io import ADBaseIO, ADState
-from ._utils import ImageMode, stop_busy_record
+from ._utils import ADImageMode, stop_busy_record
 
 # Default set of states that we should consider "good" i.e. the acquisition
 #  is complete and went well
@@ -44,7 +44,7 @@ async def prepare(self, trigger_info: TriggerInfo) -> None:
         )
         await asyncio.gather(
             self.driver.num_images.set(trigger_info.total_number_of_triggers),
-            self.driver.image_mode.set(ImageMode.MULTIPLE),
+            self.driver.image_mode.set(ADImageMode.MULTIPLE),
         )
 
     async def arm(self):

src/ophyd_async/epics/adcore/_core_writer.py

@@ -29,7 +29,7 @@
     NDFileIO,
     NDPluginBaseIO,
 )
-from ._utils import FileWriteMode
+from ._utils import ADFileWriteMode
 
 NDFileIOT = TypeVar("NDFileIOT", bound=NDFileIO)
 ADWriterT = TypeVar("ADWriterT", bound="ADWriter")
@@ -104,7 +104,7 @@ async def begin_capture(self) -> None:
             # See https://github.com/bluesky/ophyd-async/issues/122
             self.fileio.file_path.set(str(info.directory_path)),
             self.fileio.file_name.set(info.filename),
-            self.fileio.file_write_mode.set(FileWriteMode.STREAM),
+            self.fileio.file_write_mode.set(ADFileWriteMode.STREAM),
             # For non-HDF file writers, use AD file templating mechanism
             # for generating multi-image datasets
             self.fileio.file_template.set(

src/ophyd_async/epics/adcore/_single_trigger.py

@@ -7,7 +7,7 @@
 from ophyd_async.core import StandardReadableFormat as Format
 
 from ._core_io import ADBaseIO, NDPluginBaseIO
-from ._utils import ImageMode
+from ._utils import ADImageMode
 
 
 class SingleTriggerDetector(StandardReadable, Triggerable):
@@ -35,7 +35,7 @@ def __init__(
     @AsyncStatus.wrap
     async def stage(self) -> None:
         await asyncio.gather(
-            self.drv.image_mode.set(ImageMode.SINGLE),
+            self.drv.image_mode.set(ADImageMode.SINGLE),
             self.drv.wait_for_plugins.set(True),
         )
         await super().stage()

src/ophyd_async/epics/adcore/_utils.py

@@ -79,13 +79,13 @@ def convert_param_dtype_to_np(datatype: str) -> str:
     return np_datatype
 
 
-class FileWriteMode(StrictEnum):
+class ADFileWriteMode(StrictEnum):
     SINGLE = "Single"
     CAPTURE = "Capture"
     STREAM = "Stream"
 
 
-class ImageMode(SubsetEnum):
+class ADImageMode(SubsetEnum):
     SINGLE = "Single"
     MULTIPLE = "Multiple"
     CONTINUOUS = "Continuous"

src/ophyd_async/epics/adkinetix/_kinetix_controller.py

@@ -35,7 +35,7 @@ async def prepare(self, trigger_info: TriggerInfo):
                 KINETIX_TRIGGER_MODE_MAP[trigger_info.trigger]
             ),
             self.driver.num_images.set(trigger_info.total_number_of_triggers),
-            self.driver.image_mode.set(adcore.ImageMode.MULTIPLE),
+            self.driver.image_mode.set(adcore.ADImageMode.MULTIPLE),
         )
         if trigger_info.livetime is not None and trigger_info.trigger not in [
             DetectorTrigger.VARIABLE_GATE,

src/ophyd_async/epics/adpilatus/_pilatus_controller.py

@@ -55,7 +55,7 @@ async def prepare(self, trigger_info: TriggerInfo):
                 if trigger_info.total_number_of_triggers == 0
                 else trigger_info.total_number_of_triggers
             ),
-            self.driver.image_mode.set(adcore.ImageMode.MULTIPLE),
+            self.driver.image_mode.set(adcore.ADImageMode.MULTIPLE),
         )
 
     async def arm(self):