5. Run a Plan

Now that we have a running worker and we have added plans and devices to the config.yaml file, we should be able to run a plan.

Run the following command in the terminal. (Same terminal where you ran blueapi controller devices/plans).

Blueapi v1.19.0 onwards - websockets

As of blueapi release v1.19.0, websockets are used. This removes the need for any stomp configuraion and addresses issues regarding unstable rabbitmq connections.

If using blueapi v1.19.0 onwards, use the --ws flag to run a plan:

blueapi -c config.yaml controller run --ws -i cm12345-1 count '{"detectors": ["det"], "num":5}'

Or, set the BLUEAPI_CONTROLLER_RUN_WS environment variable to 1/on/t/true/y/yes

From the python client, use the run_blocking method. This has the same signature as the existing run_task method.

Currently, the bc.plans.count(...) approach still uses the existing stomp connection until an agreed way of opting in to websockets can be found.

Blueapi pre-v1.19.0 - no websockets

If using a version of blueapi older than v1.19.0, use the following commands to run a plan:

Run a Sleep plan

blueapi -c config.yaml controller run -i cm12345-1 sleep '{"time": 5}'

You may get this error in the terminal logs:

Error: Stomp configuration required to run plans is missing or disabled

We need to enable stomp in our config.yaml file. Add the following lines to your config.yaml. This should not be within the env section, but should rather be its own section.

stomp:
  enabled: true
  url: tcp://localhost:61613/

Your overall config.yaml should now look like:

env:
  metadata:
    instrument: demo
  sources:
    - kind: deviceManager
      module: blueapi.tutorial.devices
    - kind: planFunctions
      module: dodal.plans
    - kind: planFunctions
      module: dodal.plan_stubs.wrapped
stomp:
  enabled: true
  url: tcp://localhost:61613/

If you had difficulties creating your config.yaml file, you can use the pre-made one in the docs/resources folder.

Try running the Sleep plan again. You may come across this error:

WARNING stomp.py could not connect to host localhost, port 61613: [Errno 111] Connection refused

To run a plan in blocking mode, we need the message bus to be started. Blueapi can publish updates to this message bus asynchronously and then the CLI can view these updates and display them to the user. Run the following command in a new terminal window and restart the blueapi server.

echo "[rabbitmq_stomp].">enabled_plugins && podman run -it --rm --name rabbitmq-docs -v $(readlink -f enabled_plugins):/etc/rabbitmq/enabled_plugins:z -p 5672:5672 -p 61613:61613 rabbitmq:latest

Now, try running the Sleep plan. You should see ‘Plan succeeded’ in the terminal logs of the terminal window where the blueapi server is running.

Example Plans

Below are some other plans you can try. In the terminal window where the Sleep plan was run, you should see

INFO root Stomp client subscribing to name='public.worker.event'

Press CTRL+C to disconnect the Stomp client then run a new plan.

Run a Scan

blueapi -c config.yaml controller run count '{"detectors": ["det"], "num":5}' -i cm1234-5

Run a Step Scan

blueapi -c config.yaml controller run step_scan '{"detectors":["det"], "params":[["stage.x",[0,5,1]]]}' -i cm1234-5

Adding extra components to the configuration

Having added the minimal configuration required to run a plan, we can add optional components. For example:

The CLI uses REST requests talk to the worker via a message broker on tcp://localhost:61613, but you can customize this via the config.yaml file.

# client.yaml

api:
  url: http://example.com:8082

Then run

blueapi -c custom-address.yaml controller plans

Other components that can be added to the config are detailed in the the How-to-Guide section.