dls-dodal 1.69.0__tar.gz → 2.0.0__tar.gz

dls_dodal-2.0.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: dls-dodal
+Version: 2.0.0
+Summary: Ophyd devices and other utils that could be used across DLS beamlines
+Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>, Joseph Ware <joseph.ware@diamond.ac.uk>, Oliver Silvester <Oliver.Silvester@diamond.ac.uk>, Noemi Frisina <noemi.frisina@diamond.ac.uk>
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "{}"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright {yyyy} {name of copyright owner}
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: GitHub, https://github.com/DiamondLightSource/dodal
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: ophyd
+Requires-Dist: ophyd-async[ca,pva]>=v0.14.0
+Requires-Dist: bluesky>=1.14.5
+Requires-Dist: pyepics
+Requires-Dist: pillow
+Requires-Dist: zocalo>=1.0.0
+Requires-Dist: requests
+Requires-Dist: graypy
+Requires-Dist: pydantic>=2.0
+Requires-Dist: opencv-python-headless
+Requires-Dist: numpy
+Requires-Dist: aiofiles
+Requires-Dist: aiohttp
+Requires-Dist: redis
+Requires-Dist: scanspec>=0.7.3
+Requires-Dist: pyzmq==26.3.0
+Requires-Dist: deepdiff
+Requires-Dist: daq-config-server>=v1.0.0
+Dynamic: license-file
+
+[![CI](https://github.com/DiamondLightSource/dodal/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/dodal/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/DiamondLightSource/dodal/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/dodal)
+[![PyPI](https://img.shields.io/pypi/v/dls-dodal.svg)](https://pypi.org/project/dls-dodal)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+# dodal
+
+Ophyd devices and other utils that could be used across DLS beamlines
+
+Source          | <https://github.com/DiamondLightSource/dodal>
+:---:           | :---:
+PyPI            | `pip install dls-dodal`
+Documentation   | <https://diamondlightsource.github.io/dodal>
+Releases        | <https://github.com/DiamondLightSource/dodal/releases>
+
+Testing Connectivity
+--------------------
+
+You can test your connection to a beamline if it's PVs are visible to your machine with:
+
+
+```
+    # On any workstation:
+    dodal connect <BEAMLINE>
+
+    # On a beamline workstation, this should suffice:
+    dodal connect ${BEAMLINE}
+```
+
+
+
+For more options, including a list of valid beamlines, type
+
+```
+    dodal connect --help
+```
+
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+See https://diamondlightsource.github.io/dodal for more detailed documentation.

dls_dodal-2.0.0/docs/how-to/build-docs.md

@@ -0,0 +1,47 @@
+# Build the docs using sphinx
+
+You can build the [sphinx](https://www.sphinx-doc.org) based docs from the project directory by running:
+
+```
+$ tox -e docs
+```
+
+This will build the static docs on the `docs` directory, which includes API docs that pull in docstrings from the code.
+
+:::{seealso}
+[](documentation_standards)
+:::
+
+The docs will be built into the `build/html` directory, and can be opened locally with a web browse:
+
+```
+$ firefox build/html/index.html
+```
+
+## Autobuild
+
+You can also run an autobuild process, which will watch your `docs` directory for changes and rebuild whenever it sees changes, reloading any browsers watching the pages:
+
+```
+$ tox -e docs autobuild
+```
+
+You can view the pages at localhost:
+
+```
+$ firefox http://localhost:8000
+```
+
+If you are making changes to source code too, you can tell it to watch changes in this directory too:
+
+```
+$ tox -e docs autobuild -- --watch src
+```
+
+## Common issues
+
+### Building docs fails due to cached *rst files
+
+If the module stucture changes from "x.y" to "x.z.y" one could get "module x.z.y not found" error trying to build the docs locally.
+
+The solution is to clear "/workspaces/dodal/docs/reference/generated" folder.

dls_dodal-2.0.0/docs/how-to/convert-beamline-to-device-manager.md

@@ -0,0 +1,131 @@
+# Converting an existing beamline to use a DeviceManager
+
+This guide assumes you have a beamline module file (eg `dodal/beamlines/ixx.py`)
+with a number of functions defined and decorated with `@device_factory`
+(`dodal.common.beamlines.beamline_utils`).
+
+## Create a DeviceManager
+
+By convention this should be named `devices` but can be custom if there is good
+reason.
+
+```python
+from dodal.device_manager import DeviceManager
+
+devices = DeviceManager()
+```
+
+This device manager keeps track of all device factories for a beamline making it
+easier to determine which are present and the order in which to build them to
+ensure dependencies are available before their dependents.
+
+## Replace the `@device_factory` decorators
+
+Each factory function should be decorated with `@devices.factory` (where
+`devices` is the name of the `DeviceManager` created above) instead of
+`@device_factory`. If no arguments are required, the parentheses can be omitted,
+eg
+
+```python
+@devices.factory()
+def device() -> Device:
+    ...
+```
+
+is equivalent to
+
+```python
+@devices.factory
+def device() -> Device:
+    ...
+```
+
+If arguments (eg `skip` or `mock`) were passed to `device_factory`, these can
+continue to be passed to `devices.factory` in the same way.
+
+## Replace `get_path_provider` with fixture
+
+Previously, the path_provider used by detectors was set and accessed as a global.
+
+Where device factory functions used this global (via `get_path_provider`) they
+should be updated to accept `path_provider` as a parameter. This can then be
+passed in when creating the devices.
+
+```python
+# Previous approach using `get_path_provider`...
+@device_factory()
+def panda() -> HDFPanda:
+    return HDFPanda(
+        f"{PREFIX.beamline_prefix}-EA-PANDA-01:",
+        path_provider=get_path_provider(),
+    )
+
+# ... should be replaced with
+@devices.factory()
+def panda(path_provider: PathProvider) -> HDFPanda:
+    return HDFPanda(
+        f"{PREFIX.beamline_prefix}-EA-PANDA-01:",
+        path_provider=path_provider,
+    )
+```
+
+Where a beamline was setting the path provider via `set_path_provider`, a
+fixture should be created which will provide a fallback instance to be used if
+one is not passed in.
+
+
+```python
+# The previous approach...
+set_path_provider(PathProviderImplementation(...))
+
+# ...should be removed and replaced with
+@devices.fixture
+def path_provider() -> PathProvider:
+    return PathProviderImplementation(...)
+```
+
+## Replace factory calls with parameters
+
+Where one function previously called another to access another device, this should
+be replaced with a parameter of the same name. This is to prevent multiple
+instances of devices being created as functions no longer cache the devices they
+create.
+
+```python
+# Previous example using a device factory function
+@device_factory()
+def beamsize() -> Beamsize:
+    return Beamsize(aperture_scatterguard())
+
+# New version with `aperture_scatterguard` passed as a parameter
+@devices.factory
+def beamsize(aperture_scatterguard: ApertureScatterguard) -> Beamsize:
+    return Beamsize(aperture_scatterguard)
+```
+
+## Merge multiple device managers
+
+If devices need to be shared between multiple beamlines, eg branch beamlines
+sharing optics components, an external device manager can be imported and
+merged into another.
+
+```python
+# in ixx_shared.py
+devices = DeviceManager()
+
+@devices.factory
+def common_device() -> CommonDevice:
+   ...
+
+# in ixx.py
+from ixx_shared import devices as shared_devices
+
+devices = DeviceManager()
+devices.include(shared_devices)
+
+# devices defined in the common beamline module can then be used as dependencies
+# in the beamline module
+@devices.factory
+def beamline_device(common_device: CommonDevice) -> BeamlineDevice:
+    ...
+```

dls_dodal-2.0.0/docs/how-to/create-beamline.md

@@ -0,0 +1,129 @@
+# Creating a new beamline
+
+A beamline is a collection of devices that can be used together to run experiments, they may be read-only or capable of being set.
+They include motors in the experiment hutch, optical components in the optics hutch, the synchrotron "machine" and more.
+
+## Beamline Modules
+
+Each beamline should have its own file in the ``dodal.beamlines`` folder, in which the particular devices for the
+beamline are instantiated. The file should be named after the colloquial name for the beamline. For example:
+
+* ``i03.py``
+* ``i20_1.py``
+* ``vmxi.py``
+
+Beamline modules (in ``dodal.beamlines``) are code-as-configuration. They define the set of devices and common device
+settings needed for a particular beamline or group of similar beamlines (e.g. a beamline and its digital twin). Some
+of our tooling depends on the convention of *only* beamline modules going in this package. Common utilities should
+go somewhere else e.g. ``dodal.utils`` or ``dodal.beamlines.common``.
+
+The following example creates a fictitious beamline ``w41``, with a simulated twin ``s41``.
+``w41`` needs to monitor the status of the Synchrotron and has an AdAravisDetector.
+``s41`` has a simulated clone of the AdAravisDetector, but not of the Synchrotron machine.
+
+```python
+
+    from functools import cache
+    from pathlib import Path
+    from ophyd_async.core import PathProvider
+    from ophyd_async.epics.adaravis import AravisDetector
+
+    from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
+    from dodal.common.beamlines.device_helpers import CAM_SUFFIX, HDF5_SUFFIX
+    from dodal.common.visit import RemoteDirectoryServiceClient, StaticVisitPathProvider
+    from dodal.device_manager import DeviceManager
+    from dodal.devices.synchrotron import Synchrotron
+    from dodal.log import set_beamline as set_log_beamline
+    from dodal.utils import BeamlinePrefix, get_beamline_name
+
+    BL = get_beamline_name("s41")  # Default used when not on a live beamline
+    PREFIX = BeamlinePrefix(BL)
+    set_log_beamline(BL)  # Configure logging and util functions
+    set_utils_beamline(BL)
+
+    devices = DeviceManager()
+    
+    @devices.fixture
+    @cache
+    def path_provider() -> PathProvider:
+        # Currently we must hard-code the visit, determining the visit is WIP.
+        return StaticVisitPathProvider(
+            BL,
+            # Root directory for all detectors
+            Path("/dls/w41/data/YYYY/cm12345-1"),
+            # Uses an existing GDA server to ensure filename uniqueness
+            client=RemoteDirectoryServiceClient("http://s41-control:8088/api"),
+            # Else if no GDA server use a LocalDirectoryServiceClient(),
+        )
+
+
+    """
+    Define device factory functions below this point.
+    A device factory function is any function that has a return type which conforms
+    to one or more Bluesky Protocols.
+    """
+
+    """
+    This decorator gives extra desirable behaviour to this factory function:
+    - it may be instantiated automatically, selectively on live beamline
+    - it automatically names the device if no name is explicitly set
+    - it may be skipped when make_all_devices is called on this module
+    - it must be explicitly connected (which may be automated by tools)
+        - when connected it may connect to a simulated backend
+        - it may be connected concurrently (when automated by tools)
+    """
+    @devices.factory(skip = BL == "s41")
+    def synchrotron() -> Synchrotron:
+        return Synchrotron()
+
+
+    @devices.factory()
+    def d11(path_provider: PathProvider) -> AravisDetector:
+        return AravisDetector(
+            f"{PREFIX.beamline_prefix}-DI-DCAM-01:",
+            path_provider=path_provider,
+            drv_suffix=CAM_SUFFIX,
+            fileio_suffix=HDF5_SUFFIX,
+        )
+```
+
+Some beamlines have multiple endstations and shared optics. To reduce duplicate configuration, the `DeviceManager` allows us to include devices from another instance of `DeviceManager`.
+
+An example is shown below for a shared beamline setup:
+
+```python
+from dodal.device_manager import DeviceManager
+from dodal.devices.pgm import PlaneGratingMonochromator
+
+...
+
+devices = DeviceManager()
+
+"""Device that is shared between multiple endstations, i05 and i05-1."""
+@devices.factory()
+def pgm() -> PlaneGratingMonochromator:
+    return PlaneGratingMonochromator(
+        prefix=f"{PREFIX.beamline_prefix}-OP-PGM-01:",
+        grating=Grating,
+    )
+```
+
+Then for i05, we include the i05_shared devices so we have access to the shared devices.
+
+```python
+from dodal.beamlines.i05_shared import devices as i05_shared_devices
+from dodal.device_manager import DeviceManager
+from dodal.devices.temperture_controller import Lakeshore336
+
+...
+
+"""Include all the i05 shared beamline devices which should be avaliable for every end station.
+In this example, the pgm device will be included in this beamline."""
+devices = DeviceManager()
+devices.include(i05_shared_devices)
+
+"""Beamline specific device for i05 only."""
+@devices.factory()
+def sample_temperature_controller() -> Lakeshore336:
+    return Lakeshore336(prefix=f"{PREFIX.beamline_prefix}-EA-TCTRL-02:")
+```

dls_dodal-2.0.0/docs/how-to/create-device.md

@@ -0,0 +1,74 @@
+Creating a new device
+---------------------
+
+Devices in dodal use the ophyd-async framework for hardware abstraction at Diamond Light Source. Before starting, [review where your code should live](../reference/device-standards.rst#where_to_put_devices) to avoid duplication and ensure maintainability.
+
+Reusing an existing class
+=========================
+
+Before creating a new device, always check if a suitable class already exists in dodal or ophyd-async. This helps avoid duplication, ensures maintainability, and leverages tested code.
+
+- **Motors:** Use [Motor](https://github.com/bluesky/ophyd-async/blob/main/src/ophyd_async/epics/motor.py) for EPICS motor records.
+- **Storage ring signals:** Use [Synchrotron](https://github.com/DiamondLightSource/dodal/blob/main/src/dodal/devices/synchrotron.py).
+- **AreaDetectors:** Use [StandardDetector](https://github.com/bluesky/ophyd-async/tree/main/src/ophyd_async/epics/adcore) or [adcore](https://github.com/bluesky/ophyd-async/tree/main/src/ophyd_async/epics/adcore).
+
+If a compatible device class exists:
+- Use it and add it to the [beamline](./create-beamline.rst) to avoid re-implementation and share improvements.
+- You can use ophyd-async's [DeviceVector](https://blueskyproject.io/ophyd-async/main/explanations/decisions/0006-procedural-device-definitions.html) to handle a collection of identical devices.   
+- If a device class only differs by PV address, request an alias in the EPICS IOC support module with the relevant controls support team.  
+- If that's not possible (e.g. proprietary support), add configurability to the dodal device class, ensuring defaults match existing patterns and that `dodal connect` still works for current devices.
+- Avoid dynamic attribute assignment (e.g. dicts of motors) as it hinders type checking and plan writing.  
+- Use static attributes and type hints for better IDE support and maintainability.
+
+Many device classes in `dodal.devices.motors` represent physical relationships between motors, such as `Stage` and `XYStage`.  
+
+For example, only use `XYStage` for two perpendicular motors (e.g. X and Y axes on a sample table):
+- Do not use `XYStage` for unrelated motors or for motors that move in the same axis (e.g. coarse and fine adjustment).
+- Only a device that represents a group of motors with a physical relationship, should be defined in `motor`.
+- If your class define an `XYStage` but you need extra signals or behaviour, extend the `XYStage` class outside the `motor` module.
+
+**Only if no suitable class exists**, create a new device that connects to the required signals. During review, refactor to align with existing devices if needed, using inheritance or composition to deduplicate code.
+
+Devices that are generic and reusable across multiple beamlines should be defined under `dodal.devices`. For example, `dodal.devices.motors.XYStage` is generic enough that most beamlines can use it directly or inherit from it.
+
+Devices that are specific to a single beamline should be placed under `dodal.devices.beamlines.iXX`. For instance, a detector that is only used on that beamline and is too specialized to be reused elsewhere belongs here.
+
+If a beamline has multiple endstations and a device is shared between them, it should be defined under `dodal.devices.beamlines.iXX_shared`.
+
+Writing a device class
+======================
+
+To develop a new device, get an initial, working version of your code into the main branch as early as possible. Test it at the beamline, then continuously make and merge small changes into main. This approach prevents pull requests from becoming long-standing issues.
+
+- **Follow the [ophyd-async device implementation guide](https://blueskyproject.io/ophyd-async/main/tutorials/implementing-devices.html)** to structure your device code.
+- **Choose the right base class** by consulting the [base class guide](https://blueskyproject.io/ophyd-async/main/how-to/choose-right-baseclass.html), If your device needs to move, you'll need to extend the Movable protocol. For detailed guidance on when and how to do this, refer to the [movable device guide](https://blueskyproject.io/ophyd-async/main/explanations/when-to-extend-movable.html). 
+- **Add static metadata (if any) to the device class** using a [soft signal](https://blueskyproject.io/ophyd-async/main/_api/ophyd_async/ophyd_async.core.html#ophyd_async.core.soft_signal_rw) or existing device epics record. For example this could be a manufacturer or brand name of the device. Another example is crystal metadata in [i22 DCM](https://diamondlightsource.github.io/dodal/main/reference/generated/dodal.devices.beamlines.i22.dcm.DCM.html#dodal.devices.beamlines.i22.dcm.DCM) In some cases it might be beneficial to ask controls team to create an additional epics field containing metadata for such device. 
+- **Write thorough unit tests** for all expected use cases. Reference the [ophyd-async device test guide](https://blueskyproject.io/ophyd-async/main/tutorials/implementing-devices.html) for best practices.
+- **Validate your device on the beamline** and keep notes of any issues for later fixes.
+- **Make use of type annotations** so that pyright will validate that you are passing around values that ophyd-async will accept.
+- Use `dodal connect <beamline>` to check device connectivity and `cainfo <PV address>` to confirm PVs and datatypes. You can check a PV's datatype by using the `cainfo <PV address>` command. If the datatype is an enum, `caget -d 31 <PV address>` will also display the available enums that the PV takes. Common enums are defined in `ophyd-async.core` for devices to use, but you can define custom ones when suitable (inheriting from `ophyd_async.core` `StrictEnum`, `SupersetEnum` or `SubsetEnum`). The values should be capitalised e.g `ON = "On"`. If the PV expects upper case for the enum (e.g `ON = "ON"`), please speak to the relevant controls engineer(s) to get this changed if possible. For more infomation, please visit [here](https://blueskyproject.io/ophyd-async/main/explanations/decisions/0008-signal-types.html).
+
+Device best practices for Bluesky plans
+=======================================
+
+- Interact with devices in plans only through the Bluesky [messages protocol](https://blueskyproject.io/bluesky/main/msg.html), such as `yield from bps.abs_set(...)` or `yield Msg("set", ...)`.
+- Avoid calling device methods directly inside plans (e.g. `device.do_thing()`), as this breaks the abstraction and can lead to unpredictable behaviour.
+
+Example of what **not** to do:
+```python
+class MyDevice(Device):
+    def do_thing(...):
+        ...
+
+def my_plan():
+    yield from bps.set(...)
+    device.do_thing()  # This is bad: do not call device methods directly in plans
+```
+
+**Tip:**
+
+- If you are unsure how to represent a PV as a Signal, seek feedback early (for example, by opening a draft PR).
+- Whenever possible, merge with existing devices—comprehensive tests help ensure changes do not break current functionality.
+- Document any device-specific quirks or limitations for future maintainers.
+
+For further guidance, see the [ophyd-async documentation](https://blueskyproject.io/ophyd-async/main/how-to/choose-interfaces-for-devices.html).