Running Bluesky on p99

This document outlines three methods for running Bluesky on the p99 beamline: using the Athena service, running Bluesky locally, or using a local blueAPI instance.

Athena

The Athena service provides a pre-configured Bluesky environment running on a Kubernetes cluster. You can access the blueAPI control interface for Athena here.

For developers who need to access the Kubernetes deployment directly, the landing page is available here. Note that authentication may be required.

Local Bluesky

For rapid testing and development, running Bluesky locally is often the most convenient approach. A Jupyter Notebook template pre-configured with p99 hardware settings is available at: src/p99-bluesky/tests/jupyter_tests/p99_bluesky_template.ipynb.

To open the template, execute the following command within your activated virtual environment:

jupyter notebook ./tests/jupyter_tests/p99_bluesky_template.ipynb

This notebook provides a starting point for interacting with p99 hardware.

Warning

P99 hardware is only accessible on its dedicated network. The simplest method for testing is to connect to p99-ws001 via SSH:

ssh -X p99-ws001

Note

Devices are imported from the dodal library. For detailed information on creating new devices, refer to the ophyd-async documentation.

The following flowchart can assist in determining the appropriate device type.

Adhering to the device standards is crucial when creating new devices.

Local blueAPI

To run blueAPI locally, you must first start a RabbitMQ instance, you can do this by running the blueAPI script here.

Once RabbitMQ is running, execute the following command from the project root directory:

blueapi --config ./src/yaml_config/blueapi_config.yaml serve

This will start blueAPI with the p99 configuration. To modify the configuration, edit the /workspaces/sm-bluesky/src/yaml_config/blueapi_config.yaml file.

---
stomp:
  host: "localhost"
  port: 61613
  auth:
    username: "guest"
    password: "guest"

env:
  sources:
    - kind: deviceFunctions
      module: "dodal.beamlines.p99"
    - kind: planFunctions
      module: "p99_bluesky.plans"
  events:
    broadcast_status_events: True

Tip

To add custom devices and plans, specify their module paths within the configuration file’s env.sources section:

For devices (example device path: p99_bluesky.devices):

env:
    sources:
    - kind: deviceFunctions
        module: p99_bluesky.devices

For plans (example plans path: p99_bluesky.plans):

env:
    sources:
    - kind: planFunctions
        module: p99_bluesky.plans

Note

Plans must have a return type of MsgGenerator from the bluesky.protocols library and complete type hints for blueAPI to recognize them. For example:

def grid_fast_scan(
    dets: list[Readable],
    count_time: float,
    step_motor: Motor,
    step_start: float,
    step_end: float,
    scan_motor: Motor,
    scan_start: float,
    scan_end: float,
    plan_time: float,
    point_correction: float = 1,
    step_size: float | None = None,
    home: bool = False,
    snake_axes: bool = True,
    md: dict[str, Any] | None = None,
) -> MsgGenerator: