instrument.utils

Add Python modules here that provide any other code not covered by callbacks, configs, core, devices, or plans.

aps_functions	APS utility helper functions
controls_setup	EPICS & ophyd related setup
helper_functions	Generic utility helper functions
_logging_setup	Configure logging for this session.
metadata	RunEngine Metadata

APS utility helper functions

host_on_aps_subnet()	Detect if this host is on an APS subnet.
aps_dm_setup(dm_setup_file)	APS Data Management setup

instrument.utils.aps_functions.aps_dm_setup(dm_setup_file)

APS Data Management setup

Read the bash shell script file used by DM to setup the environment. Parse any export lines and add their environment variables to this session. This is done by brute force here since the APS DM environment setup requires different Python code than bluesky and the two often clash.

This setup must be done before any of the DM package libraries are called.

instrument.utils.aps_functions.host_on_aps_subnet()

Detect if this host is on an APS subnet.

EPICS & ophyd related setup

oregistry	Registry of all ophyd-style Devices and Signals.
set_control_layer([control_layer])	Communications library between ophyd and EPICS Channel Access.
set_timeouts()	Set default timeout for all EpicsSignal connections & communications.
epics_scan_id_source(scan_id_epics, _md)	Callback function for RunEngine.
connect_scan_id_pv(RE[, pv])	Define a PV to use for the RunEngine's scan_id.

instrument.utils.controls_setup.connect_scan_id_pv(RE, pv: str = None)

Define a PV to use for the RunEngine’s scan_id.

instrument.utils.controls_setup.epics_scan_id_source(scan_id_epics, _md)

Callback function for RunEngine. Returns next scan_id to be used.

• Ignore metadata dictionary passed as argument.

• Get current scan_id from PV.

• Apply lower limit of zero.

• Increment (so that scan_id numbering starts from 1).

• Set PV with new value.

• Return new value.

Exception will be raised if PV is not connected when next bps.open_run() is called.

instrument.utils.controls_setup.oregistry

Registry of all ophyd-style Devices and Signals.

instrument.utils.controls_setup.set_control_layer(control_layer: str = 'PyEpics')

Communications library between ophyd and EPICS Channel Access.

Choices are: PyEpics (default) or caproto.

OPHYD_CONTROL_LAYER is an application of “lessons learned.”

Only used in a couple rare cases where PyEpics code was failing. It’s defined here since it was difficult to find how to do this in the ophyd documentation.

instrument.utils.controls_setup.set_timeouts()

Set default timeout for all EpicsSignal connections & communications.

Generic utility helper functions

running_in_queueserver()	Detect if running in the bluesky queueserver.
debug_python()
mpl_setup()	MatPlotLib setup.
is_notebook()	Detect if running in a notebook.

instrument.utils.helper_functions.debug_python()

instrument.utils.helper_functions.is_notebook()

Detect if running in a notebook.

see: https://stackoverflow.com/a/39662359/1046449

instrument.utils.helper_functions.mpl_setup()

MatPlotLib setup.

instrument.utils.helper_functions.running_in_queueserver()

Detect if running in the bluesky queueserver.

Configure logging for this session.

There are many _loggers_ to control the level of detailed logging for some bluesky/ophyd internals. The next table shows some of the many possible logger names. Configure the ACTIVATE_LOGGERS dictionary (below, where the keys are logger names and the values are logging level, as shown) with any of these names, or others which you may find useful:

logger name	description
bluesky	logger to which all bluesky log records propagate
bluesky.emit_document	when a Document is emitted. The log record does not contain the full content of the Document.
bluesky.RE	Records from a RunEngine. INFO-level notes state changes. DEBUG-level notes when each message from a plan is about to be processed and when a status object has completed.
bluesky.RE.msg	when each Msg is about to be processed.
bluesky.RE.state	when the RunEngine’s state changes.
databroker	logger to which all databroker log records propagate
ophyd	logger to which all ophyd log records propagate
ophyd.objects	records from all devices and signals (that is, OphydObject subclasses)
ophyd.control_layer	requests issued to the underlying control layer (e.g. pyepics, caproto)
ophyd.event_dispatcher	regular summaries of the backlog of updates from the control layer that are being processed on background threads

References:

• https://blueskyproject.io/ophyd/user_v1/reference/logging.html#logger-names

• https://blueskyproject.io/bluesky/debugging.html#logger-names

instrument.utils._logging_setup.configure_logging()

configure logging setup to be used with instrument package

RunEngine Metadata

MD_PATH	PersistentDict Directory to save RE metadata between sessions.
get_md_path()	Get PersistentDict directory for RE metadata.
re_metadata([cat])	Programmatic metadata for the RunEngine.

instrument.utils.metadata.MD_PATH = '/home/runner/.config/Bluesky_RunEngine_md'

PersistentDict Directory to save RE metadata between sessions.

instrument.utils.metadata.get_md_path()

Get PersistentDict directory for RE metadata.

instrument.utils.metadata.re_metadata(cat=None)

Programmatic metadata for the RunEngine.