Configure bluesky instrument#
After the steps in the Installation checklist are complete, it is time to configure the instrument for the details of this specific user.
Settings for various aspects of data collection are distributed amongst the many
directories and files of the instrument/ subdirectory. This directory is
configured as a Python package so that it can be loaded
with an import statement, such as:
from instrument.collection import *
The file
instrument/iconfig.yml gathers many common configuration details
into one location (in the root directory of the instrument
package). This is a text file in YAML format. It’s easy
to edit with any text editor.
Initial configuration of the instrument#
Amongst the many items you might edit in the instrument/iconfig.yml
file, the databroker catalog name is the first.
Change:
DATABROKER_CATALOG: &databroker_catalog training
to (assuming your catalog is named 45ida_abcd):
DATABROKER_CATALOG: &databroker_catalog 45ida_abcd
You should change this line:
ALLOW_AREA_DETECTOR_WARMUP: true
to
ALLOW_AREA_DETECTOR_WARMUP: false
You may comment these lines (used by the training IOCs, not so likely to use them with your instrument):
ADSIM_IOC_PREFIX: "ad:"
GP_IOC_PREFIX: "gp:"
AD_IMAGE_DIR: "adsimdet/%Y/%m/%d"
AD_MOUNT_PATH: /tmp
BLUESKY_MOUNT_PATH: /tmp/docker_ioc/iocad/tmp
Parts of the instrument package#
The instrument package is divided into several submodules to make it
easier to identify the source definition of any supported item.
Framework
~~~~~~~~~
The instrument.framework directory contains the files that setup the
core of Bluesky (and related packages).
matplotlib#
The instrument.mpl directory contains the matplotlib configuration
for data visualizations.
Callbacks#
The instrument.callbacks directory contains custom handling of the
documents from the Bluesky RunEngine.
If your instrument does not need to generate data files as if they came
from the SPEC data collection software, then change this line in your
instrument/iconfig.yml file:
from
WRITE_SPEC_DATA_FILES: true
to
WRITE_SPEC_DATA_FILES: false
Other callbacks are possible. For example, the APS USAXS instrument writes NeXus files using a callback.
The order of file loading is controlled by the lines in the init.py file. In some cases, the sequence of loading is important.
Devices#
On startup, Devices (which describe your hardware controls) are configured before Plans. This pattern is designed to avoid import loops (A needs B which needs A).
There are many files in the instrument/devices/ directory. None of
them are in use until they are uncommented in the
./instrument/devices/__init__.py file (and then the IPython session
is restarted). Before you uncomment one of these files, you might need
to adjust the contents of the file first to match your hardware. These
files are leftovers as used in the bluesky training examples and provide
ideas for what is possible with your instrument.
The order of file loading is controlled by the lines in the init.py file. In some cases, the sequence of loading is important.
Note: A major principle is that any activities on startup should
not change settings in EPICS. With this in mind, you gain the
confidence that EPICS will not be affected just beacuse a Bluesky
session was started. (This is why you changed
ALLOW_AREA_DETECTOR_WARMUP to false above.)
Tip: SPEC users: spec2ophyd can translate much of your SPEC config file into content for the Devices directory.
Plans#
The instrument/plans/ directory contains Python files that define
the custom Bluesky plans for your instrument. The existing files serve
as examples.
The order of file loading is controlled by the lines in the init.py file. In some cases, the sequence of loading is important.
Utils#
This directory is for Python code your instrument needs but is not easily classified as Callbacks, Devices, or Plans. For example, standard analytical routines might be best placed in Utils.
The order of file loading is controlled by the lines in the init.py file. In some cases, the sequence of loading is important.