ophyd-async 0.7.0a1__tar.gz → 0.8.0__tar.gz

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 2.3.0
+_commit: 2.5.0
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: tom.cobb@diamond.ac.uk
 author_name: Tom Cobb

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/.github/CONTRIBUTING.md

@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua
 
 This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
 
-For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/2.3.0/how-to.html).
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/2.5.0/how-to.html).

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/.github/workflows/_pypi.yml

@@ -15,3 +15,5 @@ jobs:
 
       - name: Publish to PyPI using trusted publishing
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: false

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/.github/workflows/_release.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Create GitHub Release
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: softprops/action-gh-release@c062e08bd532815e2082a85e87e3ef29c3e6d191 # v2.0.8
+        uses: softprops/action-gh-release@e7a8f85e1c67a31e6ed99a94b41bd0b71bbee6b8 # v2.0.9
         with:
           prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
           files: "*"

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/.github/workflows/_test.yml

@@ -49,6 +49,7 @@ jobs:
         with:
           python-version: ${{ inputs.python-version }}
           pip-install: ".[dev]"
+
       - name: Run tests
         run: tox -e tests
 

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/.github/workflows/ci.yml

@@ -20,8 +20,8 @@ jobs:
     if: needs.check.outputs.branch-pr == ''
     strategy:
       matrix:
-        runs-on: ["ubuntu-latest"] # can add windows-latest, macos-latest
-        python-version: ["3.10","3.11"] # 3.12 should be added when p4p is updated
+        runs-on: ["ubuntu-latest", "windows-latest"] # can add macos-latest
+        python-version: ["3.10", "3.11"] # 3.12 should be added when p4p is updated
         include:
           # Include one that runs in the dev environment
           - runs-on: "ubuntu-latest"

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/.pre-commit-config.yaml

@@ -22,3 +22,11 @@ repos:
         entry: ruff format --force-exclude
         types: [python]
         require_serial: true
+
+      - id: import-contracts
+        name: Ensure import directionality
+        pass_filenames: false
+        language: system
+        entry: lint-imports
+        types: [python]
+        require_serial: false

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/Dockerfile

@@ -1,7 +1,7 @@
 # The devcontainer should use the developer target and run as root with podman
 # or docker with user namespaces.
 ARG PYTHON_VERSION=3.11
-FROM python:${PYTHON_VERSION} as developer
+FROM python:${PYTHON_VERSION} AS developer
 
 # Allow Qt 6 (pyside6) UI to work in the container - also see apt-get below
 ENV MPLBACKEND=QtAgg

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ophyd-async
-Version: 0.7.0a1
+Version: 0.8.0
 Summary: Asynchronous Bluesky hardware abstraction code, compatible with control systems like EPICS and Tango
 Author-email: Tom Cobb <tom.cobb@diamond.ac.uk>
 License: BSD 3-Clause License
@@ -41,12 +41,12 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: networkx>=2.0
-Requires-Dist: numpy<2.0.0
+Requires-Dist: numpy
 Requires-Dist: packaging
 Requires-Dist: pint
-Requires-Dist: bluesky>=1.13.0a3
-Requires-Dist: event_model
-Requires-Dist: p4p
+Requires-Dist: bluesky>=1.13
+Requires-Dist: event-model>=1.22.1
+Requires-Dist: p4p>=4.2.0a3
 Requires-Dist: pyyaml
 Requires-Dist: colorlog
 Requires-Dist: pydantic>=2.0
@@ -64,13 +64,10 @@ Requires-Dist: ophyd_async[pva]; extra == "dev"
 Requires-Dist: ophyd_async[sim]; extra == "dev"
 Requires-Dist: ophyd_async[ca]; extra == "dev"
 Requires-Dist: ophyd_async[tango]; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: flake8; extra == "dev"
-Requires-Dist: flake8-isort; extra == "dev"
-Requires-Dist: Flake8-pyproject; extra == "dev"
 Requires-Dist: inflection; extra == "dev"
 Requires-Dist: ipython; extra == "dev"
 Requires-Dist: ipywidgets; extra == "dev"
+Requires-Dist: import-linter; extra == "dev"
 Requires-Dist: matplotlib; extra == "dev"
 Requires-Dist: myst-parser; extra == "dev"
 Requires-Dist: numpydoc; extra == "dev"
@@ -104,9 +101,9 @@ Requires-Dist: types-pyyaml; extra == "dev"
 [![CI](https://github.com/bluesky/ophyd-async/actions/workflows/ci.yml/badge.svg)](https://github.com/bluesky/ophyd-async/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/bluesky/ophyd-async/branch/main/graph/badge.svg)](https://codecov.io/gh/bluesky/ophyd-async)
 [![PyPI](https://img.shields.io/pypi/v/ophyd-async.svg)](https://pypi.org/project/ophyd-async)
-[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://choosealicense.com/licenses/bsd-3-clause)
 
-# ophyd-async
+# ![ophyd-async](https://raw.githubusercontent.com/bluesky/ophyd-async/main/docs/images/ophyd-async-logo.svg)
 
 Asynchronous Bluesky hardware abstraction code, compatible with control systems like EPICS and Tango.
 
@@ -116,7 +113,7 @@ Asynchronous Bluesky hardware abstraction code, compatible with control systems
 | Documentation |      <https://bluesky.github.io/ophyd-async>      |
 |   Releases    | <https://github.com/bluesky/ophyd-async/releases> |
 
-Ophyd-async is a Python library for asynchronously interfacing with hardware, intended to 
+Ophyd-async is a Python library for asynchronously interfacing with hardware, intended to
 be used as an abstraction layer that enables experiment orchestration and data acquisition code to operate above the specifics of particular devices and control
 systems.
 

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/README.md

@@ -1,9 +1,9 @@
 [![CI](https://github.com/bluesky/ophyd-async/actions/workflows/ci.yml/badge.svg)](https://github.com/bluesky/ophyd-async/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/bluesky/ophyd-async/branch/main/graph/badge.svg)](https://codecov.io/gh/bluesky/ophyd-async)
 [![PyPI](https://img.shields.io/pypi/v/ophyd-async.svg)](https://pypi.org/project/ophyd-async)
-[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://choosealicense.com/licenses/bsd-3-clause)
 
-# ophyd-async
+# ![ophyd-async](https://raw.githubusercontent.com/bluesky/ophyd-async/main/docs/images/ophyd-async-logo.svg)
 
 Asynchronous Bluesky hardware abstraction code, compatible with control systems like EPICS and Tango.
 
@@ -13,7 +13,7 @@ Asynchronous Bluesky hardware abstraction code, compatible with control systems
 | Documentation |      <https://bluesky.github.io/ophyd-async>      |
 |   Releases    | <https://github.com/bluesky/ophyd-async/releases> |
 
-Ophyd-async is a Python library for asynchronously interfacing with hardware, intended to 
+Ophyd-async is a Python library for asynchronously interfacing with hardware, intended to
 be used as an abstraction layer that enables experiment orchestration and data acquisition code to operate above the specifics of particular devices and control
 systems.
 

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/docs/conf.py

@@ -188,9 +188,6 @@ if not switcher_exists:
 # will fix the switcher at the end of the docs workflow, but never gets a chance
 # to complete as the docs build warns and fails.
 html_theme_options = {
-    "logo": {
-        "text": project,
-    },
     "use_edit_page_button": True,
     "github_url": f"https://github.com/{github_user}/{github_repo}",
     "icon_links": [
@@ -230,8 +227,8 @@ html_show_sphinx = False
 html_show_copyright = False
 
 # Logo
-html_logo = "images/bluesky_ophyd_logo.svg"
-html_favicon = "images/ophyd_favicon.svg"
+html_logo = "images/ophyd-async-logo.svg"
+html_favicon = "images/ophyd-favicon.svg"
 
 # If False and a module has the __all__ attribute set, autosummary documents
 # every member listed in __all__ and no others. Default is True

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/docs/examples/foo_detector.py

@@ -10,7 +10,7 @@ from ophyd_async.core import (
     StandardDetector,
 )
 from ophyd_async.epics import adcore
-from ophyd_async.epics.signal import epics_signal_rw_rbv
+from ophyd_async.epics.core import epics_signal_rw_rbv
 
 
 class FooDriver(adcore.ADBaseIO):

ophyd_async-0.8.0/docs/explanations/decisions/0008-signal-types.md

@@ -0,0 +1,159 @@
+# 8. Settle on Signal Types
+Date: 2024-10-18
+
+## Status
+
+Accepted
+
+## Context
+
+At present, soft Signals allow any sort of datatype, while CA, PVA, Tango restrict these to what the control system allows. This means that some soft signals when `describe()` is called on them will give `dtype=object` which is not understood by downstream tools. It also means that load/save will not necessarily understand how to serialize results. Finally we now require `dtype_numpy` for tiled, so arbitrary object types are not suitable even if they are serializable. We should restrict the datatypes allowed in Signals to objects that are serializable and are sensible to add support for in downstream tools.
+
+## Decision
+
+We will allow the following:
+- Primitives:
+    - `bool`
+    - `int`
+    - `float`
+    - `str`
+- Enums:
+    - `StrictEnum` subclass which will be checked to have the same members as the CS
+    - `SubsetEnum` subclass which will be checked to be a subset of the CS members
+- 1D arrays:
+    - `Array1D[np.bool_]`
+    - `Array1D[np.int8]`
+    - `Array1D[np.uint8]`
+    - `Array1D[np.int16]`
+    - `Array1D[np.uint16]`
+    - `Array1D[np.int32]`
+    - `Array1D[np.uint32]`
+    - `Array1D[np.int64]`
+    - `Array1D[np.uint64]`
+    - `Array1D[np.float32]`
+    - `Array1D[np.float64]`
+    - `Sequence[str]`
+    - `Sequence[MyEnum]` where `MyEnum` is a subclass of `StrictEnum` or `SubsetEnum`
+- Specific structures:
+    - `np.ndarray` to represent arrays where dimensionality and dtype can change and must be read from CS
+    - `Table` subclass (which is a pydantic `BaseModel`) where all members are 1D arrays
+
+## Consequences
+
+Clients will be expected to understand:
+- Python primitives (with Enums serializing as strings)
+- Numpy arrays
+- Pydantic BaseModels
+
+All of the above have sensible `dtype_numpy` fields, but `Table` will give a structured row-wise `dtype_numpy`, while the data will be serialized in a column-wise fashion.
+
+The following breaking changes will be made to ophyd-async:
+
+## pvi structure changes
+Structure now read from `.value` rather than `.pvi`. Supported in FastCS. Requires at least PandABlocks-ioc 0.10.0
+## `StrictEnum` is now requried for all strictly checked `Enums`
+```python
+# old
+from enum import Enum
+class MyEnum(str, Enum):
+    ONE = "one"
+    TWO = "two"
+# new
+from ophyd_async.core import StrictEnum
+class MyEnum(StrictEnum):
+    ONE = "one"
+    TWO = "two"
+```
+## `SubsetEnum` is now an `Enum` subclass:
+```python
+from ophyd_async.core import SubsetEnum
+# old
+MySubsetEnum = SubsetEnum["one", "two"]
+# new
+class MySubsetEnum(SubsetEnum):
+    ONE = "one"
+    TWO = "two"
+```
+## Use python primitives for scalar types instead of numpy types
+```python
+# old
+import numpy as np
+x = epics_signal_rw(np.int32, "PV")
+# new
+x = epics_signal_rw(int, "PV")
+```
+## Use `Array1D` for 1D arrays instead of `npt.NDArray`
+```python
+import numpy as np
+# old
+import numpy.typing as npt
+x = epics_signal_rw(npt.NDArray[np.int32], "PV")
+# new
+from ophyd_async.core import Array1D
+x = epics_signal_rw(Array1D[np.int32], "PV")
+```
+## Use `Sequence[str]` for arrays of strings instead of `npt.NDArray[np.str_]`
+```python
+import numpy as np
+# old
+import numpy.typing as npt
+x = epics_signal_rw(npt.NDArray[np.str_], "PV")
+# new
+from collections.abc import Sequence
+x = epics_signal_rw(Sequence[str], "PV")
+```
+## `MockSignalBackend` requires a real backend
+```python
+# old
+fake_set_signal = SignalRW(MockSignalBackend(float))
+# new
+fake_set_signal = soft_signal_rw(float)
+await fake_set_signal.connect(mock=True)
+```
+## `get_mock_put` is no longer passed timeout as it is handled in `Signal`
+```python
+# old
+get_mock_put(driver.capture).assert_called_once_with(Writing.ON, wait=ANY, timeout=ANY)
+# new
+get_mock_put(driver.capture).assert_called_once_with(Writing.ON, wait=ANY)
+```
+## `super().__init__` required for `Device` subclasses
+```python
+# old
+class MyDevice(Device):
+    def __init__(self, name: str = ""):
+        self.signal, self.backend_put = soft_signal_r_and_setter(int)
+# new
+class MyDevice(Device):
+    def __init__(self, name: str = ""):
+        self.signal, self.backend_put = soft_signal_r_and_setter(int)
+        super().__init__(name=name)
+```
+## Arbitrary `BaseModel`s not supported, pending use cases for them
+The `Table` type has been suitable for everything we have seen so far, if you need an arbitrary `BaseModel` subclass then please make an issue
+## Child `Device`s set parent on attach, and can't be public children of more than one parent
+```python
+class SourceDevice(Device):
+    def __init__(self, name: str = ""):
+        self.signal = soft_signal_rw(int)
+        super().__init__(name=name)
+
+# old
+class ReferenceDevice(Device):
+    def __init__(self, signal: SignalRW[int], name: str = ""):
+        self.signal = signal
+        super().__init__(name=name)
+
+    def set(self, value) -> AsyncStatus:
+        return self.signal.set(value + 1)
+# new
+from ophyd_async.core import Reference
+
+class ReferenceDevice(Device):
+    def __init__(self, signal: SignalRW[int], name: str = ""):
+        self._signal_ref = Reference(signal)
+        super().__init__(name=name)
+
+    def set(self, value) -> AsyncStatus:
+        return self._signal_ref().set(value + 1)
+```

ophyd_async-0.8.0/docs/explanations/decisions/0009-procedural-vs-declarative-devices.md

@@ -0,0 +1,140 @@
+# 9. Procedural vs Declarative Devices
+
+Date: 01/10/24
+
+## Status
+
+Accepted
+
+## Context
+
+In [](./0006-procedural-device-definitions.rst) we decided we preferred the procedural approach to devices, because of the issue of applying structure like `DeviceVector`. Since then we have `FastCS` and `Tango` support which use a declarative approach. We need to decide whether we are happy with this situation, or whether we should go all in one way or the other. A suitable test Device would be:
+
+```python
+class EpicsProceduralDevice(StandardReadable):
+    def __init__(self, prefix: str, num_values: int, name="") -> None:
+        with self.add_children_as_readables():
+            self.value = DeviceVector(
+                {
+                    i: epics_signal_r(float, f"{prefix}Value{i}")
+                    for i in range(1, num_values + 1)
+                }
+            )
+        with self.add_children_as_readables(ConfigSignal):
+            self.mode = epics_signal_rw(EnergyMode, prefix + "Mode")
+        super().__init__(name=name)
+```
+
+and a Tango/FastCS procedural equivalent would be (if we add support to StandardReadable for Format.HINTED_SIGNAL and Format.CONFIG_SIGNAL annotations):
+```python
+class TangoDeclarativeDevice(StandardReadable, TangoDevice):
+    value: Annotated[DeviceVector[SignalR[float]], Format.HINTED_SIGNAL]
+    mode: Annotated[SignalRW[EnergyMode], Format.CONFIG_SIGNAL]
+```
+
+But we could specify the Tango one procedurally (with some slight ugliness around the DeviceVector):
+```python
+class TangoProceduralDevice(StandardReadable):
+    def __init__(self, prefix: str, name="") -> None:
+        with self.add_children_as_readables():
+            self.value = DeviceVector({0: tango_signal_r(float)})
+        with self.add_children_as_readables(ConfigSignal):
+            self.mode = tango_signal_rw(EnergyMode)
+        super().__init__(name=name, connector=TangoConnector(prefix))
+```
+
+or the EPICS one could be declarative:
+```python
+class EpicsDeclarativeDevice(StandardReadable, EpicsDevice):
+    value: Annotated[
+        DeviceVector[SignalR[float]], Format.HINTED_SIGNAL, EpicsSuffix("Value%d", "num_values")
+    ]
+    mode: Annotated[SignalRW[EnergyMode], Format.CONFIG_SIGNAL, EpicsSuffix("Mode")]
+```
+
+Which do we prefer?
+
+## Decision
+
+We decided that the declarative approach is to be preferred until we need to write formatted strings. At that point we should drop to an `__init__` method and a for loop. This is not a step towards only supporting the declarative approach and there are no plans to drop the procedural approach.
+
+The two approaches now look like:
+
+```python
+class Sensor(StandardReadable, EpicsDevice):
+    """A demo sensor that produces a scalar value based on X and Y Movers"""
+
+    value: A[SignalR[float], PvSuffix("Value"), Format.HINTED_SIGNAL]
+    mode: A[SignalRW[EnergyMode], PvSuffix("Mode"), Format.CONFIG_SIGNAL]
+
+
+class SensorGroup(StandardReadable):
+    def __init__(self, prefix: str, name: str = "", sensor_count: int = 3) -> None:
+        with self.add_children_as_readables():
+            self.sensors = DeviceVector(
+                {i: Sensor(f"{prefix}{i}:") for i in range(1, sensor_count + 1)}
+            )
+        super().__init__(name)
+```
+
+## Consequences
+
+We need to:
+- Add support for reading annotations and `PvSuffix` in an `ophyd_async.epics.core.EpicsDevice` baseclass
+- Do the `Format.HINTED_SIGNAL` and `Format.CONFIG_SIGNAL` flags in annotations for `StandardReadable`
+- Ensure we can always drop to `__init__`
+
+
+## pvi structure changes
+Structure read from `.value` now includes `DeviceVector` support. Requires at least PandABlocks-ioc 0.11.2
+
+## Epics `signal` module moves
+`ophyd_async.epics.signal` moves to `ophyd_async.epics.core` with a backwards compat module that emits deprecation warning.
+```python
+# old
+from ophyd_async.epics.signal import epics_signal_rw
+# new
+from ophyd_async.epics.core import epics_signal_rw
+```
+
+## `StandardReadable` wrappers change to `StandardReadableFormat`
+`StandardReadable` wrappers change to enum members of `StandardReadableFormat` (normally imported as `Format`)
+```python
+# old
+from ophyd_async.core import ConfigSignal, HintedSignal
+class MyDevice(StandardReadable):
+    def __init__(self):
+        self.add_readables([sig1], ConfigSignal)
+        self.add_readables([sig2], HintedSignal)
+        self.add_readables([sig3], HintedSignal.uncached)
+# new
+from ophyd_async.core import StandardReadableFormat as Format
+class MyDevice(StandardReadable):
+    def __init__(self):
+        self.add_readables([sig1], Format.CONFIG_SIGNAL)
+        self.add_readables([sig2], Format.HINTED_SIGNAL)
+        self.add_readables([sig3], Format.HINTED_UNCACHED_SIGNAL
+```
+
+## Declarative Devices are now available
+```python
+# old
+from ophyd_async.core import ConfigSignal, HintedSignal
+from ophyd_async.epics.signal import epics_signal_r, epics_signal_rw
+
+class Sensor(StandardReadable):
+    def __init__(self, prefix: str, name="") -> None:
+        with self.add_children_as_readables(HintedSignal):
+            self.value = epics_signal_r(float, prefix + "Value")
+        with self.add_children_as_readables(ConfigSignal):
+            self.mode = epics_signal_rw(EnergyMode, prefix + "Mode")
+        super().__init__(name=name)
+# new
+from typing import Annotated as A
+from ophyd_async.core import StandardReadableFormat as Format
+from ophyd_async.epics.core import EpicsDevice, PvSuffix, epics_signal_r, epics_signal_rw
+
+class Sensor(StandardReadable, EpicsDevice):
+    value: A[SignalR[float], PvSuffix("Value"), Format.HINTED_SIGNAL]
+    mode: A[SignalRW[EnergyMode], PvSuffix("Mode"), Format.CONFIG_SIGNAL]
+```

{ophyd_async-0.7.0a1 → ophyd_async-0.8.0}/docs/how-to/make-a-simple-device.rst

@@ -1,6 +1,6 @@
 .. note::
 
-   Ophyd async is included on a provisional basis until the v1.0 release and 
+   Ophyd async is included on a provisional basis until the v1.0 release and
    may change API on minor release numbers before then
 
 Make a Simple Device
@@ -31,7 +31,7 @@ its Python type, which could be:
 - A primitive (`str`, `int`, `float`)
 - An array (`numpy.typing.NDArray` ie. ``numpy.typing.NDArray[numpy.uint16]`` or ``Sequence[str]``)
 - An enum (`enum.Enum`) which **must** also extend `str`
-    - `str` and ``EnumClass(str, Enum)`` are the only valid ``datatype`` for an enumerated signal.
+    - `str` and ``EnumClass(StrictEnum)`` are the only valid ``datatype`` for an enumerated signal.
 
 The rest of the arguments are PV connection information, in this case the PV suffix.
 
@@ -45,7 +45,7 @@ Finally `super().__init__() <StandardReadable>` is called with:
   without renaming
 
 All signals passed into this init method will be monitored between ``stage()``
-and ``unstage()`` and their cached values returned on ``read()`` and 
+and ``unstage()`` and their cached values returned on ``read()`` and
 ``read_configuration()`` for perfomance.
 
 Movable
@@ -64,7 +64,7 @@ informing watchers of the progress. When it gets to the requested value it
 completes. This co-routine is wrapped in a timeout handler, and passed to an
 `AsyncStatus` which will start executing it as soon as the Run Engine adds a
 callback to it. The ``stop()`` method then pokes a PV if the move needs to be
-interrupted. 
+interrupted.
 
 Assembly
 --------

ophyd_async-0.8.0/docs/how-to/use_set_and_wait_for_other_value.md

@@ -0,0 +1,45 @@
+# `set_and_wait_for_other_value`
+
+The `set_and_wait_for_other_value` function (defined in `_signal.py`) is a utility designed to:
+
+1. **Set a signal**.
+2. **Wait for another signal to reach a specified value (`match_value`)**.
+
+The behavior of the function depends on the value of the `wait_for_set_completion` parameter:  
+
+- **If `wait_for_set_completion = True`:**  
+  The function returns at **1** (see diagram below), which occurs when the "set operation" is complete.  
+
+- **If `wait_for_set_completion = False`:**  
+  The function returns at **2**, which occurs when the `match_signal` reaches the `match_value`.
+
+In **AreaDetector**, the `wait_for_set_completion` parameter should generally be set to **`False`**, as the preferred behavior is to return when the `match_signal` achieves the `match_value`.
+
+---
+
+## Behavior Diagram:
+
+![wait_for_set_completion](../images/set_and_wait_for_other_value.svg)
+
+---
+
+## Example Usage
+
+```python
+# Example code snippet for using set_and_wait_for_other_value in an AreaDetector driver
+self._arm_status = set_and_wait_for_other_value(
+    self._drv.arm,
+    1,
+    self._drv.state,
+    "ready",
+    timeout=DEFAULT_TIMEOUT,
+    wait_for_set_completion=False,
+)
+```
+
+In this **AreaDetector driver**, the function ensures that the detector's `arm_status` reaches `"ready"` before capturing data. To achieve this:  
+
+- The detector is instructed to transition to the "armed" state by setting the driver's `arm` signal to `1`.  
+- The function waits until the driver's `state` signal equals `"ready"`.  
+
+This approach ensures that data capture is only initiated once the detector is fully prepared.