dls-dodal 1.55.1__tar.gz → 1.57.0__tar.gz

{dls_dodal-1.55.1 → dls_dodal-1.57.0}/.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       matrix:
         runs-on: ["ubuntu-latest"] # can add windows-latest, macos-latest
-        python-version: ["3.11", "3.12"]
+        python-version: ["3.11", "3.12", "3.13"]
         include:
           # Include one that runs in the dev environment
           - runs-on: "ubuntu-latest"

{dls_dodal-1.55.1 → dls_dodal-1.57.0}/.pre-commit-config.yaml

@@ -31,7 +31,7 @@ repos:
         types: [python]
         require_serial: false
 
-  - repo: https://github.com/thoughtworks/talisman
-    rev: v1.37.0
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.28.0
     hooks:
-      - id: talisman-commit
+      - id: gitleaks

{dls_dodal-1.55.1 → dls_dodal-1.57.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dls-dodal
-Version: 1.55.1
+Version: 1.57.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
@@ -215,8 +215,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: ophyd
-Requires-Dist: ophyd-async[ca,pva]>=0.13.0
-Requires-Dist: bluesky
+Requires-Dist: ophyd-async[ca,pva]>=0.13.2
+Requires-Dist: bluesky==1.14.2
 Requires-Dist: pyepics
 Requires-Dist: dataclasses-json
 Requires-Dist: pillow

{dls_dodal-1.55.1 → dls_dodal-1.57.0}/conftest.py

@@ -14,6 +14,12 @@ from ophyd_async.core import (
     PathInfo,
     PathProvider,
 )
+from tests.devices.i10.test_data import LOOKUP_TABLE_PATH
+from tests.devices.test_daq_configuration import MOCK_DAQ_CONFIG_PATH
+from tests.test_data import (
+    TEST_DISPLAY_CONFIG,
+    TEST_OAV_ZOOM_LEVELS_XML,
+)
 
 from dodal.common.beamlines import beamline_utils
 from dodal.common.visit import (
@@ -23,12 +29,11 @@ from dodal.common.visit import (
 )
 from dodal.log import LOGGER, GELFTCPHandler, set_up_all_logging_handlers
 
-MOCK_DAQ_CONFIG_PATH = "tests/devices/unit_tests/test_daq_configuration"
 mock_paths = [
     ("DAQ_CONFIGURATION_PATH", MOCK_DAQ_CONFIG_PATH),
-    ("ZOOM_PARAMS_FILE", "tests/devices/unit_tests/test_jCameraManZoomLevels.xml"),
-    ("DISPLAY_CONFIG", "tests/devices/unit_tests/test_display.configuration"),
-    ("LOOK_UPTABLE_DIR", "tests/devices/i10/lookupTables/"),
+    ("ZOOM_PARAMS_FILE", TEST_OAV_ZOOM_LEVELS_XML),
+    ("DISPLAY_CONFIG", TEST_DISPLAY_CONFIG),
+    ("LOOK_UPTABLE_DIR", LOOKUP_TABLE_PATH),
 ]
 mock_attributes_table = {
     "i03": mock_paths,
@@ -119,8 +124,8 @@ def failed_status(failure: Exception) -> Status:
     return status
 
 
-@pytest.fixture
-async def RE():
+@pytest.fixture(scope="session", autouse=True)
+async def _ensure_running_bluesky_event_loop():
     RE = RunEngine()
     # make sure the event loop is thoroughly up and running before we try to create
     # any ophyd_async devices which might need it
@@ -129,4 +134,8 @@ async def RE():
         await asyncio.sleep(0)
         if time.monotonic() > timeout:
             raise TimeoutError("This really shouldn't happen but just in case...")
-    yield RE
+
+
+@pytest.fixture()
+async def RE():
+    yield RunEngine()

dls_dodal-1.57.0/docs/explanations/decisions/0006-devices-shared-between-endstations.md

@@ -0,0 +1,27 @@
+# 6. Handle devices shared between multiple endstations
+
+Date: 2025-08-27
+
+## Status
+
+Proposed
+
+## Context
+
+Some beamlines have multiple endstations with shared hardware in the optics or experiment hutch, and could potentially be trying to control it at the same time. Any device in the common hutch should only be fully controlled by one endstation at a time - the one that is taking data - but still be readable from the other endstations.
+
+## Decision
+
+The current solution is to have a separate blueapi instance for the shared hutch in order to be able to control the access to all the devices defined there.
+For all hardware in the shared optics hutch, the architecture should follow this structure:
+
+- There is a base device in dodal that sends a REST call to the shared blueapi with plan and devices names, as well as the name of the endstation performing the call.
+- There are read-only versions of the shared devices in the endstation blueapi which inherit from the base device above and set up the request parameters.
+- The real settable devices are only defined in the shared blueapi and should never be called directly from a plan.
+- The shared blueapi instance also has an ``AccessControl`` device that reads the endstation in use for beamtime from a PV.
+- Every plan should then be wrapped in a decorator that reads the ``AccessControl`` device, check which endstation is making the request and only allows the plan to run if the two values match.
+
+
+:::{seealso}
+[Optics hutch implementation on I19](https://diamondlightsource.github.io/i19-bluesky/main/explanations/decisions/0004-optics-blueapi-architecture.html) for an example.
+:::

{dls_dodal-1.55.1 → dls_dodal-1.57.0}/docs/how-to/coverage.md

@@ -3,6 +3,10 @@
 
 Code coverage is reported to the command line and to a `cov.xml` file by the command `tox -e tests`. The file is uploaded to the Codecov service in CI.
 
+If you are using VSCode IDE, you can also check code coverage by right-clicking on the test icon and selecting `Run with coverage`. This will re-run the test and highlight line numbers in your file:
+- Green = covered by tests
+- Red = not covered (and ideally should be tested)
+
 ## Adding a Codecov Token
 
 If the repo is not hosted in DiamondLightSource, then you need to visit `https://app.codecov.io/account/gh/<org_name>/org-upload-token` to generate a token for your org, and store it as a secret named `CODECOV_TOKEN` in `https://github.com/organizations/<org_name>/settings/secrets/actions`

dls_dodal-1.55.1/docs/how-to/create-beamline.rst → dls_dodal-1.57.0/docs/how-to/create-beamline.md

@@ -1,13 +1,11 @@
-Creating a new beamline
-=======================
+# 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
-----------------
+## Beamline Modules
 
-Each beamline should have its own file in the ``dodal.beamlines`` folder, in which the particular devices for the 
+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``
@@ -16,14 +14,14 @@ beamline are instantiated. The file should be named after the colloquial name fo
 
 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 
+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.
 
-.. code-block:: python
+```python
 
     from ophyd_async.epics.adaravis import AravisDetector
 
@@ -85,3 +83,4 @@ The following example creates a fictitious beamline ``w41``, with a simulated tw
             drv_suffix=CAM_SUFFIX,
             fileio_suffix=HDF5_SUFFIX,
         )
+```

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

@@ -0,0 +1,66 @@
+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.  
+
+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). 
+- **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).

dls_dodal-1.57.0/docs/how-to/move-code.md

@@ -0,0 +1,94 @@
+
+# Moving code from another repo
+
+In the process of writing code in other DLS repos you may come to realise that it makes more sense to be in ``dodal``. It is a good idea to keep the history for this code, you can do this by doing the following (we will be using moving devices from https://github.com/DiamondLightSource/hyperion as an example):
+
+* Clone the codebase you are copying from:
+
+```bash
+    git clone git@github.com:DiamondLightSource/hyperion.git clone_for_history
+    cd clone_for_history/
+```
+
+* Remove the remote to avoid any mistaken pushes:
+
+```bash
+    git remote rm origin
+```
+
+* Filter out only the directory/file you want to move:
+
+```bash
+    pip install git-filter-repo
+    git-filter-repo --path file/to/move --path /other/file/to/move -f
+```
+
+* Clean everything up:
+
+```bash
+    git reset --hard
+    git gc --aggressive
+    git prune
+    git clean -fd
+```
+
+* Add a note to every commit message to mention it's been moved::
+
+```bash
+    git filter-branch --msg-filter 'sed "$ a \
+    NOTE: Commit originally came from https://github.com/DiamondLightSource/hyperion"' -f -- --all
+```
+
+* If you have been using Github [issue references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#issues-and-pull-requests) in the old repository modify these to point to be more explicit (Note that this assumes the old repo uses ``#123`` notation and only ever references issues from it's own repo)::
+
+```bash
+    git filter-branch -f --msg-filter 'sed "s|#[0-9]\+|DiamondLightSource/hyperion&|g"' -- --all
+```
+
+* Prepare the code to be in the correct structure for dodal::
+
+```bash
+    mkdir -p src/dodal/devices
+    mv path/to/device src/dodal/devices/
+```
+
+* At this point it's a good idea to check the log ``git log`` and the general directory structure to ensure it looks mostly correct
+
+* Add and commit this (locally)::
+
+```bash
+    git add .
+    git commit -m "Prepare for import into dodal"
+```
+
+* In a different folder clone ``dodal``, remove the origin (for now) to be safe and create a branch::
+
+```bash
+    git clone git@github.com:DiamondLightSource/dodal.git
+    cd dodal
+    git remote rm origin
+    git checkout -b add_code_from_hyperion
+```
+
+* Add the source repo as a remote for ``dodal``::
+
+```bash
+    git remote add source /path/to/source/old_repo/.git
+```
+
+* Pull from the source repo::
+
+```bash
+    git pull --no-rebase source main --allow-unrelated-histories
+```
+
+* This is another point where it's a good idea to check the log ``git log`` and the general directory structure to ensure it looks mostly correct
+
+* Remove the source remote and re-add origin::
+
+```bash
+    git remote rm source
+    git remote add origin git@github.com:DiamondLightSource/dodal.git
+```
+
+* Tidy up the code so that it fits into the ``dodal`` repo e.g. in the Hyperion case we had to change the tests to import from ``hyperion`` to import from ``dodal`` and add some more dependencies.

dls_dodal-1.57.0/docs/how-to/run-tests.md

@@ -0,0 +1,61 @@
+(using-pytest)=
+
+# Running tests
+
+Tests can be ran locally via command line or VSCode IDE.
+
+## With VSCode
+
+When using the VSCode IDE, it should automatically detect all of your tests and display one of the following icons next to each of them:
+- Grey circle (not run yet)
+- Green circle with a tick (test passed)
+- Red circle with a cross (test failed)
+
+You can also check code coverage by right-clicking on the test icon and selecting `Run with coverage`. This will re-run the test and highlight line numbers in your file:
+- Green = covered by tests
+- Red = not covered (and ideally should be tested)
+
+To view all tests inside dodal, use the `Test Explorer` panel (flask icon) in VSCode. It displays all of your tests in a hierarchy, which you can run individually or in groups. It also shows the pass/fail icons mentioned above. Clicking on an item will run all tests beneath it in the hierarchy.
+
+If you find that your tests are being skipped or not recognised by `pytest`, check for any syntax errors as this will block the tests being found. You can also check to see if there is an error output at the very bottom of the `Test Explorer` panel. This is usually caused by invalid syntax in your test file, or by circular dependencies in the code you are testing.
+
+## Command line
+
+### Unit tests
+
+`pytest` will find functions in the project that [look like tests][look like tests], and run them to check for errors. 
+
+When you have some fully working tests then you can run it with coverage:
+
+```
+$ tox -e tests
+```
+
+It will also report coverage to the command line and to `cov.xml`.
+
+[look like tests]: https://docs.pytest.org/explanation/goodpractices.html#test-discovery
+[pytest]: https://pytest.org/
+
+### System tests locally
+
+The system tests require the ``example-services`` project:
+
+```commandline
+git clone git@github.com:epics-containers/example-services.git
+```
+
+Then you need to launch some of the example ioc containers. Please note, this requires docker-compose not 
+podman-compose:
+
+```commandline
+module load docker-compose
+cd example-services
+. ./environment.sh
+podman compose up -d bl01t-di-cam-01 bl01t-mo-sim-01 ca-gateway
+```
+
+Once this is done, then the system tests can be run:
+
+```commandline
+tox -e system-report
+```

dls_dodal-1.57.0/docs/how-to/write-tests.md

@@ -0,0 +1,122 @@
+# Writing Tests in This Python Project
+
+Testing is essential to maintain the integrity and reliability of the codebase. Follow the guidelines below to write tests for this project effectively.
+
+## Test Organization
+
+- **Unit Tests**: Place unit tests for individual components in the `tests` directory, but take care to mirror the file structure of the `src` folder with the corresponding code files. Use the `test_*.py` naming convention for test files.
+- **System Tests**: Tests that interact with DLS infrastructure, network, and filesystem should be placed in the top-level `systems_test` folder. This separation ensures that these tests are easily identifiable and can be run independently from unit tests.
+
+Useful functions for testing that can be reused across multiple tests for common devices and for external plan repositories belong in the `dodal/testing` directory. For example, when mocking a `Motor` device, all of the signals will default to zero, which will cause errors when trying to move. The `patch_motor` and `patch_all_motors` functions, found in `dodal.testing`, will populate the mocked motor with useful default values for the signals so that it can still be used in tests.
+
+
+## Writing a test for a device
+We aim for high test coverage in dodal with small, modular test functions. To achieve this, we need to test the relevant methods by writing tests for the class/method we are creating or changing, checking for the expected behaviour. We shouldn't need to write tests for parent classes unless we alter their behaviour.
+
+Below, a `StandardReadable` example device is defined which also implements the `Stageable` protocol.
+
+```Python
+from bluesky import RunEngine
+from bluesky.protocols import Stageable
+from ophyd_async.core import AsyncStatus, OnOff, StandardReadable
+from ophyd_async.epics.core import epics_signal_rw
+
+
+class MyDevice(StandardReadable, Stageable):
+    """
+    Example device demostrating how to test stage, unstage and read methods.
+    """
+
+    def __init__(self, prefix: str, name: str = "") -> None:
+        """
+        Constructor for setting up instance of device.
+
+        Parameters:
+            prefix: Base PV used for connecting signals.
+            name: Name of the device.
+        """
+        with self.add_children_as_readables():
+            self.signal_a = epics_signal_rw(float, prefix + "A")
+            self.signal_b = epics_signal_rw(OnOff, prefix + "B")
+
+        super().__init__(name)
+
+    @AsyncStatus.wrap
+    async def stage(self):
+        """
+        Setup device by moving signal_a to ON.
+        """
+        await asyncio.gather(super().stage(), self.signal_b.set(OnOff.ON))
+
+    @AsyncStatus.wrap
+    async def unstage(self):
+        """
+        Once device is finished, set signal_b back to OFF.
+        """
+        await asyncio.gather(super().stage(), self.signal_b.set(OnOff.OFF))
+```
+
+In this example, we need to test the `stage` and `unstage` methods. For more complex devices, it is also a good idea to test the `read` method to confirm that we get the expected read signals back when this method is called.
+
+We use [pytest](https://docs.pytest.org/en/stable/contents.html) for writing tests in dodal. A core part of this library is the use of fixtures. A fixture is a function decorated with `@pytest.fixture` that provides setup/teardown or reusable test data for your tests. It is defined once and can be reused across multiple tests. Fixtures are mainly used to define devices and then inject them into each test.
+
+To help set up a device, they are created with the `init_devices(mock=True)` function from `ophyd_async.core`, which automatically initialises the device in mock mode. The `RunEngine` fixture is passed when creating a device to ensure there is an event loop available when connecting signals. This fixture is defined in `dodal/tests/conftest.py`, which is a special file recognised by `pytest`. It defines fixtures that are automatically available to any test in the same directory (and its subdirectories) without needing to import them. This is useful for defining common setup code once without duplicating it across test files.
+
+In order for `pytest` to detect something as a test, a function should begin with `test_*`. The test function should be self-descriptive about what it is testing, and it is acceptable (even encouraged) to have longer names for test functions for clarity.
+
+```Python
+import asyncio
+
+import pytest
+from bluesky import RunEngine
+from bluesky import plan_stubs as bps
+from ophyd_async.core import OnOff, init_devices
+from ophyd_async.testing import assert_reading, get_mock_put, partial_reading
+from dodal.device.my_device import  MyDevice
+
+
+# RunEngine is needed to make sure there is an event loop when creating device.
+@pytest.fixture
+async def sim_my_device(RE: RunEngine) -> MyDevice:
+    async with init_devices(mock=True):
+        sim_my_device = MyDevice("TEST:")
+    return sim_my_device
+
+
+def test_my_device_stage(sim_my_device: MyDevice, RE: RunEngine) -> None:
+    RE(bps.stage(sim_my_device, wait=True), wait=True)
+    get_mock_put(sim_my_device.signal_b).assert_called_once_with(OnOff.ON, wait=True)
+
+
+def test_my_device_unstage(sim_my_device: MyDevice, RE: RunEngine) -> None:
+    RE(bps.unstage(sim_my_device, wait=True), wait=True)
+    get_mock_put(sim_my_device.signal_b).assert_called_once_with(OnOff.OFF, wait=True)
+
+```
+
+You should test the output of a device when the device has many signals read and you want to ensure the correct ones are read at the correct times, or when the `read` method of it or one of its signals (e.g. a DerivedSignal) requires testing. Functions are defined in `ophyd-async` to aid with this. `assert_reading` allows us to compare the readings generated from a `Readable` device to the expected results.
+
+```Python
+async def test_my_device_read(sim_my_device: MyDevice, RE: RunEngine) -> None:
+    prefix = sim_my_device.name
+    await assert_reading(
+        sim_my_device,
+        {
+            f"{prefix}-signal_a": partial_reading(OnOff.ON),
+            f"{prefix}-signal_b": partial_reading(0),
+        },
+    )
+```
+
+`partial_reading` wraps the value given in a mapping like `{"value": ANY}`, so we are actually checking that the reading matches the expected structure.
+
+```Python
+    prefix = sim_my_device.name
+    await assert_reading(
+        sim_my_device,
+        {
+            f"{prefix}-signal_a" : {"value": OnOff.ON},
+            f"{prefix}-signal_b" : {"value": 0},
+        }
+    )
+```

dls_dodal-1.55.1/docs/how-to/zocalo.rst → dls_dodal-1.57.0/docs/how-to/zocalo.md

@@ -1,32 +1,27 @@
-Zocalo Interaction
-==================
+# Zocalo Interaction
 
-.. image:: ../assets/zocalo.png
-  :alt: Diagram of zocalo
+![Diagram of zocalo](../assets/zocalo.png)
 
-Zocalo jobs are triggered based on their ISPyB DCID using the ``ZocaloTrigger`` class in a callback subscribed to the 
-Bluesky plan or ``RunEngine``. These can trigger processing for any kind of job, as zocalo infers the necessary 
+Zocalo jobs are triggered based on their ISPyB DCID using the ``ZocaloTrigger`` class in a callback subscribed to the
+Bluesky plan or ``RunEngine``. These can trigger processing for any kind of job, as zocalo infers the necessary
 processing from data in ISPyB.
 
-Results are received using the ``ZocaloResults`` device, so that they can be read into a plan and used for 
-decision-making. Currently the ``ZocaloResults`` device is only made to handle X-ray centring results. It subscribes to 
+Results are received using the ``ZocaloResults`` device, so that they can be read into a plan and used for
+decision-making. Currently the ``ZocaloResults`` device is only made to handle X-ray centring results. It subscribes to
 a given zocalo RabbitMQ channel the first time that it is triggered.
 
-Zocalo Service
-==============
+# Zocalo Service
 
-The Zocalo service processes incoming messages using recipes which describe routing of messages between processing 
-steps. You can see `source for the recipes here`_.
-
-.. _source for the recipes here: https://gitlab.diamond.ac.uk/scisoft/zocalo/-/tree/master/recipes
+The Zocalo service processes incoming messages using recipes which describe routing of messages between processing
+steps. You can see [source for the recipes here](https://gitlab.diamond.ac.uk/scisoft/zocalo/-/tree/master/recipes).
 
 You can find more information about Zocalo at https://confluence.diamond.ac.uk/display/SSCC/How+to+create+an+MX+processing+pipeline
 
-Gridscans
----------
+## Gridscans
 
-The Zocalo Service receives messages of the following form for both the xy and xz gridscans::
+The Zocalo Service receives messages of the following form for both the xy and xz gridscans:
 
+```
     {
         'recipes': ['mimas'],
         'parameters': {
@@ -39,9 +34,11 @@ The Zocalo Service receives messages of the following form for both the xy and x
             'guid': 'd6f117bb-c856-4df8-b9bc-2d3c625e9fd5'
         }
     }
+```
 
-Zocalo is then sent stop messages::
+Zocalo is then sent stop messages:
 
+```
    {
         'recipes': ['mimas'],
         'parameters': {
@@ -50,22 +47,22 @@ Zocalo is then sent stop messages::
             'guid': '9a96e59c-da30-494c-8380-c7a5c828c2c9'
         },
    }
+```
 
 these tell zocalo that the data is now ready to be processed.
 
 Zocalo then uses the ISPyB DataCollection ID to fetch the corresponding info from ISPyB
 
-The messages that zocalo receives can be found in Graylog in the Zocalo stream, from there you can find the log of 
+The messages that zocalo receives can be found in Graylog in the Zocalo stream, from there you can find the log of
 the recipe processing using the path to the logbook that comes from messages like these::
     Message saved in logbook at /dls/tmp/zocalo/dispatcher/2024-12/cb/62d35b-7cc9-4f1b-868b-712e82aa0271
 
-From the zocalo graylog you can also see that once the gridscan nexus file is picked up (for the CPU gridscan) it 
-starts a recipe::
+From the zocalo graylog you can also see that once the gridscan nexus file is picked up (for the CPU gridscan) it
+starts a recipe:
 
+```
     {'recipes': ['per-image-analysis-gridscan-i03-no-really'], 'parameters': {'ispyb_dcid': 16085803, 'filename': '{filename}', 'start_frame_index': '{start_frame_index}', 'number_of_frames': '{number_of_frames}', 'message_index': '{message_index}', 'guid': 'd10f8b8c-57a5-4dc4-acaf-a22f8d2bbf60'}, 'recipe': <workflows.recipe.recipe.Recipe object at 0x7f0587f13110>}
+```
 
-
-If you look at the recipe json, Zocalo then runs Per-Image-Analysis on each frame and then assembles the results in 
-the `DLS X-Ray Centring service`_.
-
-.. _DLS X-Ray Centring service: https://github.com/DiamondLightSource/python-dlstbx/blob/a8fcbd30335bf13f5e35df78badfc60397500535/src/dlstbx/services/xray_centering.py
+If you look at the recipe json, Zocalo then runs Per-Image-Analysis on each frame and then assembles the results in
+the [DLS X-Ray Centring service](https://github.com/DiamondLightSource/python-dlstbx/blob/a8fcbd30335bf13f5e35df78badfc60397500535/src/dlstbx/services/xray_centering.py).