Running Bluesky locally

This document outlines how to run Bluesky locally for rapid testing and development using the provided sm-bluesky command-line tools. This will run a local instance of BlueAPI alongside a message broker with an ipython interactive environment.

Local BlueAPI with sm-bluesky

To run blueAPI locally, you must first start a message broker (RabbitMQ/STOMP) to handle live event streaming (This will soon not be necessary). Please follow the instructions at Start RabbitMQ to set up your message bus.

Important

Once RabbitMQ is running, you can start the BlueAPI server and connect your client.

Step 1: Start the BlueAPI Server

In a terminal, start the BlueAPI server using your configuration file:

sm-bluesky start blueapi --config ./src/yaml_config/blueapi_config.yaml

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

---
api:
  url: http://0.0.0.0:8000
env:
  metadata:
    instrument: iXX
  sources:
    - kind: deviceManager
      module: dodal.beamlines.i06
      mock: True
    - kind: planFunctions
      module: dodal.plans
    - kind: planFunctions
      module: dodal.plan_stubs.wrapped
stomp:
  enabled: True
  url: tcp://localhost:61613/

Step 2: Connect to your running server

To connect to a local BlueAPI instance via the interactive client, you can pass your configuration file:

sm-bluesky client --config ./src/yaml_config/blueapi_config.yaml -s my_session

Tip

Remote Option: If you are connecting to a remote beamline server, you can use the -b / --beamline flag instead to connect automatically without a local config file:

sm-bluesky client -b p99 -s cm44186-1

Step 3: Run a Plan

Once the interactive IPython shell opens, your active session is bound to the session variable. You can trigger hardware plans directly using the python client:

# Run a simple count plan on the DCM device
 pl.count(dev.dcm)

Advanced Configurations

Customizing Devices & Plans

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

For devices (example device path: sm_bluesky.beamlines.p99):

env:
    sources:
    - kind: deviceManager
      module: sm_bluesky.beamlines.p99

For plans (example plans path: sm_bluesky.beamlines.p99.plans):

env:
    sources:
    - kind: planFunctions
      module: sm_bluesky.beamlines.p99.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:

For a full list of available commands and flags, check out the CLI Reference.