Devices

Ophyd-style Devices for the APS.

Also consult the Index under the Ophyd heading for links to the Devices, Exceptions, Mixins, Signals, and other support items described here.

Categories

See these categories:

• APS General Support

• Area Detector Support

• Factory Functions

• Fly Scan Support

• Insertion Devices

• Motors, Positioners, Axes, …

• Detector & Scaler Support

• Shutters

• Slits

• Temperature Support

• Other Support

APS General Support

ApsCycleDM(*args, **kwargs)	Get the APS cycle name from a local file (source: official APS schedule).
ApsMachineParametersDevice([prefix, kind, ...])	Common operational parameters of the APS of general interest.
ApsPssShutter(prefix, *args[, close_pv, ...])	APS PSS shutter
ApsPssShutterWithStatus(prefix, state_pv, ...)	APS PSS shutter with separate status PV
SimulatedApsPssShutterWithStatus(*args, **kwargs)	Simulated APS PSS shutter

Area Detector Support

ad_creator(prefix, *[, ad_setup, bases, ...])	Create an area detector object from a custom class.
ad_class_factory(name[, bases, plugins, ...])	Build an Area Detector class with specified plugins.

AD_EpicsFileNameHDF5Plugin(*args, **kwargs)	Alternative to HDF5Plugin: EPICS area detector PV sets file name.
AD_EpicsFileNameJPEGPlugin(*args, **kwargs)	Alternative to JPEGPlugin: EPICS area detector PV sets file name.
AD_EpicsFileNameTIFFPlugin(*args, **kwargs)	Alternative to TIFFPlugin: EPICS area detector PV sets file name.

AD_EpicsFileNameMixin(*args, **kwargs)	Custom class to define image file name from EPICS.
AD_EpicsHdf5FileName(*args, **kwargs)	Custom class to define HDF5 image file name from EPICS PVs.
AD_EpicsHDF5IterativeWriter(*args, **kwargs)	intermediate class between AD_EpicsHdf5FileName and AD_EpicsFileNameHDF5Plugin
AD_EpicsJPEGFileName(*args, **kwargs)	Custom class to define JPEG image file name from EPICS PVs.
AD_EpicsJPEGIterativeWriter(*args, **kwargs)	intermediate class between AD_EpicsJPEGFileName and AD_EpicsFileNameJPEGPlugin
AD_EpicsTIFFFileName(*args, **kwargs)	Custom class to define TIFF image file name from EPICS PVs.
AD_EpicsTIFFIterativeWriter(*args, **kwargs)	intermediate class between AD_EpicsTIFFFileName and AD_EpicsFileNameTIFFPlugin
AD_setup_FrameType(prefix[, scheme])	configure so frames are identified & handled by type (dark, white, or image)
BadPixelPlugin(*args, **kwargs)	ADCore NDBadPixel, new in AD 3.13.
CamMixin_V34([prefix, kind, read_attrs, ...])	Update cam support to AD release 3.1.1.
CamMixin_V3_1_1([prefix, kind, read_attrs, ...])	Update cam support to AD release 3.1.1.
SingleTrigger_V34(*args, **kwargs)	Variation of ophyd's SingleTrigger mixin supporting AcquireBusy.

AD_full_file_name_local(plugin)	Return AD plugin's Last filename using local filesystem path.
AD_plugin_primed(plugin)	Has area detector pushed an NDarray to the file writer plugin? True or False
AD_prime_plugin2(plugin)	Prime this area detector's file writer plugin.
ensure_AD_plugin_primed(plugin[, allow])	Ensure the AD file writing plugin is primed (warmed up), if allowed.

Detector & Scaler Support

Struck3820([prefix, kind, read_attrs, ...])	Struck/SIS 3820 Multi-Channel Scaler (as used by USAXS)
MeasCompCtr([prefix, kind, read_attrs, ...])	Measurement Computing USB CTR08 high-speed counter/timer.
MeasCompCtrMcs([prefix, kind, read_attrs, ...])	Measurement Computing USB CTR08 Multi-Channel Scaler Controls.
use_EPICS_scaler_channels(scaler)	configure scaler for only the channels with names assigned in EPICS
SynPseudoVoigt(name, motor, motor_field[, ...])	Evaluate a point on a pseudo-Voigt based on the value of a motor.

Tip

The Measurement Computing USB-CTR08 EPICS support provides a compatible EPICS scaler record.

Factory Functions

Object Factories

Object factories create ophyd objects.

ad_creator(prefix, *[, ad_setup, bases, ...])	Create an area detector object from a custom class.
make_dict_device(obj[, name])	Make recordable DictionaryDevice instance from dictionary.
mb_creator(*[, prefix, name, motors, ...])	Create MotorBundle with any number of motors.

Class Factories

Class factories create ophyd Device classes.

ad_class_factory(name[, bases, plugins, ...])	Build an Area Detector class with specified plugins.
dict_device_factory([data])	Create a DictionaryDevice class using the supplied dictionary.
mb_class_factory([motors, class_bases, ...])	Create a custom MotorBundle (or as specified in 'class_bases') class.

Fly Scan Support

ScalerMotorFlyer() support withdrawn pending issue #763.

Insertion Devices

PlanarUndulator([prefix, kind, read_attrs, ...])	APS Planar Undulator.
Revolver_Undulator([prefix, kind, ...])	APS Revolver Insertion Device.
STI_Undulator([prefix, kind, read_attrs, ...])	APS Planar Undulator built by STI Optronics.
Undulator2M([prefix, kind, read_attrs, ...])	APS 2M Undulator.
Undulator4M([prefix, kind, read_attrs, ...])	APS 4M Undulator.

Note

The ApsUndulator and ApsUndulatorDual device support classes have been removed. These devices are not used in the APS-U era.

Motors, Positioners, Axes, …

AcsMotor([prefix, kind, read_attrs, ...])	AcsMotionControl motor support.
AxisTunerException	Exception during execution of AxisTunerBase subclass
AxisTunerMixin(*args, **kwargs)	Mixin class to provide tuning capabilities for an axis
EpicsDescriptionMixin([prefix, kind, ...])	add a record's description field to a Device, such as EpicsMotor
mb_class_factory([motors, class_bases, ...])	Create a custom MotorBundle (or as specified in 'class_bases') class.
mb_creator(*[, prefix, name, motors, ...])	Create MotorBundle with any number of motors.
EpicsMotorDialMixin([prefix, kind, ...])	add motor record's dial coordinate fields to Device
EpicsMotorEnableMixin([prefix, kind, ...])	mixin providing access to motor enable/disable
EpicsMotorRawMixin([prefix, kind, ...])	add motor record's raw coordinate fields to Device
EpicsMotorResolutionMixin([prefix, kind, ...])	Add motor record's resolution fields to motor.
EpicsMotorServoMixin([prefix, kind, ...])	add motor record's servo loop controls to Device
PVPositionerSoftDone([prefix, readback_pv, ...])	PVPositioner that computes done as a soft signal.
PVPositionerSoftDoneWithStop([prefix, ...])	PVPositionerSoftDone with stop() and inposition.
EpicsMotorShutter(*args[, tolerance])	Shutter, implemented with an EPICS motor moved between two positions
EpicsOnOffShutter(*args[, open_value, ...])	Shutter using a single EPICS PV moved between two positions
SimulatedSwaitControllerPositioner(*args[, ...])	Simulated process controller as positioner with EPICS swait record.
SimulatedTransformControllerPositioner(*args)	Simulated process controller as positioner with EPICS transform record.

Shutters

ApsPssShutter(prefix, *args[, close_pv, ...])	APS PSS shutter
ApsPssShutterWithStatus(prefix, state_pv, ...)	APS PSS shutter with separate status PV
EpicsMotorShutter(*args[, tolerance])	Shutter, implemented with an EPICS motor moved between two positions
EpicsOnOffShutter(*args[, open_value, ...])	Shutter using a single EPICS PV moved between two positions
OneSignalShutter(*args[, open_value, ...])	Shutter Device using one Signal for open and close.
ShutterBase(*args[, open_value, ...])	Base class for all shutter Devices.
SimulatedApsPssShutterWithStatus(*args, **kwargs)	Simulated APS PSS shutter

Slits

HHLSlits(prefix, pitch_motor, yaw_motor, ...)	High Heat Load Slit.
XiaSlit2D([prefix, kind, read_attrs, ...])	EPICS synApps optics xia_slit.db 2D support: inb out bot top ...
Optics2Slit1D([prefix, kind, read_attrs, ...])	EPICS synApps optics 2slit.db 1D support: xn, xp, size, center, sync
Optics2Slit2D_HV([prefix, kind, read_attrs, ...])	EPICS synApps optics 2slit.db 2D support: h.xn, h.xp, v.xn, v.xp
Optics2Slit2D_InbOutBotTop([prefix, kind, ...])	EPICS synApps optics 2slit.db 2D support: inb, out, bot, top
SlitGeometry(width, height, x, y)	Slit size and center as a named tuple

synApps Support

See separate synApps section.

Temperature Support

Controllers

Eurotherm2216e([prefix, tolerance])	Eurotherm 2216e Temperature Controller
LakeShore336Device([prefix, kind, ...])	LakeShore 336 temperature controller.
LakeShore340Device([prefix, kind, ...])	LakeShore 340 temperature controller
Linkam_CI94_Device(*args, **kwargs)	Linkam model CI94 temperature controller
Linkam_T96_Device(*args, **kwargs)	Linkam model T96 temperature controller
PTC10AioChannel([prefix, kind, read_attrs, ...])	SRS PTC10 AIO module
PTC10RtdChannel([prefix, kind, read_attrs, ...])	SRS PTC10 RTD module channel
PTC10TcChannel([prefix, kind, read_attrs, ...])	SRS PTC10 Tc (thermocouple) module channel
PTC10PositionerMixin(*args, **kwargs)	Mixin so SRS PTC10 can be used as a (temperature) positioner.
SimulatedSwaitControllerPositioner(*args[, ...])	Simulated process controller as positioner with EPICS swait record.
SimulatedTransformControllerPositioner(*args)	Simulated process controller as positioner with EPICS transform record.

Readers

MeasCompTc32([prefix, kind, read_attrs, ...])

Measurement Computing TC-32 32-channel Thermocouple reader.

Other Support

ApsBssUserInfoDevice([prefix, kind, ...])	Provide current experiment info from the APS BSS.
DM_WorkflowConnector([name, workflow])	Support for the APS Data Management tools.
Pf4FilterSingle([prefix, kind, read_attrs, ...])	XIA PF4 Filter: one set of 4 filters (A).
Pf4FilterDual([prefix, kind, read_attrs, ...])	XIA PF4 Filter: two sets of 4 filters (A, B).
Pf4FilterTriple([prefix, kind, read_attrs, ...])	XIA PF4 Filter: three sets of 4 filters (A, B, C).
Pf4FilterBank(prefix[, bank])	A single module of XIA PF4 filters (4-blades).
Pf4FilterCommon([prefix, kind, read_attrs, ...])	XIA PF4 filters - common support.
DualPf4FilterBox([prefix, kind, read_attrs, ...])	LEGACY (use Pf4FilterDual now): Dual (Al, Ti) Xia PF4 filter boxes
EpicsDescriptionMixin([prefix, kind, ...])	add a record's description field to a Device, such as EpicsMotor
dict_device_factory([data])	Create a DictionaryDevice class using the supplied dictionary.
make_dict_device(obj[, name])	Make recordable DictionaryDevice instance from dictionary.
EpicsScanIdSignal(read_pv[, write_pv, ...])	Use an EPICS PV as the source of the RunEngine's scan_id.
MeasCompCtr([prefix, kind, read_attrs, ...])	Measurement Computing USB CTR08 high-speed counter/timer.
KohzuSeqCtl_Monochromator([prefix, kind, ...])	synApps Kohzu double-crystal monochromator sequence control program
SimulatedSwaitControllerPositioner(*args[, ...])	Simulated process controller as positioner with EPICS swait record.
SimulatedTransformControllerPositioner(*args)	Simulated process controller as positioner with EPICS transform record.
SRS570_PreAmplifier(*args, **kwargs)	Ophyd support for Stanford Research Systems 570 preamplifier from synApps.
Struck3820([prefix, kind, read_attrs, ...])	Struck/SIS 3820 Multi-Channel Scaler (as used by USAXS)
DG645Delay([prefix, kind, read_attrs, ...])	An SRS DG-645 digial delay/pulse generator.
LabJackBase([prefix, kind, read_attrs, ...])	A labjack T-series data acquisition unit (DAQ).
LabJackT4([prefix, kind, read_attrs, ...])	A labjack T-series data acquisition unit (DAQ).
LabJackT7([prefix, kind, read_attrs, ...])	A labjack T-series data acquisition unit (DAQ).
LabJackT7Pro([prefix, kind, read_attrs, ...])	A labjack T-series data acquisition unit (DAQ).
LabJackT8([prefix, kind, read_attrs, ...])	A labjack T-series data acquisition unit (DAQ).

Internal Routines

ApsOperatorMessagesDevice([prefix, kind, ...])	General messages from the APS main control room.
TrackingSignal(*, name[, value, dtype, ...])	Non-EPICS signal for use when coordinating Device actions.
DeviceMixinBase([prefix, kind, read_attrs, ...])	Base class for apstools Device mixin classes

All Submodules

ACS Motors

AcsMotors provides extra signals that are part of AcsMotionControl motor support.

AcsMotorMixin([prefix, kind, read_attrs, ...])	Components used by EPICS database for ACS Motion Controller.
EpicsMotorWithRes([prefix, kind, ...])	Adds support for motor record resolution fields.
EpicsMotorWithResAndCNEN([prefix, kind, ...])	Adds "servo" enable/disable (CNEN) field.
EpicsMotorWithResAndCNENAndDial([prefix, ...])	Adds support for motor record dial coordinates.

class apstools.devices.acs_motors.AcsMotor(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, **kwargs)

Bases: AcsMotorMixin, EpicsMotorWithResAndCNENAndDial

AcsMotionControl motor support.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of AcsMotorTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(success=True, timestamp=None, value=None, **kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_move_changed(timestamp=None, value=None, sub_type=None, **kwargs)

Callback from EPICS, indicating that movement status has changed

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(pos)

Check that the position is within the soft limits

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

e2fac

Secondary encoder factor (distance per encoder count)

e2offs

Secondary encoder offset (doesn’t persist through power cycle)

e2type

Secondary encoder type

e_aoffs

Absolute encoder offset (persists through ACS power cycle)

efac

Encoder factor (distance per encoder count)

property egu

The engineering units (EGU) for a position

eoffs

Encoder offset (doesn’t persist through power cycle)

etype

Encoder type

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_lim(flag)

Returns the travel limit of motor

• flag > 0: returns high limit

• flag < 0: returns low limit

• flag == 0: returns None

Included here for compatibility with similar with SPEC command.

Parameters

highfloat

Limit of travel in the positive direction.

lowfloat

Limit of travel in the negative direction.

home(direction, wait=True, **kwargs)

Perform the default homing function in the desired direction

Parameters

directionHomeEnum

Direction in which to perform the home search.

homed

Homing status (using ACS algorithms)

move(position, wait=True, **kwargs)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

Returns

moving : bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property position

The current position of the motor in its engineering units

Returns

position : float

property precision

The precision of the readback PV, as reported by EPICS

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

roffs

Reference offset

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

set_current_position(pos)

Configure the motor user position to the given value

Parameters

pos

Position to set.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

set_lim(low, high)

Sets the low and high travel limits of motor

• No action taken if motor is moving.

• Low limit is set to lesser of (low, high)

• High limit is set to greater of (low, high)

Included here for compatibility with similar with SPEC command.

Parameters

highfloat

Limit of travel in the positive direction.

lowfloat

Limit of travel in the negative direction.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stepf

Step factor (distance per [micro]step)

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.acs_motors.AcsMotorMixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: DeviceMixinBase

Components used by EPICS database for ACS Motion Controller.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of AcsMotorMixinTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

e2fac

Secondary encoder factor (distance per encoder count)

e2offs

Secondary encoder offset (doesn’t persist through power cycle)

e2type

Secondary encoder type

e_aoffs

Absolute encoder offset (persists through ACS power cycle)

efac

Encoder factor (distance per encoder count)

eoffs

Encoder offset (doesn’t persist through power cycle)

etype

Encoder type

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

homed

Homing status (using ACS algorithms)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

roffs

Reference offset

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stepf

Step factor (distance per [micro]step)

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.acs_motors.EpicsMotorWithRes(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, **kwargs)

Bases: EpicsMotorResolutionMixin, EpicsMotor

Adds support for motor record resolution fields.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of EpicsMotorWithResTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(success=True, timestamp=None, value=None, **kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_move_changed(timestamp=None, value=None, sub_type=None, **kwargs)

Callback from EPICS, indicating that movement status has changed

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(pos)

Check that the position is within the soft limits

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_lim(flag)

Returns the travel limit of motor

• flag > 0: returns high limit

• flag < 0: returns low limit

• flag == 0: returns None

Included here for compatibility with similar with SPEC command.

Parameters

highfloat

Limit of travel in the positive direction.

lowfloat

Limit of travel in the negative direction.

home(direction, wait=True, **kwargs)

Perform the default homing function in the desired direction

Parameters

directionHomeEnum

Direction in which to perform the home search.

move(position, wait=True, **kwargs)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

Returns

moving : bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property position

The current position of the motor in its engineering units

Returns

position : float

property precision

The precision of the readback PV, as reported by EPICS

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

set_current_position(pos)

Configure the motor user position to the given value

Parameters

pos

Position to set.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

set_lim(low, high)

Sets the low and high travel limits of motor

• No action taken if motor is moving.

• Low limit is set to lesser of (low, high)

• High limit is set to greater of (low, high)

Included here for compatibility with similar with SPEC command.

Parameters

highfloat

Limit of travel in the positive direction.

lowfloat

Limit of travel in the negative direction.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.acs_motors.EpicsMotorWithResAndCNEN(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, **kwargs)

Bases: EpicsMotorServoMixin, EpicsMotorWithRes

Adds “servo” enable/disable (CNEN) field.

ACS support uses for steppers as well.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of EpicsMotorWithResAndCNENTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(success=True, timestamp=None, value=None, **kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_move_changed(timestamp=None, value=None, sub_type=None, **kwargs)

Callback from EPICS, indicating that movement status has changed

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(pos)

Check that the position is within the soft limits

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_lim(flag)

Returns the travel limit of motor

• flag > 0: returns high limit

• flag < 0: returns low limit

• flag == 0: returns None

Included here for compatibility with similar with SPEC command.

Parameters

highfloat

Limit of travel in the positive direction.

lowfloat

Limit of travel in the negative direction.

home(direction, wait=True, **kwargs)

Perform the default homing function in the desired direction

Parameters

directionHomeEnum

Direction in which to perform the home search.

move(position, wait=True, **kwargs)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

Returns

moving : bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property position

The current position of the motor in its engineering units

Returns

position : float

property precision

The precision of the readback PV, as reported by EPICS

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

set_current_position(pos)

Configure the motor user position to the given value

Parameters

pos

Position to set.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

set_lim(low, high)

Sets the low and high travel limits of motor

• No action taken if motor is moving.

• Low limit is set to lesser of (low, high)

• High limit is set to greater of (low, high)

Included here for compatibility with similar with SPEC command.

Parameters

highfloat

Limit of travel in the positive direction.

lowfloat

Limit of travel in the negative direction.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.acs_motors.EpicsMotorWithResAndCNENAndDial(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, **kwargs)

Bases: EpicsMotorDialMixin, EpicsMotorWithResAndCNEN

Adds support for motor record dial coordinates.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of EpicsMotorWithResAndCNENAndDialTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(success=True, timestamp=None, value=None, **kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_move_changed(timestamp=None, value=None, sub_type=None, **kwargs)

Callback from EPICS, indicating that movement status has changed

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(pos)

Check that the position is within the soft limits

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_lim(flag)

Returns the travel limit of motor

• flag > 0: returns high limit

• flag < 0: returns low limit

• flag == 0: returns None

Included here for compatibility with similar with SPEC command.

Parameters

highfloat

Limit of travel in the positive direction.

lowfloat

Limit of travel in the negative direction.

home(direction, wait=True, **kwargs)

Perform the default homing function in the desired direction

Parameters

directionHomeEnum

Direction in which to perform the home search.

move(position, wait=True, **kwargs)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

Returns

moving : bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property position

The current position of the motor in its engineering units

Returns

position : float

property precision

The precision of the readback PV, as reported by EPICS

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

set_current_position(pos)

Configure the motor user position to the given value

Parameters

pos

Position to set.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

set_lim(low, high)

Sets the low and high travel limits of motor

• No action taken if motor is moving.

• Low limit is set to lesser of (low, high)

• High limit is set to greater of (low, high)

Included here for compatibility with similar with SPEC command.

Parameters

highfloat

Limit of travel in the positive direction.

lowfloat

Limit of travel in the negative direction.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

APS User Proposal and ESAF Information

ApsBssUserInfoDevice([prefix, kind, ...])

Provide current experiment info from the APS BSS.

class apstools.devices.aps_bss_user.ApsBssUserInfoDevice(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Provide current experiment info from the APS BSS.

BSS: Beamtime Scheduling System

EXAMPLE:

bss_user_info = ApsBssUserInfoDevice(
                    "9id_bss:",
                    name="bss_user_info")
sd.baseline.append(bss_user_info)

NOTE: There is info provided by the APS proposal & ESAF systems.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of ApsBssUserInfoDeviceTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

APS cycles

ApsCycleDM(*args, **kwargs)

Get the APS cycle name from a local file (source: official APS schedule).

class apstools.devices.aps_cycle.ApsCycleDM(*args, **kwargs)

Bases: SynSignalRO

Get the APS cycle name from a local file (source: official APS schedule).

Previously, this info was available from the BSS API in the APS Data Management (thus the DM name). Now that interface requires credentialed access only.

This signal is read-only.

Changed in version 1.7.8: Provide cycle info empirically when not in data table. (Drop DM API.)

_repr_info()

Yields pairs of (key, value) to generate the Signal repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_metadata_callbacks()

Run SUB_META in the appropriate dispatcher thread

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_and_wait(value, timeout, **kwargs)

Overridable hook for subclasses to override set() functionality.

This will be called in a separate thread (_set_thread), but will not be called in parallel.

Parameters

valueany

The value

timeoutfloat, optional

Maximum time to wait for value to be successfully set, or None

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

property connected

Is the signal connected to its associated hardware, and ready to use?

describe()

Provide schema and meta-data for read()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration()

Provide schema & meta-data for BlueskyInterface.read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect the Signal from the underlying control layer; destroy it

Clears all subscriptions on this Signal. Once destroyed, the signal may no longer be used.

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get()

The readback value

property high_limit

The high, inclusive control limit for the Signal

property hints

Field hints for plotting

property limits

The control limits (low, high), such that low <= value <= high

property low_limit

The low, inclusive control limit for the Signal

property metadata

A copy of the metadata dictionary associated with the signal

property metadata_keys

Metadata keys that will be passed along on value subscriptions

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

put(value, *, timestamp=None, force=False)

Low-level method for writing to a Signal.

The value is optionally checked first, depending on the value of force. In addition, VALUE subscriptions are run.

Extra kwargs are ignored (for API compatibility with EpicsSignal kwargs pass through).

Parameters

valueany

Value to set

timestampfloat, optional

The timestamp associated with the value, defaults to time.time()

metadatadict, optional

Further associated metadata with the value (such as alarm status, severity, etc.)

forcebool, optional

Check the value prior to setting it, defaults to False

read()

Put the status of the signal into a simple dictionary format for data acquisition

Returns

dict

property read_access

Can the signal be read?

read_configuration()

Dictionary mapping names to value dicts with keys: value, timestamp

property report

A report on the object.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(value, *, timestamp=None, force=False)

Set the value of the Signal and return a Status object.

Returns

stStatus

This status object will be finished upon return in the case of basic soft Signals

sim_set_func(func)

Update the SynSignal function to set a new value on trigger.

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timestamp

Timestamp of the readback value

property tolerance

The absolute tolerance associated with the value.

trigger()

Call that is used by bluesky prior to read()

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

property value

The signal’s value

wait_for_connection(timeout=0.0)

Wait for the underlying signals to initialize or connect

property write_access

Can the signal be written to?

class apstools.devices.aps_cycle._ApsCycleDB

Bases: object

Python representation of the APS run cycle schedule table.

property _bss_list_runs

Get the full list of APS runs via a Data Management API or ‘None’.

_read_cycle_data()

Read the list of APS run cycles from a local file.

The file is formatted in YAML after reformatting content received from the APS Data Management package (aps-dm-api). The YAML format is easily updated and human-readable.

_write_cycle_data(output_file: str = None)

Write the list of APS run cycles to a local file.

The content of this file is received from the APS Data Management package (aps-dm-api) and reformatted here for readbility. This allows automatic updates as needed.

MANUAL UPDATE OF CYCLE YAML FILE

To update the LOCAL_FILE, run this code (on a workstation at the APS configured to use the DM tools):

from apstools.devices.aps_cycle import cycle_db
from apstools.utils import dm_setup
dm_setup("/path/to/dm.setup.sh")
cycle_db._write_cycle_data()

get_cycle_name(ts=None)

Get the name of the current APS run cycle.

By default, the name of the current run cycle (based on the current timestamp) will be returned.

PARAMETERS

ts float:

Absolute time stamp (such as from time.time()). Default: current time stamp.

RETURNS

Returns cycle name (str) or None if timestamp is not in data table.

Connect with APS Data Management workflows.

Example:

import bluesky
from apstools.devices import DM_WorkflowConnector

RE = bluesky.RunEngine()

dm_workflow = DM_WorkflowConnector(name="dm_workflow", labels=["DM"])
RE(
    dm_workflow.run_as_plan(
        workflow="example-01",
        filePath="/home/beams/S1IDTEST/.bashrc"
    )
)

Note

DM_WorkflowConnector() requires APS Data Management package (aps-dm-api >=5)

DM_WorkflowConnector([name, workflow])

Support for the APS Data Management tools.

class apstools.devices.aps_data_management.DM_WorkflowConnector(name=None, workflow=None, **kwargs)

Bases: Device

Support for the APS Data Management tools.

The DM workflow dictionary of arguments (workflow_args) needs special attention. Python’s dict structure is not compatible with MongoDB. In turn, ophyd does not support it. A custom plan can choose how to use the workflow_args dictionary:

• use with DM workflow, as planned

• add workflow_args to the start metadata

• write as run stream:

  from apstools.devices import make_dict_device
  from apstools.plans import write_stream
  
  yield from write_stream(
      [make_dict_device(workflow_args, name="kwargs")],
      "workflow_args"
  )
  

api	Local copy of DM Processing API object.
idle	Is DM Processing idle?
processing_jobs	The list of DM processsing jobs.
report_processing_stages([truncate])	Print a table about each stage of the workflow process.
report_status([t_offset])	Status report.
run_as_plan([workflow, wait, timeout])	Run the DM workflow as a bluesky plan.
start_workflow([workflow, timeout])	Kickoff a DM workflow with optional reporting timeout.
workflows	Return the list of workflows.
put_if_different(signal, value)	Put ophyd signal only if new value is different.
_update_processing_data()	(internal) Called periodically (while process runs) to update self.job.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of DM_WorkflowConnectorTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

_update_processing_data()

(internal) Called periodically (while process runs) to update self.job.

Also updates certain ophyd signals.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

property api

Local copy of DM Processing API object.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

getJob()

Get the current processing job object.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property idle

Is DM Processing idle?

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property processing_jobs

The list of DM processsing jobs.

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

put_if_different(signal, value)

Put ophyd signal only if new value is different.

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

report_processing_stages(truncate=40)

Print a table about each stage of the workflow process.

report_status(t_offset=None)

Status report.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

run_as_plan(workflow: str = '', wait: bool = True, timeout: int = 180, **kwargs)

Run the DM workflow as a bluesky plan.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

start_workflow(workflow='', timeout=180, **kwargs)

Kickoff a DM workflow with optional reporting timeout.

The reporting process will continue until the workflow ends or the timeout period is exceeded. It does not affect the actual workflow.

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

property workflows

Return the list of workflows.

APS Machine Parameters

APS machine parameters

ApsMachineParametersDevice([prefix, kind, ...])	Common operational parameters of the APS of general interest.
ApsOperatorMessagesDevice([prefix, kind, ...])	General messages from the APS main control room.

class apstools.devices.aps_machine.ApsMachineParametersDevice(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Common operational parameters of the APS of general interest.

EXAMPLE:

import apstools.devices
aps = apstools.devices.ApsMachineParametersDevice(name="aps")
aps_current = aps.current

# make sure these values are logged at start and stop of every scan
sd.baseline.append(aps)
# record storage ring current as secondary stream during scans
# name: aps_current_monitor
# db[-1].table("aps_current_monitor")
sd.monitors.append(aps_current)

The sd.baseline and sd.monitors usage relies on this global setup:

from bluesky import SupplementalData
sd = SupplementalData()
RE.preprocessors.append(sd)

inUserOperations

determine if APS is in User Operations mode (boolean)

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of ApsMachineParametersDeviceTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property inUserOperations

determine if APS is in User Operations mode (boolean)

Use this property to configure ophyd Devices for direct or simulated hardware. See issue #49 (BCDA-APS/apstools#49) for details.

EXAMPLE:

APS = apstools.devices.ApsMachineParametersDevice(name="APS")

if APS.inUserOperations:
    suspend_APS_current = bluesky.suspenders.SuspendFloor(APS.current, 2, resume_thresh=10)
    RE.install_suspender(suspend_APS_current)
else:
    # use pseudo shutter controls and no current suspenders
    pass

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_machine.ApsOperatorMessagesDevice(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

General messages from the APS main control room.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of ApsOperatorMessagesDeviceTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

APS undulators (Insertion Devices)

PlanarUndulator([prefix, kind, read_attrs, ...])	APS Planar Undulator.
Revolver_Undulator([prefix, kind, ...])	APS Revolver Insertion Device.
STI_Undulator([prefix, kind, read_attrs, ...])	APS Planar Undulator built by STI Optronics.
Undulator2M([prefix, kind, read_attrs, ...])	APS 2M Undulator.
Undulator4M([prefix, kind, read_attrs, ...])	APS 4M Undulator.

Note

The ApsUndulator and ApsUndulatorDual device support classes have been removed. These devices are not used in the APS-U era.

class apstools.devices.aps_undulator.ID_Controls_Mixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Common controls components for insertion devices.

Works for: Planar & Revolver

The signals busy and done convey complementary information. busy comes from the IOC, while done comes directly from the controller.

start_button	A descriptor representing a device component (or signal)
stop_button	A descriptor representing a device component (or signal)
busy	A descriptor representing a device component (or signal)
done	A descriptor representing a device component (or signal)
motor_drive_status	A descriptor representing a device component (or signal)

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of ID_Controls_MixinTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_undulator.ID_Misc_Mixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Common miscellaneous components for insertion devices.

Works for: Planar & Revolver

gap_deadband	A descriptor representing a device component (or signal)
device_limit	A descriptor representing a device component (or signal)
access_mode	A descriptor representing a device component (or signal)
message1	A descriptor representing a device component (or signal)
message2	A descriptor representing a device component (or signal)
device	A descriptor representing a device component (or signal)
magnet	A descriptor representing a device component (or signal)
location	A descriptor representing a device component (or signal)
version_plc	A descriptor representing a device component (or signal)

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of ID_Misc_MixinTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_undulator.ID_Spectrum_Mixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Common spectrum components for insertion devices.

Works for: Planar & Revolver

energy	A descriptor representing a device component (or signal)
energy_taper	A descriptor representing a device component (or signal)
gap	A descriptor representing a device component (or signal)
gap_taper	A descriptor representing a device component (or signal)
harmonic_value	A descriptor representing a device component (or signal)
total_power	A descriptor representing a device component (or signal)

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of ID_Spectrum_MixinTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_undulator.PlanarUndulator(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: ID_Spectrum_Mixin, ID_Controls_Mixin, ID_Misc_Mixin, Device

APS Planar Undulator.

APS Use: 34 devices, including 20ID.

EXAMPLE:

undulator = PlanarUndulator("S25ID:USID:", name="undulator")

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of PlanarUndulatorTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_undulator.Revolver_Undulator(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: ID_Spectrum_Mixin, ID_Controls_Mixin, ID_Misc_Mixin, Device

APS Revolver Insertion Device.

APS Use: Only 08US, 08DS, 34DS.

EXAMPLE:

undulator = Revolver_Undulator("S08ID:USID:", name="undulator")

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Revolver_UndulatorTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_undulator.STI_Undulator(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: PlanarUndulator

APS Planar Undulator built by STI Optronics.

APS Use: 13 devices, including 4ID.

EXAMPLE:

undulator = STI_Undulator("S04ID:USID:", name="undulator")

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of STI_UndulatorTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_undulator.Undulator2M(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: ID_Spectrum_Mixin, ID_Controls_Mixin, ID_Misc_Mixin, Device

APS 2M Undulator.

APS Use: 1ID, downstream.

EXAMPLE:

undulator = Undulator2M("S01ID:DSID:", name="undulator")

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Undulator2MTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_undulator.Undulator4M(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Undulator2M

APS 4M Undulator.

APS Use: 11ID, downstream & upstream.

EXAMPLE:

undulator = Undulator4M("S11ID:DSID:", name="undulator")

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Undulator4MTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.aps_undulator.UndulatorPositioner(prefix='', *, limits=None, name=None, read_attrs=None, configuration_attrs=None, parent=None, egu='', **kwargs)

Bases: PVPositioner

A positioner for any of the gap control parameters.

Communicates with the parent (presumably the undulator device) to start and stop the device.

setpoint	A descriptor representing a device component (or signal)
readback	A descriptor representing a device component (or signal)
actuate	A descriptor representing a device component (or signal)
stop_signal	A descriptor representing a device component (or signal)
done	A descriptor representing a device component (or signal)
done_value

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of UndulatorPositionerTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(**kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_setup_move(position)

Move and do not wait until motion is complete (asynchronous)

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(pos)

Check that the position is within the soft limits

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

move(position, wait=True, timeout=None, moved_cb=None)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

If a done PV is specified, it will be read directly to get the motion status. If not, it determined from the internal state of PVPositioner.

Returns

bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property position

The current position of the motor in its engineering units

Returns

position : any

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

Area Detector Factory

ad_creator(prefix, *[, ad_setup, bases, ...])	Create an area detector object from a custom class.
ad_class_factory(name[, bases, plugins, ...])	Build an Area Detector class with specified plugins.
PLUGIN_DEFAULTS	Default plugin configuration dictionary.

EXAMPLE 1: DEFAULT CAM

Just the camera plugin (uses CamBase, the most basic features):

from apstools.devices import ad_creator
det = ad_creator("ad:", name="det", class_name="MySimpleAD", ["cam",])

EXAMPLE 2: CUSTOM CAM & IMAGING

View ADSimDetector image with CA and PVA:

from ophyd.areadetector import SimDetectorCam
from apstools.devices import ad_creator

det = ad_creator(
    "ad:", name="det", class_name="MySimDetector",
    plugins=[
        {"cam": {"class": SimDetectorCam}},
        "image",
        "pva",
    ],
)

EXAMPLE 3: CUSTOM CAM, IMAGING, & HDF5 FILES

Record HDF5 images with Eiger detector. Here, both the Eiger detector IOC and the Bluesky databroker use the same filesystem mount /:

from ophyd.areadetector import EigerDetectorCam
from apstools.devices import ad_creator

det = ad_creator(
    "ad:", name="det", class_name"MyEiger",
    plugins=[
        {"cam": {"class": EigerDetectorCam}},
        "image",
        {"hdf1": {"write_path_template": "/"}},
    ],
)

EXAMPLE 4: CUSTOM CAM, IMAGING, & BASIC HDF5 PLUGIN

Override one of the default plugin configurations. In this case, remove the write_path_template and read_path_template keys from the hdf1 plugin support and switch to the plugin class from ophyd:

from ophyd.areadetector import EigerDetectorCam
from ophyd.areadetector.plugins import HDF5Plugin_V34
from apstools.devices import ad_creator, PLUGIN_DEFAULTS

plugin_defaults = PLUGIN_DEFAULTS.copy()
plugin_defaults["hdf1"].pop("read_path_template", None)
plugin_defaults["hdf1"].pop("write_path_template", None)

det = ad_creator(
    "ad:", name="det", class_name"MyEiger",
    plugins=[
        {"cam": {"class": EigerDetectorCam}},
        "image",
        {"hdf1": {"class": HDF5Plugin_V34}},
    ],
    plugin_defaults=plugin_defaults,
)

apstools.devices.area_detector_factory.PLUGIN_DEFAULTS = {'attr1': {'class': <class 'ophyd.areadetector.plugins.AttrPlotPlugin_V34'>, 'suffix': 'Attr1:'}, 'badpix1': {'class': <class 'apstools.devices.area_detector_support.BadPixelPlugin'>, 'suffix': 'BadPix1:'}, 'cam': {'class': <class 'apstools.devices.area_detector_support.SimDetectorCam_V34'>, 'suffix': 'cam1:'}, 'cb1': {'class': <class 'ophyd.areadetector.plugins.CircularBuffPlugin_V34'>, 'suffix': 'CB1:'}, 'cc1': {'class': <class 'ophyd.areadetector.plugins.ColorConvPlugin_V34'>, 'suffix': 'CC1:'}, 'cc2': {'class': <class 'ophyd.areadetector.plugins.ColorConvPlugin_V34'>, 'suffix': 'CC2:'}, 'codec1': {'class': <class 'ophyd.areadetector.plugins.CodecPlugin_V34'>, 'suffix': 'Codec1:'}, 'fft1': {'class': <class 'ophyd.areadetector.plugins.FFTPlugin_V34'>, 'suffix': 'FFT1:'}, 'gather1': {'class': <class 'ophyd.areadetector.plugins.GatherNPlugin_V31'>, 'suffix': 'Gather1:'}, 'hdf1': {'class': <class 'apstools.devices.area_detector_support.HDF5FileWriterPlugin'>, 'read_path_template': None, 'suffix': 'HDF1:', 'write_path_template': None}, 'image': {'class': <class 'ophyd.areadetector.plugins.ImagePlugin_V34'>, 'suffix': 'image1:'}, 'jpeg1': {'class': <class 'apstools.devices.area_detector_support.AD_EpicsFileNameJPEGPlugin'>, 'read_path_template': None, 'suffix': 'JPEG1:', 'write_path_template': None}, 'magick1': {'class': <class 'ophyd.areadetector.plugins.MagickPlugin_V34'>, 'read_path_template': None, 'suffix': 'Magick1:', 'write_path_template': None}, 'netcdf1': {'class': <class 'ophyd.areadetector.plugins.NetCDFPlugin_V34'>, 'read_path_template': None, 'suffix': 'netCDF1:', 'write_path_template': None}, 'overlay1': {'class': <class 'ophyd.areadetector.plugins.OverlayPlugin_V34'>, 'suffix': 'Over1:'}, 'process1': {'class': <class 'ophyd.areadetector.plugins.ProcessPlugin_V34'>, 'suffix': 'Proc1:'}, 'pva': {'class': <class 'ophyd.areadetector.plugins.PvaPlugin_V34'>, 'suffix': 'Pva1:'}, 'roi1': {'class': <class 'ophyd.areadetector.plugins.ROIPlugin_V34'>, 'suffix': 'ROI1:'}, 'roi2': {'class': <class 'ophyd.areadetector.plugins.ROIPlugin_V34'>, 'suffix': 'ROI2:'}, 'roi3': {'class': <class 'ophyd.areadetector.plugins.ROIPlugin_V34'>, 'suffix': 'ROI3:'}, 'roi4': {'class': <class 'ophyd.areadetector.plugins.ROIPlugin_V34'>, 'suffix': 'ROI4:'}, 'roistat1': {'class': <class 'ophyd.areadetector.plugins.ROIStatPlugin_V34'>, 'suffix': 'ROIStat1:'}, 'scatter1': {'class': <class 'ophyd.areadetector.plugins.ScatterPlugin_V34'>, 'suffix': 'Scatter1:'}, 'stats1': {'class': <class 'ophyd.areadetector.plugins.StatsPlugin_V34'>, 'suffix': 'Stats1:'}, 'stats2': {'class': <class 'ophyd.areadetector.plugins.StatsPlugin_V34'>, 'suffix': 'Stats2:'}, 'stats3': {'class': <class 'ophyd.areadetector.plugins.StatsPlugin_V34'>, 'suffix': 'Stats3:'}, 'stats4': {'class': <class 'ophyd.areadetector.plugins.StatsPlugin_V34'>, 'suffix': 'Stats4:'}, 'stats5': {'class': <class 'ophyd.areadetector.plugins.StatsPlugin_V34'>, 'suffix': 'Stats5:'}, 'tiff1': {'class': <class 'apstools.devices.area_detector_support.AD_EpicsFileNameTIFFPlugin'>, 'read_path_template': None, 'suffix': 'TIFF1:', 'write_path_template': None}, 'transform1': {'class': <class 'ophyd.areadetector.plugins.TransformPlugin_V34'>, 'suffix': 'Trans1:'}}

Default plugin configuration dictionary.

These defaults could be replaced by a caller individually or in total. For example, the "class" could be replaced by a newer, version-specific class. Another use case is to remove an existing set of defaults.

apstools.devices.area_detector_factory.ad_class_factory(name, bases=None, plugins=None, plugin_defaults=None)

Build an Area Detector class with specified plugins.

PARAMETERS

name str :

Name of the class to be created.

bases object or tuple :

Parent(s) of the new class. (default: (SingleTrigger_V34, DetectorBase))

plugins list :

Description of the plugins used. The list consists of either strings or dictionaries. (default: ["cam"] – Just the camera plugin.)

plugin_defaults object :

Plugin configuration dictionary. (default: None, PLUGIN_DEFAULTS will be used.)

Here are a couple examples of the plugins keyword.

EXAMPLE 1: ALL DEFAULTS

All defaults are acceptable. In this case, the cam (CamBase from ophyd) will only support the most general features of the detector hardware:

plugins=["cam", "image", "pva"]

This is a shorthand for:

plugins=[{"cam": {}}, {"image": {}}, {"pva": {}}]

EXAMPLE 2: CUSTOM CAM CLASS

More typical is when one or more defaults need to be replaced, such as the class used to provide features specific to the hardware. The inner dictionaries contain the keyword arguments to be replaced for each plugin. All these dictionaries are empty, signifying all defaults are acceptable.

For the ADSimDetector, replace the string "cam" with a dictionary that replaces the default camera class. Other detectors will have their own camera class that provides access to the specific features of that detector.

Here the Python class is imported from apstools. Use the class as it is imported or defined. Do not use quotations around SimDetectorCam_V34:

from apstools.devices import SimDetectorCam_V34

plugins=[{"cam": {"class": SimDetectorCam_V34}}, "image", "pva"]

Added in version 1.7.0.

apstools.devices.area_detector_factory.ad_creator(prefix: str, *, ad_setup: object = None, bases=None, class_name: str = None, name: str = None, plugin_defaults: dict = None, plugins=None, validate_ports: bool = True, **kwargs)

Create an area detector object from a custom class.

PARAMETERS

prefix str :

EPICS PV prefix.

name str :

Name of the ophyd object.

class_name str :

Name of the class to be created. (default: "ADclass_HEX7" where HEX is a random 7-digit hexadecimal string)

plugins list :

Description of the plugins used.

bases object or tuple:

Parent(s) of the new class. (default: (SingleTrigger_V34, DetectorBase))

ad_setup object :

Optional setup function to be called. Blocking code is allowed for this function (does not have to be a bluesky plan stub). (default: None)

plugin_defaults object :

Plugin configuration dictionary. (default: None, PLUGIN_DEFAULTS will be used.)

validate_ports bool :

When True (default), call .validate_asyn_ports(). This call will wait for PV connections. Set ‘False’ to skip this test on startup.

If assigned plugin ports are used but no ophyd plugin class is provided, an ophyd exception will be raised when the detector tries to take an image.

(new in apstools release 1.7.3)

kwargs dict :

Any additional keyword arguments for the new class definition. (default: {})

Added in version 1.7.0.

Area Detector Support

AD_EpicsFileNameHDF5Plugin(*args, **kwargs)	Alternative to HDF5Plugin: EPICS area detector PV sets file name.
AD_EpicsFileNameJPEGPlugin(*args, **kwargs)	Alternative to JPEGPlugin: EPICS area detector PV sets file name.
AD_EpicsFileNameMixin(*args, **kwargs)	Custom class to define image file name from EPICS.
AD_EpicsFileNameTIFFPlugin(*args, **kwargs)	Alternative to TIFFPlugin: EPICS area detector PV sets file name.
AD_EpicsHdf5FileName(*args, **kwargs)	Custom class to define HDF5 image file name from EPICS PVs.
AD_EpicsHDF5IterativeWriter(*args, **kwargs)	intermediate class between AD_EpicsHdf5FileName and AD_EpicsFileNameHDF5Plugin
AD_EpicsJPEGFileName(*args, **kwargs)	Custom class to define JPEG image file name from EPICS PVs.
AD_EpicsJPEGIterativeWriter(*args, **kwargs)	intermediate class between AD_EpicsJPEGFileName and AD_EpicsFileNameJPEGPlugin
AD_EpicsTIFFFileName(*args, **kwargs)	Custom class to define TIFF image file name from EPICS PVs.
AD_EpicsTIFFIterativeWriter(*args, **kwargs)	intermediate class between AD_EpicsTIFFFileName and AD_EpicsFileNameTIFFPlugin
AD_FrameType_schemes	Naming schemes for area detector frame types.
AD_full_file_name_local(plugin)	Return AD plugin's Last filename using local filesystem path.
AD_plugin_primed(plugin)	Has area detector pushed an NDarray to the file writer plugin? True or False
AD_prime_plugin(detector, plugin)	Prime this area detector's file writer plugin.
AD_prime_plugin2(plugin)	Prime this area detector's file writer plugin.
AD_setup_FrameType(prefix[, scheme])	configure so frames are identified & handled by type (dark, white, or image)
BadPixelPlugin(*args, **kwargs)	ADCore NDBadPixel, new in AD 3.13.
CamMixin_V3_1_1([prefix, kind, read_attrs, ...])	Update cam support to AD release 3.1.1.
CamMixin_V34([prefix, kind, read_attrs, ...])	Update cam support to AD release 3.1.1.
HDF5FileWriterPlugin(*args, **kwargs)	Add data acquisition methods to HDF5Plugin.
SingleTrigger_V34(*args, **kwargs)	Variation of ophyd's SingleTrigger mixin supporting AcquireBusy.
ensure_AD_plugin_primed(plugin[, allow])	Ensure the AD file writing plugin is primed (warmed up), if allowed.

class apstools.devices.area_detector_support.AD_EpicsFileNameHDF5Plugin(*args, **kwargs)

Bases: HDF5Plugin_V34, AD_EpicsHDF5IterativeWriter

Alternative to HDF5Plugin: EPICS area detector PV sets file name.

Caution

Caveat emptor applies here. You assume expertise!

Uses AD_EpicsHdf5FileName.

EXAMPLE:

from apstools.devices import CamMixin_V34
from apstools.devices import SimDetectorCam_V34
from apstools.devices import SingleTrigger_V34
from apstools.devices.area_detector_support import AD_EpicsFileNameHDF5Plugin
from ophyd import EpicsSignalWithRBV
from ophyd.areadetector import ADComponent
from ophyd.areadetector import DetectorBase
from ophyd.areadetector.plugins import ImagePlugin_V34 as ImagePlugin
from ophyd.areadetector.plugins import PvaPlugin_V34 as PvaPlugin
import datetime
import pathlib


IOC = "ad:"
IMAGE_DIR = "adsimdet/%Y/%m/%d"
AD_IOC_MOUNT_PATH = pathlib.Path("/tmp")
BLUESKY_MOUNT_PATH = pathlib.Path("/tmp/docker_ioc/iocad/tmp")

# MUST end with a `/`, pathlib will NOT provide it
WRITE_PATH_TEMPLATE = f"{AD_IOC_MOUNT_PATH / IMAGE_DIR}/"
READ_PATH_TEMPLATE = f"{BLUESKY_MOUNT_PATH / IMAGE_DIR}/"

class SimDetector_V34(SingleTrigger_V34, DetectorBase):
    '''ADSimDetector'''

    cam = ADComponent(SimDetectorCam_V34, "cam1:")
    image = ADComponent(ImagePlugin, "image1:")
    hdf1 = ADComponent(
        AD_EpicsFileNameHDF5Plugin,
        "HDF1:",
        write_path_template=WRITE_PATH_TEMPLATE,
        read_path_template=READ_PATH_TEMPLATE,
    )
    pva = ADComponent(PvaPlugin, "Pva1:")

Added in version 1.6.2.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of AD_EpicsFileNameHDF5PluginTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_plugin_type_connected(connected, **kw)

Connection callback on the plugin type

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

property array_pixels

The total number of pixels, calculated from array_size

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration()

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

disable_on_stage()

when the plugin is staged, ensure that it is disabled.

a convenience method for adding `('enable', 0) to stage_sigs

property dotted_name: str

Return the dotted name

enable_on_stage()

when the plugin is staged, ensure that it is enabled.

a convenience method for adding (‘enable’, 1) to stage_sigs

ensure_blocking()

Ensure that if plugin is enabled after staging, callbacks block.

a convenience method for adding `('blocking_callbacks', 1) to stage_sigs

ensure_nonblocking()

Ensure that if plugin is enabled after staging, callbacks don’t block.

a convenience method for adding `('blocking_callbacks', 0) to stage_sigs

property event_types

Events that can be subscribed to via obj.subscribe

find_signal(text, use_re=False, case_sensitive=False, match_fcn=None, f=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Search through the signal docs on this detector for the string text

Parameters

textstr

Text to find

use_rebool, optional

Use regular expressions

case_sensitivebool, optional

Case sensitive search

match_fcncallable, optional

Function to call when matches are found Defaults to a function that prints matches to f

ffile-like, optional

File-like object that the default match function prints to (Defaults to sys.stdout)

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

get_asyn_digraph()

Get the directed graph of the ASYN ports

Returns

Gnetworkx.DiGraph

Directed graph of pipelines

port_mapdict

Mapping between port_name and ADBase objects

get_asyn_port_dictionary()

Return port name : component map

Returns

port_mapdict

Mapping between port_name and ADBase objects

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_frames_per_point()

overrides default behavior

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_plugin_by_asyn_port(port_name)

Get the plugin which has the given asyn port name

Parameters

port_namestr

The port name to search for

Returns

retADBase or None

Either the requested plugin or None if not found

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

missing_plugins()

Find missing ports

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration()

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property source_plugin

The PluginBase object that is the asyn source for this plugin.

stage()

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

validate_asyn_ports()

Validate that all components of pipeline are known

Raises

RuntimeError

If there any input ports to known plugins where the source is not known to ophyd

visualize_asyn_digraph(ax=None, *args, **kwargs)

This generates a figure showing the current asyn port layout.

This method generates a plot showing all of the currently enabled Areadetector plugin asyn ports and their relationships. The current ports and relationships are found using self.get_asyn_digraph.

Parameters

ax: matplotlib axes

if None (default) then a new figure is created otherwise it is plotted on the specified axes.

*args, **kwargsnetworkx.draw_networkx args and kwargs.

For the allowed args and kwargs see the networkx.draw_networkx documentation

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

warmup()

A convenience method for ‘priming’ the plugin.

The plugin has to ‘see’ one acquisition before it is ready to capture. This sets the array size, etc.

class apstools.devices.area_detector_support.AD_EpicsFileNameJPEGPlugin(*args, **kwargs)

Bases: JPEGPlugin_V34, AD_EpicsJPEGIterativeWriter

Alternative to JPEGPlugin: EPICS area detector PV sets file name.

Caution

Caveat emptor applies here. You assume expertise!

Uses AD_EpicsJpegFileName.

EXAMPLE:

from apstools.devices import CamMixin_V34
from apstools.devices import SimDetectorCam_V34
from apstools.devices import SingleTrigger_V34
from apstools.devices.area_detector_support import AD_EpicsFileNameJPEGPlugin
from ophyd import EpicsSignalWithRBV
from ophyd.areadetector import ADComponent
from ophyd.areadetector import DetectorBase
from ophyd.areadetector.plugins import ImagePlugin_V34 as ImagePlugin
from ophyd.areadetector.plugins import PvaPlugin_V34 as PvaPlugin
import datetime
import pathlib


IOC = "ad:"
IMAGE_DIR = "adsimdet/%Y/%m/%d"
AD_IOC_MOUNT_PATH = pathlib.Path("/tmp")
BLUESKY_MOUNT_PATH = pathlib.Path("/tmp/docker_ioc/iocad/tmp")

# MUST end with a `/`, pathlib will NOT provide it
WRITE_PATH_TEMPLATE = f"{AD_IOC_MOUNT_PATH / IMAGE_DIR}/"
READ_PATH_TEMPLATE = f"{BLUESKY_MOUNT_PATH / IMAGE_DIR}/"


class SimDetector_V34(SingleTrigger_V34, DetectorBase):
    '''ADSimDetector'''

    cam = ADComponent(SimDetectorCam_V34, "cam1:")
    image = ADComponent(ImagePlugin, "image1:")
    jpeg1 = ADComponent(
        AD_EpicsFileNameHDF5Plugin,
        "JPEG1:",
        write_path_template=WRITE_PATH_TEMPLATE,
        read_path_template=READ_PATH_TEMPLATE,
    )
    pva = ADComponent(PvaPlugin, "Pva1:")

Added in version 1.6.2.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of AD_EpicsFileNameJPEGPluginTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_plugin_type_connected(connected, **kw)

Connection callback on the plugin type

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

property array_pixels

The total number of pixels, calculated from array_size

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration()

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

disable_on_stage()

when the plugin is staged, ensure that it is disabled.

a convenience method for adding `('enable', 0) to stage_sigs

property dotted_name: str

Return the dotted name

enable_on_stage()

when the plugin is staged, ensure that it is enabled.

a convenience method for adding (‘enable’, 1) to stage_sigs

ensure_blocking()

Ensure that if plugin is enabled after staging, callbacks block.

a convenience method for adding `('blocking_callbacks', 1) to stage_sigs

ensure_nonblocking()

Ensure that if plugin is enabled after staging, callbacks don’t block.

a convenience method for adding `('blocking_callbacks', 0) to stage_sigs

property event_types

Events that can be subscribed to via obj.subscribe

find_signal(text, use_re=False, case_sensitive=False, match_fcn=None, f=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Search through the signal docs on this detector for the string text

Parameters

textstr

Text to find

use_rebool, optional

Use regular expressions

case_sensitivebool, optional

Case sensitive search

match_fcncallable, optional

Function to call when matches are found Defaults to a function that prints matches to f

ffile-like, optional

File-like object that the default match function prints to (Defaults to sys.stdout)

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

get_asyn_digraph()

Get the directed graph of the ASYN ports

Returns

Gnetworkx.DiGraph

Directed graph of pipelines

port_mapdict

Mapping between port_name and ADBase objects

get_asyn_port_dictionary()

Return port name : component map

Returns

port_mapdict

Mapping between port_name and ADBase objects

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_frames_per_point()

overrides default behavior

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_plugin_by_asyn_port(port_name)

Get the plugin which has the given asyn port name

Parameters

port_namestr

The port name to search for

Returns

retADBase or None

Either the requested plugin or None if not found

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

missing_plugins()

Find missing ports

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration()

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property source_plugin

The PluginBase object that is the asyn source for this plugin.

stage()

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

validate_asyn_ports()

Validate that all components of pipeline are known

Raises

RuntimeError

If there any input ports to known plugins where the source is not known to ophyd

visualize_asyn_digraph(ax=None, *args, **kwargs)

This generates a figure showing the current asyn port layout.

This method generates a plot showing all of the currently enabled Areadetector plugin asyn ports and their relationships. The current ports and relationships are found using self.get_asyn_digraph.

Parameters

ax: matplotlib axes

if None (default) then a new figure is created otherwise it is plotted on the specified axes.

*args, **kwargsnetworkx.draw_networkx args and kwargs.

For the allowed args and kwargs see the networkx.draw_networkx documentation

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.area_detector_support.AD_EpicsFileNameMixin(*args, **kwargs)

Bases: FileStorePluginBase

Custom class to define image file name from EPICS.

Used as part of AD_EpicsFileNameHDF5Plugin.

Caution

Caveat emptor applies here. You assume expertise!

Replace standard ophyd file naming algorithm (where file names are defined as UUID strings, virtually guaranteeing that no existing images files will ever be overwritten).

Caller is responsible for setting values of these Components:

• array_counter

• auto_increment

• auto_save

• compression (only HDF)

• create_directory

• file_name

• file_number

• file_path

• file_template

• num_capture

make_filename()	overrides default behavior: Get info from EPICS file writer plugin.
get_frames_per_point()	overrides default behavior
stage()	Overrides default behavior of parent class.

To allow users to control the file name, we override the make_filename() method here and we need to override some intervening classes.

To allow users to control the file number, we override the stage() method here and triple-comment out that line, and bring in sections from the methods we are replacing here.

It is allowed to set the file_template="%s%s.h5" so the file name does not include the file number.

The image file name is set in FileStoreBase.make_filename() from ophyd.areadetector.filestore_mixins. This is called (during device staging) from FileStoreBase.stage()

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

describe()

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get_frames_per_point()

overrides default behavior

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

read()

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

stage()

Overrides default behavior of parent class.

Parent class items overridden here:

• Sets file_name based on a UUID.

• Sets file_path from write_path_template.

• Sets file_number to 0.

Set EPICS items before device is staged, then copy EPICS naming template (and other items) to ophyd after staging.

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

class apstools.devices.area_detector_support.AD_EpicsFileNameTIFFPlugin(*args, **kwargs)

Bases: TIFFPlugin_V34, AD_EpicsTIFFIterativeWriter

Alternative to TIFFPlugin: EPICS area detector PV sets file name.

Caution

Caveat emptor applies here. You assume expertise!

Uses AD_EpicsTIFFFileName.

EXAMPLE:

from apstools.devices import CamMixin_V34
from apstools.devices import SimDetectorCam_V34
from apstools.devices import SingleTrigger_V34
from apstools.devices.area_detector_support import AD_EpicsFileNameTIFFPlugin
from ophyd import EpicsSignalWithRBV
from ophyd.areadetector import ADComponent
from ophyd.areadetector import DetectorBase
from ophyd.areadetector.plugins import ImagePlugin_V34 as ImagePlugin
from ophyd.areadetector.plugins import PvaPlugin_V34 as PvaPlugin
from ophyd.areadetector import SimDetectorCam
import datetime
import pathlib


IOC = "ad:"
IMAGE_DIR = "adsimdet/%Y/%m/%d"
AD_IOC_MOUNT_PATH = pathlib.Path("/tmp")
BLUESKY_MOUNT_PATH = pathlib.Path("/tmp/docker_ioc/iocad/tmp")

# MUST end with a `/`, pathlib will NOT provide it
WRITE_PATH_TEMPLATE = f"{AD_IOC_MOUNT_PATH / IMAGE_DIR}/"
READ_PATH_TEMPLATE = f"{BLUESKY_MOUNT_PATH / IMAGE_DIR}/"


class SimDetector_V34(SingleTrigger_V34, DetectorBase):
    '''ADSimDetector'''

    cam = ADComponent(SimDetectorCam_V34, "cam1:")
    image = ADComponent(ImagePlugin, "image1:")
    tiff1 = ADComponent(
        AD_EpicsFileNameTIFFPlugin,
        "TIFF1:",
        write_path_template=WRITE_PATH_TEMPLATE,
        read_path_template=READ_PATH_TEMPLATE,
    )
    pva = ADComponent(PvaPlugin, "Pva1:")

Added in version 1.6.2.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of AD_EpicsFileNameTIFFPluginTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_plugin_type_connected(connected, **kw)

Connection callback on the plugin type

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

property array_pixels

The total number of pixels, calculated from array_size

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration()

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

disable_on_stage()

when the plugin is staged, ensure that it is disabled.

a convenience method for adding `('enable', 0) to stage_sigs

property dotted_name: str

Return the dotted name

enable_on_stage()

when the plugin is staged, ensure that it is enabled.

a convenience method for adding (‘enable’, 1) to stage_sigs

ensure_blocking()

Ensure that if plugin is enabled after staging, callbacks block.

a convenience method for adding `('blocking_callbacks', 1) to stage_sigs

ensure_nonblocking()

Ensure that if plugin is enabled after staging, callbacks don’t block.

a convenience method for adding `('blocking_callbacks', 0) to stage_sigs

property event_types

Events that can be subscribed to via obj.subscribe

find_signal(text, use_re=False, case_sensitive=False, match_fcn=None, f=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Search through the signal docs on this detector for the string text

Parameters

textstr

Text to find

use_rebool, optional

Use regular expressions

case_sensitivebool, optional

Case sensitive search

match_fcncallable, optional

Function to call when matches are found Defaults to a function that prints matches to f

ffile-like, optional

File-like object that the default match function prints to (Defaults to sys.stdout)

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

get_asyn_digraph()

Get the directed graph of the ASYN ports

Returns

Gnetworkx.DiGraph

Directed graph of pipelines

port_mapdict

Mapping between port_name and ADBase objects

get_asyn_port_dictionary()

Return port name : component map

Returns

port_mapdict

Mapping between port_name and ADBase objects

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_frames_per_point()

overrides default behavior

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_plugin_by_asyn_port(port_name)

Get the plugin which has the given asyn port name

Parameters

port_namestr

The port name to search for

Returns

retADBase or None

Either the requested plugin or None if not found

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

missing_plugins()

Find missing ports

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration()

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property source_plugin

The PluginBase object that is the asyn source for this plugin.

stage()

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

validate_asyn_ports()

Validate that all components of pipeline are known

Raises

RuntimeError

If there any input ports to known plugins where the source is not known to ophyd

visualize_asyn_digraph(ax=None, *args, **kwargs)

This generates a figure showing the current asyn port layout.

This method generates a plot showing all of the currently enabled Areadetector plugin asyn ports and their relationships. The current ports and relationships are found using self.get_asyn_digraph.

Parameters

ax: matplotlib axes

if None (default) then a new figure is created otherwise it is plotted on the specified axes.

*args, **kwargsnetworkx.draw_networkx args and kwargs.

For the allowed args and kwargs see the networkx.draw_networkx documentation

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.area_detector_support.AD_EpicsHDF5IterativeWriter(*args, **kwargs)

Bases: AD_EpicsHdf5FileName, FileStoreIterativeWrite

intermediate class between AD_EpicsHdf5FileName and AD_EpicsFileNameHDF5Plugin

Added in version 1.6.2.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

describe()

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get_frames_per_point()

overrides default behavior

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

read()

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

stage()

Overrides default behavior of parent class.

Parent class items overridden here:

• Sets file_name based on a UUID.

• Sets file_path from write_path_template.

• Sets file_number to 0.

Set EPICS items before device is staged, then copy EPICS naming template (and other items) to ophyd after staging.

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

class apstools.devices.area_detector_support.AD_EpicsHdf5FileName(*args, **kwargs)

Bases: AD_EpicsFileNameMixin

Custom class to define HDF5 image file name from EPICS PVs.

Used as part of AD_EpicsFileNameHDF5Plugin.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

describe()

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get_frames_per_point()

overrides default behavior

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

read()

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

stage()

Overrides default behavior of parent class.

Parent class items overridden here:

• Sets file_name based on a UUID.

• Sets file_path from write_path_template.

• Sets file_number to 0.

Set EPICS items before device is staged, then copy EPICS naming template (and other items) to ophyd after staging.

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

class apstools.devices.area_detector_support.AD_EpicsJPEGFileName(*args, **kwargs)

Bases: AD_EpicsFileNameMixin

Custom class to define JPEG image file name from EPICS PVs.

Used as part of AD_EpicsFileNameJPEGPlugin.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

describe()

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get_frames_per_point()

overrides default behavior

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

read()

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

stage()

Overrides default behavior of parent class.

Parent class items overridden here:

• Sets file_name based on a UUID.

• Sets file_path from write_path_template.

• Sets file_number to 0.

Set EPICS items before device is staged, then copy EPICS naming template (and other items) to ophyd after staging.

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

class apstools.devices.area_detector_support.AD_EpicsJPEGIterativeWriter(*args, **kwargs)

Bases: AD_EpicsJPEGFileName, FileStoreIterativeWrite

intermediate class between AD_EpicsJPEGFileName and AD_EpicsFileNameJPEGPlugin

Added in version 1.6.2.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

describe()

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get_frames_per_point()

overrides default behavior

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

read()

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

stage()

Overrides default behavior of parent class.

Parent class items overridden here:

• Sets file_name based on a UUID.

• Sets file_path from write_path_template.

• Sets file_number to 0.

Set EPICS items before device is staged, then copy EPICS naming template (and other items) to ophyd after staging.

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

class apstools.devices.area_detector_support.AD_EpicsTIFFFileName(*args, **kwargs)

Bases: AD_EpicsFileNameMixin

Custom class to define TIFF image file name from EPICS PVs.

Used as part of AD_EpicsFileNameTIFFPlugin.

Added in version 1.6.2.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

describe()

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get_frames_per_point()

overrides default behavior

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

read()

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

stage()

Overrides default behavior of parent class.

Parent class items overridden here:

• Sets file_name based on a UUID.

• Sets file_path from write_path_template.

• Sets file_number to 0.

Set EPICS items before device is staged, then copy EPICS naming template (and other items) to ophyd after staging.

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

class apstools.devices.area_detector_support.AD_EpicsTIFFIterativeWriter(*args, **kwargs)

Bases: AD_EpicsTIFFFileName, FileStoreIterativeWrite

intermediate class between AD_EpicsTIFFFileName and AD_EpicsFileNameTIFFPlugin

Added in version 1.6.2.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_remove_caller_stage_sigs()

Caller is responsible for setting these, pop from stage_sigs.

describe()

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get_frames_per_point()

overrides default behavior

make_filename()

overrides default behavior: Get info from EPICS file writer plugin.

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

read()

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

stage()

Overrides default behavior of parent class.

Parent class items overridden here:

• Sets file_name based on a UUID.

• Sets file_path from write_path_template.

• Sets file_number to 0.

Set EPICS items before device is staged, then copy EPICS naming template (and other items) to ophyd after staging.

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

apstools.devices.area_detector_support.AD_FrameType_schemes = {'DataExchange': {'ONST': '/exchange/data_dark', 'TWST': '/exchange/data_white', 'ZRST': '/exchange/data'}, 'NeXus': {'ONST': '/entry/data/dark', 'TWST': '/entry/data/white', 'ZRST': '/entry/data/data'}, 'reset': {'ONST': 'Background', 'TWST': 'FlatField', 'ZRST': 'Normal'}}

Naming schemes for area detector frame types.

apstools.devices.area_detector_support.AD_full_file_name_local(plugin)

Return AD plugin’s Last filename using local filesystem path.

Get the full name, in terms of the bluesky filesystem, for the image file recently-acquired by the area detector plugin.

Return the name as a pathlib object.

PARAMETERS

plugin obj :

Instance of ophyd area detector file writing plugin.

Added in version 1.6.2.

apstools.devices.area_detector_support.AD_plugin_primed(plugin)

Has area detector pushed an NDarray to the file writer plugin? True or False

PARAMETERS

plugin

obj : area detector plugin to be primed (such as detector.hdf1)

EXAMPLE:

AD_plugin_primed(detector.hdf1)

Works around an observed issue: #598 NSLS-II/ophyd#598

If detector IOC has just been started and has not yet taken an image with the file writer plugin, then a TimeoutError will occur as the file writer plugin “Capture” is set to 1 (Start). In such case, first acquire at least one image with the file writer plugin enabled.

Also issue in apstools (needs a robust method to detect if primed): BCDA-APS/apstools#464

Since Area Detector release 2.1 (2014-10-14).

The prime process is not needed if you select the LazyOpen feature with Stream mode for the file plugin. LazyOpen defers file creation until the first frame arrives in the plugin. This removes the need to initialize the plugin with a dummy frame before starting capture.

apstools.devices.area_detector_support.AD_prime_plugin(detector, plugin)

Prime this area detector’s file writer plugin.

PARAMETERS

detector

obj : area detector (such as detector)

plugin

obj : area detector plugin to be primed (such as detector.hdf1)

EXAMPLE:

AD_prime_plugin(detector, detector.hdf1)

apstools.devices.area_detector_support.AD_prime_plugin2(plugin)

Prime this area detector’s file writer plugin.

Collect and push an NDarray to the file writer plugin. Works with all file writer plugins.

Based on ophyd.areadetector.plugins.HDF5Plugin.warmup().

PARAMETERS

plugin

obj : area detector plugin to be primed (such as detector.hdf1)

EXAMPLE:

AD_prime_plugin2(detector.hdf1)

apstools.devices.area_detector_support.AD_setup_FrameType(prefix, scheme='NeXus')

configure so frames are identified & handled by type (dark, white, or image)

PARAMETERS

prefix

str : EPICS PV prefix of area detector, such as 13SIM1:

scheme

str : any key in the AD_FrameType_schemes dictionary

This routine prepares the EPICS Area Detector to identify frames by image type for handling by clients, such as the HDF5 file writing plugin. With the HDF5 plugin, the FrameType PV is added to the NDattributes and then used in the layout file to direct the acquired frame to the chosen dataset. The FrameType PV value provides the HDF5 address to be used.

To use a different scheme than the defaults, add a new key to the AD_FrameType_schemes dictionary, defining storage values for the fields of the EPICS mbbo record that you will be using.

see: https://nbviewer.org/github/BCDA-APS/bluesky_training/blob/main/images_darks_flats.ipynb

EXAMPLE:

AD_setup_FrameType("2bmbPG3:", scheme="DataExchange")

• Call this function before creating the ophyd area detector object

• use lower-level PyEpics interface

class apstools.devices.area_detector_support.BadPixelPlugin(*args, **kwargs)

Bases: PluginBase

ADCore NDBadPixel, new in AD 3.13.

Added in version 1.7.3.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of BadPixelPluginTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_plugin_type_connected(connected, **kw)

Connection callback on the plugin type

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

property array_pixels

The total number of pixels, calculated from array_size

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration()

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

disable_on_stage()

when the plugin is staged, ensure that it is disabled.

a convenience method for adding `('enable', 0) to stage_sigs

property dotted_name: str

Return the dotted name

enable_on_stage()

when the plugin is staged, ensure that it is enabled.

a convenience method for adding (‘enable’, 1) to stage_sigs

ensure_blocking()

Ensure that if plugin is enabled after staging, callbacks block.

a convenience method for adding `('blocking_callbacks', 1) to stage_sigs

ensure_nonblocking()

Ensure that if plugin is enabled after staging, callbacks don’t block.

a convenience method for adding `('blocking_callbacks', 0) to stage_sigs

property event_types

Events that can be subscribed to via obj.subscribe

find_signal(text, use_re=False, case_sensitive=False, match_fcn=None, f=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Search through the signal docs on this detector for the string text

Parameters

textstr

Text to find

use_rebool, optional

Use regular expressions

case_sensitivebool, optional

Case sensitive search

match_fcncallable, optional

Function to call when matches are found Defaults to a function that prints matches to f

ffile-like, optional

File-like object that the default match function prints to (Defaults to sys.stdout)

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

get_asyn_digraph()

Get the directed graph of the ASYN ports

Returns

Gnetworkx.DiGraph

Directed graph of pipelines

port_mapdict

Mapping between port_name and ADBase objects

get_asyn_port_dictionary()

Return port name : component map

Returns

port_mapdict

Mapping between port_name and ADBase objects

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_plugin_by_asyn_port(port_name)

Get the plugin which has the given asyn port name

Parameters

port_namestr

The port name to search for

Returns

retADBase or None

Either the requested plugin or None if not found

missing_plugins()

Find missing ports

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration()

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property source_plugin

The PluginBase object that is the asyn source for this plugin.

stage()

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

validate_asyn_ports()

Validate that all components of pipeline are known

Raises

RuntimeError

If there any input ports to known plugins where the source is not known to ophyd

visualize_asyn_digraph(ax=None, *args, **kwargs)

This generates a figure showing the current asyn port layout.

This method generates a plot showing all of the currently enabled Areadetector plugin asyn ports and their relationships. The current ports and relationships are found using self.get_asyn_digraph.

Parameters

ax: matplotlib axes

if None (default) then a new figure is created otherwise it is plotted on the specified axes.

*args, **kwargsnetworkx.draw_networkx args and kwargs.

For the allowed args and kwargs see the networkx.draw_networkx documentation

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.area_detector_support.CamMixin_V34(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: CamMixin_V3_1_1

Update cam support to AD release 3.1.1.

Added in version 1.6.3.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of CamMixin_V34Tuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

find_signal(text, use_re=False, case_sensitive=False, match_fcn=None, f=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Search through the signal docs on this detector for the string text

Parameters

textstr

Text to find

use_rebool, optional

Use regular expressions

case_sensitivebool, optional

Case sensitive search

match_fcncallable, optional

Function to call when matches are found Defaults to a function that prints matches to f

ffile-like, optional

File-like object that the default match function prints to (Defaults to sys.stdout)

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

get_asyn_digraph()

Get the directed graph of the ASYN ports

Returns

Gnetworkx.DiGraph

Directed graph of pipelines

port_mapdict

Mapping between port_name and ADBase objects

get_asyn_port_dictionary()

Return port name : component map

Returns

port_mapdict

Mapping between port_name and ADBase objects

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_plugin_by_asyn_port(port_name)

Get the plugin which has the given asyn port name

Parameters

port_namestr

The port name to search for

Returns

retADBase or None

Either the requested plugin or None if not found

missing_plugins()

Find missing ports

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage(*args, **kwargs)

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

validate_asyn_ports()

Validate that all components of pipeline are known

Raises

RuntimeError

If there any input ports to known plugins where the source is not known to ophyd

visualize_asyn_digraph(ax=None, *args, **kwargs)

This generates a figure showing the current asyn port layout.

This method generates a plot showing all of the currently enabled Areadetector plugin asyn ports and their relationships. The current ports and relationships are found using self.get_asyn_digraph.

Parameters

ax: matplotlib axes

if None (default) then a new figure is created otherwise it is plotted on the specified axes.

*args, **kwargsnetworkx.draw_networkx args and kwargs.

For the allowed args and kwargs see the networkx.draw_networkx documentation

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.area_detector_support.CamMixin_V3_1_1(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: CamBase

Update cam support to AD release 3.1.1.

Added in version 1.6.3.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of CamMixin_V3_1_1Tuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

find_signal(text, use_re=False, case_sensitive=False, match_fcn=None, f=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Search through the signal docs on this detector for the string text

Parameters

textstr

Text to find

use_rebool, optional

Use regular expressions

case_sensitivebool, optional

Case sensitive search

match_fcncallable, optional

Function to call when matches are found Defaults to a function that prints matches to f

ffile-like, optional

File-like object that the default match function prints to (Defaults to sys.stdout)

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

get_asyn_digraph()

Get the directed graph of the ASYN ports

Returns

Gnetworkx.DiGraph

Directed graph of pipelines

port_mapdict

Mapping between port_name and ADBase objects

get_asyn_port_dictionary()

Return port name : component map

Returns

port_mapdict

Mapping between port_name and ADBase objects

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_plugin_by_asyn_port(port_name)

Get the plugin which has the given asyn port name

Parameters

port_namestr

The port name to search for

Returns

retADBase or None

Either the requested plugin or None if not found

missing_plugins()

Find missing ports

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage(*args, **kwargs)

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

validate_asyn_ports()

Validate that all components of pipeline are known

Raises

RuntimeError

If there any input ports to known plugins where the source is not known to ophyd

visualize_asyn_digraph(ax=None, *args, **kwargs)

This generates a figure showing the current asyn port layout.

This method generates a plot showing all of the currently enabled Areadetector plugin asyn ports and their relationships. The current ports and relationships are found using self.get_asyn_digraph.

Parameters

ax: matplotlib axes

if None (default) then a new figure is created otherwise it is plotted on the specified axes.

*args, **kwargsnetworkx.draw_networkx args and kwargs.

For the allowed args and kwargs see the networkx.draw_networkx documentation

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.area_detector_support.HDF5FileWriterPlugin(*args, **kwargs)

Bases: FileStoreHDF5IterativeWrite, HDF5Plugin_V34

Add data acquisition methods to HDF5Plugin. Ophyd default file names.

File names are based on uuid.uuid4() strings.

• stage() - prepare device PVs befor data acquisition

• unstage() - restore device PVs after data acquisition

• generate_datum() - coordinate image storage metadata

Added in version 1.6.3.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of HDF5FileWriterPluginTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_ensure_absolute_under_root(path: Path) → Path

If the given path is not absolute, assume it is supposed to be under the root directory (self.reg_root) and append it. If it is absolute and but not under the root directory, raise an exception as this would break mounting. Otherwise return it as-is.

Note: The ancestor check is inclusive, root is considered to be under itself. This allows the write path to be ./

Args:

path: The path to check, can be absolute or relative

Raises:

ValueError: If the path is absolute and not a subdirectory (inclusive and recursive)

of root.

Returns:

Path: _description_

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_plugin_type_connected(connected, **kw)

Connection callback on the plugin type

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

property array_pixels

The total number of pixels, calculated from array_size

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe()

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration()

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

disable_on_stage()

when the plugin is staged, ensure that it is disabled.

a convenience method for adding `('enable', 0) to stage_sigs

property dotted_name: str

Return the dotted name

enable_on_stage()

when the plugin is staged, ensure that it is enabled.

a convenience method for adding (‘enable’, 1) to stage_sigs

ensure_blocking()

Ensure that if plugin is enabled after staging, callbacks block.

a convenience method for adding `('blocking_callbacks', 1) to stage_sigs

ensure_nonblocking()

Ensure that if plugin is enabled after staging, callbacks don’t block.

a convenience method for adding `('blocking_callbacks', 0) to stage_sigs

property event_types

Events that can be subscribed to via obj.subscribe

find_signal(text, use_re=False, case_sensitive=False, match_fcn=None, f=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Search through the signal docs on this detector for the string text

Parameters

textstr

Text to find

use_rebool, optional

Use regular expressions

case_sensitivebool, optional

Case sensitive search

match_fcncallable, optional

Function to call when matches are found Defaults to a function that prints matches to f

ffile-like, optional

File-like object that the default match function prints to (Defaults to sys.stdout)

property fs_root

DEPRECATED: The ‘root’ put into the Asset registry, use reg_root

generate_datum(key, timestamp, datum_kwargs)

Generate a uid and cache it with its key for later insertion.

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

get_asyn_digraph()

Get the directed graph of the ASYN ports

Returns

Gnetworkx.DiGraph

Directed graph of pipelines

port_mapdict

Mapping between port_name and ADBase objects

get_asyn_port_dictionary()

Return port name : component map

Returns

port_mapdict

Mapping between port_name and ADBase objects

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_plugin_by_asyn_port(port_name)

Get the plugin which has the given asyn port name

Parameters

port_namestr

The port name to search for

Returns

retADBase or None

Either the requested plugin or None if not found

make_filename()

Make a filename.

This is a hook so that the read and write paths can either be modified or created on disk prior to configuring the areaDetector plugin.

Returns

filenamestr

The start of the filename

read_pathstr

Path that ophyd can read from

write_pathstr

Path that the IOC can write to

missing_plugins()

Find missing ports

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read()

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration()

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property read_path_template

Returns write_path_template if read_path_template is not set

property reg_root

The ‘root’ put into the Asset Registry

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property source_plugin

The PluginBase object that is the asyn source for this plugin.

stage()

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage()

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

validate_asyn_ports()

Validate that all components of pipeline are known

Raises

RuntimeError

If there any input ports to known plugins where the source is not known to ophyd

visualize_asyn_digraph(ax=None, *args, **kwargs)

This generates a figure showing the current asyn port layout.

This method generates a plot showing all of the currently enabled Areadetector plugin asyn ports and their relationships. The current ports and relationships are found using self.get_asyn_digraph.

Parameters

ax: matplotlib axes

if None (default) then a new figure is created otherwise it is plotted on the specified axes.

*args, **kwargsnetworkx.draw_networkx args and kwargs.

For the allowed args and kwargs see the networkx.draw_networkx documentation

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

warmup()

A convenience method for ‘priming’ the plugin.

The plugin has to ‘see’ one acquisition before it is ready to capture. This sets the array size, etc.

class apstools.devices.area_detector_support.SimDetectorCam_V34(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: CamMixin_V34, SimDetectorCam

Adds triggering configuration and AcquireBusy support.

Added in version 1.6.3.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of SimDetectorCam_V34Tuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

find_signal(text, use_re=False, case_sensitive=False, match_fcn=None, f=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Search through the signal docs on this detector for the string text

Parameters

textstr

Text to find

use_rebool, optional

Use regular expressions

case_sensitivebool, optional

Case sensitive search

match_fcncallable, optional

Function to call when matches are found Defaults to a function that prints matches to f

ffile-like, optional

File-like object that the default match function prints to (Defaults to sys.stdout)

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

get_asyn_digraph()

Get the directed graph of the ASYN ports

Returns

Gnetworkx.DiGraph

Directed graph of pipelines

port_mapdict

Mapping between port_name and ADBase objects

get_asyn_port_dictionary()

Return port name : component map

Returns

port_mapdict

Mapping between port_name and ADBase objects

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

get_plugin_by_asyn_port(port_name)

Get the plugin which has the given asyn port name

Parameters

port_namestr

The port name to search for

Returns

retADBase or None

Either the requested plugin or None if not found

missing_plugins()

Find missing ports

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage(*args, **kwargs)

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

validate_asyn_ports()

Validate that all components of pipeline are known

Raises

RuntimeError

If there any input ports to known plugins where the source is not known to ophyd

visualize_asyn_digraph(ax=None, *args, **kwargs)

This generates a figure showing the current asyn port layout.

This method generates a plot showing all of the currently enabled Areadetector plugin asyn ports and their relationships. The current ports and relationships are found using self.get_asyn_digraph.

Parameters

ax: matplotlib axes

if None (default) then a new figure is created otherwise it is plotted on the specified axes.

*args, **kwargsnetworkx.draw_networkx args and kwargs.

For the allowed args and kwargs see the networkx.draw_networkx documentation

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.area_detector_support.SingleTrigger_V34(*args, **kwargs)

Bases: SingleTrigger

Variation of ophyd’s SingleTrigger mixin supporting AcquireBusy.

Added in version 1.6.3.

_acquire_changed(value=None, old_value=None, **kwargs)

This is called when the ‘acquire’ signal changes.

_status_type

alias of ADTriggerStatus

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

stage()

Prepare device settings before data acquisition.

trigger()

Trigger one acquisition.

unstage()

Restore device settings after data acquisition.

apstools.devices.area_detector_support.ensure_AD_plugin_primed(plugin, allow=False)

Ensure the AD file writing plugin is primed (warmed up), if allowed.

This function primes the plugin only if it is deemed necessary (for the use by ophyd).

PARAMETERS

plugin

obj : area detector plugin to be primed (such as detector.hdf1)

allow

bool : (default: False) Should the detector be primed? This keyword argument might be provided by a local configuration setting, controlled externally, such as from configuration file or other ophyd Signal.

EXAMPLE:

from apstools.devices import ensure_AD_plugin_primed
ensure_AD_plugin_primed(det.hdf1, True)

# or from a boolean python object

from local_configuration_settings import ok_to_prime
ensure_AD_plugin_primed(det.hdf1, allow=ok_to_prime)

An area detector file writing plugin is primed (as considered by ophyd) if the plugin’s image array parameters (size, number of bits, & color mode) match those configured in the cam. This agreement is required by the bluesky RunEngine (via area_detector_handlers) to generate a descriptor document for any ensuing image events.

Use with these area detector file writing plugins (maybe others):

• HDF5Plugin

• JPEGPlugin

• NetCDFPlugin

• TIFFPlugin

Even with lazy_open=1, ophyd (via area_detector_handlers) checks if the area detector file writing plugin has been primed.

See also

ophyd.areadetector.plugins.UnprimedPlugin: bluesky/ophyd

Added in version 1.6.16.

Axis Tuner

AxisTunerException	Exception during execution of AxisTunerBase subclass
AxisTunerMixin(*args, **kwargs)	Mixin class to provide tuning capabilities for an axis

exception apstools.devices.axis_tuner.AxisTunerException

Bases: ValueError

Exception during execution of AxisTunerBase subclass

add_note(object, /)

Exception.add_note(note) – add a note to the exception

with_traceback(object, /)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class apstools.devices.axis_tuner.AxisTunerMixin(*args, **kwargs)

Bases: DeviceMixinBase

Mixin class to provide tuning capabilities for an axis

See the TuneAxis() example in this jupyter notebook: BCDA-APS/apstools

HOOK METHODS

There are two hook methods (pre_tune_method(), and post_tune_method()) for callers to add additional plan parts, such as opening or closing shutters, setting detector parameters, or other actions.

Each hook method must accept a single argument: an axis object such as EpicsMotor or SynAxis, such as:

def my_pre_tune_hook(axis):
    yield from bps.mv(shutter, "open")
def my_post_tune_hook(axis):
    yield from bps.mv(shutter, "close")

class TunableSynAxis(AxisTunerMixin, SynAxis): pass

myaxis = TunableSynAxis(name="myaxis")
mydet = SynGauss('mydet', myaxis, 'myaxis', center=0.21, Imax=0.98e5, sigma=0.127)
myaxis.tuner = TuneAxis([mydet], myaxis)
myaxis.pre_tune_method = my_pre_tune_hook
myaxis.post_tune_method = my_post_tune_hook

def tune_myaxis():
    yield from myaxis.tune(md={"plan_name": "tune_myaxis"})

RE(tune_myaxis())

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_default_post_tune_method()

called after tune()

_default_pre_tune_method()

called before tune()

_device_tuple

alias of AxisTunerMixinTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

Ophyd definitions for digital delay and pulse generators.

class apstools.devices.delay.DG645Delay(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

An SRS DG-645 digial delay/pulse generator.

This device has four delayed outputs: AB, CD, EF, GH.

Configuration of the output parameters (e.g. amplitude, polarity) is done using components output_AB, etc. The individual delays for the start and end of the output pulse are configured using individual channels channel_A etc.

There is also a T0 output which is the reference pulses used for the remaining delayed outputs.

Changed in version 1.7.6: add components: burst_T0 & trigger_arm

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of DG645DelayTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

Mixin to add EPICS .DESC field

EpicsDescriptionMixin([prefix, kind, ...])

add a record's description field to a Device, such as EpicsMotor

class apstools.devices.description_mixin.EpicsDescriptionMixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: DeviceMixinBase

add a record’s description field to a Device, such as EpicsMotor

EXAMPLE:

from ophyd import EpicsMotor
from apstools.devices import EpicsDescriptionMixin

class MyEpicsMotor(EpicsDescriptionMixin, EpicsMotor): pass

m1 = MyEpicsMotor('xxx:m1', name='m1')
print(m1.desc.get())

more ideas:

class TunableSynAxis(AxisTunerMixin, SynAxis):
    '''synthetic axis that can be tuned'''

class TunableEpicsMotor(AxisTunerMixin, EpicsMotor):
    '''EpicsMotor that can be tuned'''

class EpicsMotorWithDescription(EpicsDescriptionMixin, EpicsMotor):
    '''EpicsMotor with description field'''

class EpicsMotorWithMore(
    EpicsDescriptionMixin,
    EpicsMotorDialMixin,
    EpicsMotorRawMixin,
    EpicsMotor
):
    '''
    EpicsMotor with more fields

    * description (``desc``)
    * soft motor limits (``soft_limit_hi``, ``soft_limit_lo``)
    * dial coordinates (``dial``)
    * raw coordinates (``raw``)
    '''

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of EpicsDescriptionMixinTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

DictionaryDevice

Create an ophyd Device defined by a dictionary so that a simple dictionary can be recorded in a bluesky data stream.

dict_device_factory([data])	Create a DictionaryDevice class using the supplied dictionary.
make_dict_device(obj[, name])	Make recordable DictionaryDevice instance from dictionary.

apstools.devices.dict_device_support.dict_device_factory(data={})

Create a DictionaryDevice class using the supplied dictionary.

apstools.devices.dict_device_support.make_dict_device(obj, name='ddev')

Make recordable DictionaryDevice instance from dictionary.

Added in version 1.6.4.

class apstools.devices.epics_scan_id_signal.EpicsScanIdSignal(read_pv, write_pv=None, *, put_complete=False, string=False, limits=False, name=None, **kwargs)

Bases: EpicsSignal

Use an EPICS PV as the source of the RunEngine’s scan_id.

Uses a writable EPICS integer PV (such as longout record).

EXAMPLE:

scan_id = EpicsScanIdDevice("ioc:scan_id:longout", name="scan_id")
# ...
RE = bluesky.RunEngine({}, scan_id_source=scan_id.cb_scan_id_source)

Added in version 1.6.3.

_ensure_connected(*pvs, timeout)

Ensure that pv is connected, with access/connection callbacks run

_fix_type(value)

Cast the given value according to the data type of this EpicsSignal

_get_metadata_from_kwargs(pvname, cl_metadata, *, require_timestamp=False)

Metadata from the control layer -> metadata for this Signal

_get_with_timeout(pv, timeout, connection_timeout, count, as_string, form, use_monitor)

Utility method implementing a retry loop for get and get_setpoint

Returns info from pv.read_with_metadata(…) or raises TimeoutError

_initial_metadata_callback(pvname, cl_metadata)

Control-layer callback: all initial metadata - control and status

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_metadata_changed(pvname, cl_metadata, *, from_monitor, update, require_timestamp=False)

Metadata for one PV has changed

_pv_access_callback(read_access, write_access, pv)

Control-layer callback: PV access rights have changed

_pv_connected(pvname, conn, pv)

Control-layer callback: PV has [dis]connected

_read_changed(value=None, **kwargs)

CA monitor callback indicating that the read value has changed

_repr_info()

Yields pairs of (key, value) to generate the Signal repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_metadata_callbacks()

Run SUB_META in the appropriate dispatcher thread

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_and_wait(value, timeout, **kwargs)

Overridable hook for subclasses to override set() functionality.

This will be called in a separate thread (_set_thread), but will not be called in parallel.

Parameters

valueany

The value

timeoutfloat, optional

Maximum time to wait for value to be successfully set, or None

_set_event_if_ready()

If connected and access rights received, set the “ready” event used in wait_for_connection.

_write_changed(value=None, timestamp=None, **kwargs)

CA monitor: callback indicating the setpoint PV value has changed

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

property alarm_severity

PV alarm severity

property alarm_status

PV status

property as_string

Attempt to cast the EPICS PV value to a string by default

cb_scan_id_source(*args, **kwargs)

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

• Get current scan_id from PV.

• Apply lower limit of zero.

• Increment.

• Set PV with new value.

• Return new value.

check_value(value)

Check if the value is within the setpoint PV’s control limits

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

property connected

Is the signal connected to its associated hardware, and ready to use?

describe()

Return the description as a dictionary

Returns

dict

Dictionary of name and formatted description string

describe_configuration()

Provide schema & meta-data for BlueskyInterface.read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect the Signal from the underlying control layer; destroy it

Clears all subscriptions on this Signal. Once destroyed, the signal may no longer be used.

property dotted_name: str

Return the dotted name

property enum_strs

List of strings if PV is an enum type

property event_types

Events that can be subscribed to via obj.subscribe

get(*, count=None, as_string=None, timeout=<object object>, connection_timeout=<object object>, form='time', use_monitor=None, **kwargs)

Get the readback value through an explicit call to EPICS.

Parameters

countint, optional

Explicitly limit count for array data

as_stringbool, optional

Get a string representation of the value, defaults to as_string from this signal, optional

as_numpybool

Use numpy array as the return type for array data.

timeoutfloat, optional

maximum time to wait for value to be received. (default = 0.5 + log10(count) seconds)

use_monitorbool, optional

to use value from latest monitor callback or to make an explicit CA call for the value. (default: True)

connection_timeoutfloat, optional

If not already connected, allow up to connection_timeout seconds for the connection to complete.

form{‘time’, ‘ctrl’}

PV form to request

get_setpoint(*, count=None, as_string=None, timeout=<object object>, connection_timeout=<object object>, use_monitor=None, form='time', **kwargs)

Get the setpoint value (if setpoint PV and readback PV differ)

Parameters

countint, optional

Explicitly limit count for array data

as_stringbool, optional

Get a string representation of the value, defaults to as_string from this signal, optional

as_numpybool

Use numpy array as the return type for array data.

timeoutfloat, optional

maximum time to wait for value to be received. (default = 0.5 + log10(count) seconds)

use_monitorbool, optional

to use value from latest monitor callback or to make an explicit CA call for the value. (default: True)

connection_timeoutfloat, optional

If not already connected, allow up to connection_timeout seconds for the connection to complete.

form{‘time’, ‘ctrl’}

PV form to request

property high_limit

The high, inclusive control limit for the Signal

property hints

Field hints for plotting

property limits

The PV control limits (low, high), such that low <= value <= high

property low_limit

The low, inclusive control limit for the Signal

property metadata

A copy of the metadata dictionary associated with the signal

property metadata_keys

Metadata keys that will be passed along on value subscriptions

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

property precision

The precision of the read PV, as reported by EPICS

put(value, force=False, connection_timeout=<object object>, callback=None, use_complete=None, timeout=<object object>, **kwargs)

Using channel access, set the write PV to value.

Keyword arguments are passed on to callbacks

Parameters

valueany

The value to set

forcebool, optional

Skip checking the value in Python first

connection_timeoutfloat, optional

If not already connected, allow up to connection_timeout seconds for the connection to complete.

use_completebool, optional

Override put completion settings

callbackcallable

Callback for when the put has completed

timeoutfloat, optional

Timeout before assuming that put has failed. (Only relevant if put completion is used.)

property put_complete

Use put completion when writing the value

property pvname

The readback PV name

read()

Put the status of the signal into a simple dictionary format for data acquisition

Returns

dict

property read_access

Can the signal be read?

read_configuration()

Dictionary mapping names to value dicts with keys: value, timestamp

property report

A report on the object.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(value, *, timeout=<object object>, settle_time=None)

Set the value of the Signal and return a Status object.

If put completion is used for this EpicsSignal, the status object will complete once EPICS reports the put has completed.

Otherwise the readback will be polled until equal to the set point (as in Signal.set)

Parameters

value : any timeout : float, optional

Maximum time to wait.

settle_time: float, optional

Delay after the set() has completed to indicate completion to the caller

Returns

st : Status

See Also

Signal.set

classmethod set_defaults(*, timeout=2.0, connection_timeout=1.0, write_timeout=None, auto_monitor=False)

Set class-wide defaults for EPICS CA communications

This may be called only before any instances of EpicsSignalBase are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> EpicsSignalBase.set_defaults(...)

will apply to EpicsSignalRO and EpicsSignal, which are both subclasses of EpicsSignalBase.

but

>>> EpicsSignal.set_defaults(...)

will not apply to EpicsSignalRO.

Parameters

auto_monitor: bool, optional

If True, update cached value from EPICS CA monitor callbacks. If False, request new value from EPICS each time get() is called.

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

timeout: float, optional

Total time budget (seconds) for reading, not including connection time.

write_timeout: float, optional

Time (seconds) allocated for writing, not including connection time. The write_timeout is very different than the connection and read timeouts above. It relates to how long an action takes to complete. Any default value we choose here is likely to cause problems—either by being too short and giving up too early on a lengthy action or being too long and delaying the report of a failure. The default, None, waits forever.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property setpoint

The setpoint PV value

property setpoint_alarm_severity

Setpoint PV alarm severity

property setpoint_alarm_status

Setpoint PV status

property setpoint_pvname

The setpoint PV name

property setpoint_ts

Timestamp of setpoint PV, according to EPICS

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timestamp

Timestamp of readback PV, according to EPICS

property tolerance

The tolerance of the write PV, as reported by EPICS

Can be overidden by the user at the EpicsSignal level.

Returns

tolerance : float or None Using the write PV’s precision:

If precision == 0, tolerance will be None If precision > 0, calculated to be 10**(-precision)

trigger()

Call that is used by bluesky prior to read()

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

property use_limits

Check value against limits prior to sending to EPICS

property value

The signal’s value

wait_for_connection(timeout=<object object>)

Wait for the underlying signals to initialize or connect

property write_access

Can the signal be written to?

Eurotherm 2216e Temperature Controller

The 2216e is a temperature controller from Eurotherm.

Eurotherm2216e([prefix, tolerance])

Eurotherm 2216e Temperature Controller

According to their website, the Eurotherm 2216e Temperature Controller [1] is obsolete. Please see [its] replacement EPC3016 [2] in our EPC3000 Series. [3]

[1]

https://www.eurothermcontrollers.com/eurotherm-2216e-series-controller-now-obsolete/

[2]

https://www.eurothermcontrollers.com/eurotherm-epc3016-1-16-din-process-and-temperature-controller/

[3]

https://www.eurothermcontrollers.com/epc3000-series

class apstools.devices.eurotherm_2216e.Eurotherm2216e(prefix='', *, tolerance=1, **kwargs)

Bases: PVPositionerSoftDoneWithStop

Eurotherm 2216e Temperature Controller

Added in version 1.6.0.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Eurotherm2216eTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(**kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_setup_move(position)

Move and do not wait until motion is complete (asynchronous)

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

cb_readback(*args, **kwargs)

Called when readback changes (EPICS CA monitor event) or on-demand.

Responsible for determining _if_ the positioner is done moving. Since soft positioners have no such direct indication, computes if the positioner is in position (if a move is active).

cb_sensor(*args, **kwargs)

units: Convert dC from sensor to C

cb_setpoint(*args, **kwargs)

Called when setpoint changes (EPICS CA monitor event).

When the setpoint is changed, force`` done=False``. For any move, done must transition to != done_value, then back to done_value.

Without this response, a small move (within tolerance) will not return. The cb_readback() method will compute done.

Since other code will also call this method, check the keys in kwargs and do not react to the “wrong” signature.

check_value(pos)

Check that the position is within the soft limits

cleanup()

Clear subscriptions on exit.

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property inposition

Do readback and setpoint (both from cache) agree within tolerance?

Returns:

inposition = |readback - setpoint| <= tolerance

move(position, wait=True, timeout=None, moved_cb=None)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

If a done PV is specified, it will be read directly to get the motion status. If not, it determined from the internal state of PVPositioner.

Returns

bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property position

The current position of the motor in its engineering units

Returns

position : any

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Hold the current readback when stop() is called and not inposition().

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

High Heat-Load Apertures

HHLApertureBase([prefix, kind, read_attrs, ...])	Base class for HHLAperture classes, 2-axis slit.
HHLAperture(prefix, pitch_motor, yaw_motor, ...)	High Heat Load Aperture.
HHLApertureACS(prefix, pitch_motor, ...)	High Heat Load Aperture for ACS motors.
HHLApertureWBA(prefix, pitch_motor, ...)	High Heat-Load Apertures White Beam

class apstools.devices.hhl_apertures.HHLAperture(prefix: str, pitch_motor: str, yaw_motor: str, horizontal_motor: str, diagonal_motor: str, *args, **kwargs)

Bases: HHLApertureBase

High Heat Load Aperture.

There are no independent parts to move, so each axis only has center and size.

Based on the Variable Mass Aperture Slits support in OPTICS module.

Similar to HHL_slits but for beamlines that dont follow 25ID nomenclature.

Parameters

prefix:

EPICS prefix required to communicate with HHL Slit IOC, ex: “9ida:SL1:”

pitch_motor:

The motor record PV controlling the real pitch motor, ex “9ida:CR9A1:m3”

yaw_motor:

The motor record PV controlling the real yaw motor, ex “9ida:CR9A1:m4”

horizontal_motor:

The motor record PV controlling the real horizontal motor, ex: “9ida:CR9A1:m1”

diagonal_motor:

The motor record PV controlling the real diagonal motor, ex: “9ida:CR9A1:m2”

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class SlitAxis(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of SlitAxisTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of HHLApertureTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.hhl_apertures.HHLApertureACS(prefix: str, pitch_motor: str, yaw_motor: str, horizontal_motor: str, diagonal_motor: str, *args, **kwargs)

Bases: HHLApertureBase

High Heat Load Aperture for ACS motors.

There are no independent parts to move, so each axis only has center and size.

Based on the Variable Mass Aperture Slits support in OPTICS module.

Similar to HHL_slits but for beamlines that dont follow 25ID nomenclature.

Parameters

prefix:

EPICS prefix required to communicate with HHL Slit IOC, ex: “9ida:SL1:”

pitch_motor:

The motor record PV controlling the real pitch motor, ex “9ida:CR9A1:m3”

yaw_motor:

The motor record PV controlling the real yaw motor, ex “9ida:CR9A1:m4”

horizontal_motor:

The motor record PV controlling the real horizontal motor, ex: “9ida:CR9A1:m1”

diagonal_motor:

The motor record PV controlling the real diagonal motor, ex: “9ida:CR9A1:m2”

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class SlitAxis(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of SlitAxisTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of HHLApertureACSTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.hhl_apertures.HHLApertureBase(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Base class for HHLAperture classes, 2-axis slit.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class SlitAxis(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of SlitAxisTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of HHLApertureBaseTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.hhl_apertures.HHLApertureWBA(prefix: str, pitch_motor: str, yaw_motor: str, horizontal_motor: str, diagonal_motor: str, *args, **kwargs)

Bases: HHLApertureACS

High Heat-Load Apertures White Beam

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class SlitAxis(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of SlitAxisTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of HHLApertureWBATuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.hhl_slits.HHLSlits(prefix: str, pitch_motor: str, yaw_motor: str, horizontal_motor: str, diagonal_motor: str, *args, **kwargs)

Bases: Device

High Heat Load Slit.

There are no independent parts to move, so each axis only has center and size.

Based on the 25-ID-A whitebeam slits.

The motor parameters listed below specify which motor records control which axis. The last piece of the PV prefix will be removed, and the motor number added on. For example, if the prefix is “255ida:slits:US:”, and the pitch motor is “255ida:slits:m3”, then pitch_motor should be “m3”.

Parameters

prefix:

EPICS prefix required to communicate with HHL Slit IOC, ex: “25ida:slits:US:”

pitch_motor:

The motor record suffix controlling the real pitch motor, ex “m3”

yaw_motor:

The motor record suffix controlling the real yaw motor, ex “m4”

horizontal_motor:

The motor record suffix controlling the real horizontal motor, ex: “m1”

diagonal_motor:

The motor record suffix controlling the real diagonal motor, ex: “m2”

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class SlitAxis(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of SlitAxisTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of HHLSlitsTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

Kohzu double-crystal monochromator

KohzuSeqCtl_Monochromator([prefix, kind, ...])

synApps Kohzu double-crystal monochromator sequence control program

class apstools.devices.kohzu_monochromator.KohzuSeqCtl_Monochromator(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

synApps Kohzu double-crystal monochromator sequence control program

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of KohzuSeqCtl_MonochromatorTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

calibrate_energy(value)

Calibrate the monochromator energy.

PARAMETERS

value: float

New energy for the current monochromator position.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.kohzu_monochromator.KohzuSoftPositioner(*args, **kwargs)

Bases: PVPositioner

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of KohzuSoftPositionerTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(**kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_setup_move(position)

Move and do not wait until motion is complete (asynchronous).

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

cb_done(*args, **kwargs)

Called when parent’s done signal changes (EPICS CA monitor event).

cb_setpoint(*args, **kwargs)

Called when setpoint changes (EPICS CA monitor event).

When the setpoint is changed, force done=False. For any move, done must transition to != done_value, then back to done_value. Next update will refresh value from parent device.

check_value(pos)

Check that the position is within the soft limits

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property inposition

Report (boolean) if positioner is done.

move(*args, **kwargs)

Reposition, with optional wait for completion.

property moving

Whether or not the motor is moving

If a done PV is specified, it will be read directly to get the motion status. If not, it determined from the internal state of PVPositioner.

Returns

bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property position

The current position of the motor in its engineering units

Returns

position : any

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

LabJack Data Acquisition (DAQ)

LabJackBase([prefix, kind, read_attrs, ...])

A labjack T-series data acquisition unit (DAQ).

Ophyd definitions for Labjack T-series data acquisition devices.

Supported devices, all inherit from LabJackBase:

• T4

• T7

• T7Pro

• T8

These devices are based on EPICS LabJack module R3.0. The EPICS IOC database changed significantly from R2 to R3 when the module was rewritten to use the LJM library.

See also

epics-modules/LabJack

There are definitions for the entire LabJack device, as well as the various inputs/outputs available on the LabJack T-series. Individual inputs can be used as part of other devices. Assuming analog input 5 is connected to a gas flow meter:

from ophyd import Component as Cpt
from apstools.devices import labjack

class MyBeamline(Device):
    ...
    gas_flow = Cpt(labjack.AnalogInput, "LabJackT7_1:Ai5")

class apstools.devices.labjack.AnalogInput(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Input

An analog input on a labjack device.

It is based on the synApps input record, but with LabJack specific signals added.

The .trigger() method will retrieve a fresh value using the .PROC field, though based on how EPICS support works, this is likely just the most recently polled value from the device. This can be useful if the .SCAN field is set to passive.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of AnalogInputTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.AnalogOutput(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Output

An analog output on a labjack device.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of AnalogOutputTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.DigitalIO(*args, ch_num, **kwargs)

Bases: Device

A digital input/output channel on the labjack.

Because of the how the records are structured in EPICS, the prefix must not include the “Bi{N}” portion of the prefix. Instead, the prefix should be prefix for the whole labjack (e.g. LabJackT7_1:), and the channel number should be provided using the ch_num property. So for the digital I/O with its input available at PV LabJackT7_1:Bi3, use:

dio3 = DigitalIO("LabJackT7_1:", name="dio3", ch_num=3)

This will create signals for the input (Bi3), output (Bo3), and direction (Bd3) records.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of DigitalIOTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.LabJackBase(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

A labjack T-series data acquisition unit (DAQ).

To use the individual components separately, consider using the corresponding devices in the list below.

This device contains signals for the following:

• device information (e.g. firmware version ,etc)

• analog outputs (AnalogInput)

• analog inputs* (AnalogOutput)

• digital input/output* (DigitalIO)

• waveform digitizer* (WaveformDigitizer)

• waveform generator (WaveformGenerator)

The number of inputs and digital outputs depends on the specific LabJack T-series device being used. Therefore, the base device LabJackBase does not implement these I/O signals. Instead, consider using one of the subclasses, like LabJackT4.

The .trigger() method does not do much. To retrieve fresh values for analog inputs where .SCAN is passive, you will need to trigger the individual inputs themselves.

The waveform generator and waveform digitizer are included for convenience. Reading all the analog/digital inputs and outputs can be done by calling the .read() method. However, it is unlikely that the goal is also to trigger the digitizer and generator during this read. For this reason, the digitizer and generator have kind=”omitted”. To trigger the digitizer or generator, they can be used as separate devices:

lj = LabJackT4(...)

# Read a waveform from the digitizer
lj.waveform_digitizer.trigger().wait()
lj.waveform_digitizer.read()

# Same thing for the waveform generator
lj.waveform_generator.trigger().wait()

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of LabJackBaseTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.LabJackT4(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: LabJackBase

A labjack T-series data acquisition unit (DAQ).

To use the individual components separately, consider using the corresponding devices in the list below.

This device contains signals for the following:

• device information (e.g. firmware version ,etc)

• analog outputs (AnalogInput)

• analog inputs* (AnalogOutput)

• digital input/output* (DigitalIO)

• waveform digitizer* (WaveformDigitizer)

• waveform generator (WaveformGenerator)

The number of inputs and digital outputs depends on the specific LabJack T-series device being used. Therefore, the base device LabJackBase does not implement these I/O signals. Instead, consider using one of the subclasses, like LabJackT4.

The .trigger() method does not do much. To retrieve fresh values for analog inputs where .SCAN is passive, you will need to trigger the individual inputs themselves.

The waveform generator and waveform digitizer are included for convenience. Reading all the analog/digital inputs and outputs can be done by calling the .read() method. However, it is unlikely that the goal is also to trigger the digitizer and generator during this read. For this reason, the digitizer and generator have kind=”omitted”. To trigger the digitizer or generator, they can be used as separate devices:

lj = LabJackT4(...)

# Read a waveform from the digitizer
lj.waveform_digitizer.trigger().wait()
lj.waveform_digitizer.read()

# Same thing for the waveform generator
lj.waveform_generator.trigger().wait()

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class WaveformDigitizer(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: WaveformDigitizer

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of WaveformDigitizerTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of LabJackT4Tuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.LabJackT7(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: LabJackBase

A labjack T-series data acquisition unit (DAQ).

To use the individual components separately, consider using the corresponding devices in the list below.

This device contains signals for the following:

• device information (e.g. firmware version ,etc)

• analog outputs (AnalogInput)

• analog inputs* (AnalogOutput)

• digital input/output* (DigitalIO)

• waveform digitizer* (WaveformDigitizer)

• waveform generator (WaveformGenerator)

The number of inputs and digital outputs depends on the specific LabJack T-series device being used. Therefore, the base device LabJackBase does not implement these I/O signals. Instead, consider using one of the subclasses, like LabJackT4.

The .trigger() method does not do much. To retrieve fresh values for analog inputs where .SCAN is passive, you will need to trigger the individual inputs themselves.

The waveform generator and waveform digitizer are included for convenience. Reading all the analog/digital inputs and outputs can be done by calling the .read() method. However, it is unlikely that the goal is also to trigger the digitizer and generator during this read. For this reason, the digitizer and generator have kind=”omitted”. To trigger the digitizer or generator, they can be used as separate devices:

lj = LabJackT4(...)

# Read a waveform from the digitizer
lj.waveform_digitizer.trigger().wait()
lj.waveform_digitizer.read()

# Same thing for the waveform generator
lj.waveform_generator.trigger().wait()

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class WaveformDigitizer(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: WaveformDigitizer

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of WaveformDigitizerTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of LabJackT7Tuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.LabJackT7Pro(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: LabJackBase

A labjack T-series data acquisition unit (DAQ).

To use the individual components separately, consider using the corresponding devices in the list below.

This device contains signals for the following:

• device information (e.g. firmware version ,etc)

• analog outputs (AnalogInput)

• analog inputs* (AnalogOutput)

• digital input/output* (DigitalIO)

• waveform digitizer* (WaveformDigitizer)

• waveform generator (WaveformGenerator)

The number of inputs and digital outputs depends on the specific LabJack T-series device being used. Therefore, the base device LabJackBase does not implement these I/O signals. Instead, consider using one of the subclasses, like LabJackT4.

The .trigger() method does not do much. To retrieve fresh values for analog inputs where .SCAN is passive, you will need to trigger the individual inputs themselves.

The waveform generator and waveform digitizer are included for convenience. Reading all the analog/digital inputs and outputs can be done by calling the .read() method. However, it is unlikely that the goal is also to trigger the digitizer and generator during this read. For this reason, the digitizer and generator have kind=”omitted”. To trigger the digitizer or generator, they can be used as separate devices:

lj = LabJackT4(...)

# Read a waveform from the digitizer
lj.waveform_digitizer.trigger().wait()
lj.waveform_digitizer.read()

# Same thing for the waveform generator
lj.waveform_generator.trigger().wait()

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class WaveformDigitizer(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: WaveformDigitizer

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of WaveformDigitizerTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of LabJackT7ProTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.LabJackT8(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: LabJackBase

A labjack T-series data acquisition unit (DAQ).

To use the individual components separately, consider using the corresponding devices in the list below.

This device contains signals for the following:

• device information (e.g. firmware version ,etc)

• analog outputs (AnalogInput)

• analog inputs* (AnalogOutput)

• digital input/output* (DigitalIO)

• waveform digitizer* (WaveformDigitizer)

• waveform generator (WaveformGenerator)

The number of inputs and digital outputs depends on the specific LabJack T-series device being used. Therefore, the base device LabJackBase does not implement these I/O signals. Instead, consider using one of the subclasses, like LabJackT4.

The .trigger() method does not do much. To retrieve fresh values for analog inputs where .SCAN is passive, you will need to trigger the individual inputs themselves.

The waveform generator and waveform digitizer are included for convenience. Reading all the analog/digital inputs and outputs can be done by calling the .read() method. However, it is unlikely that the goal is also to trigger the digitizer and generator during this read. For this reason, the digitizer and generator have kind=”omitted”. To trigger the digitizer or generator, they can be used as separate devices:

lj = LabJackT4(...)

# Read a waveform from the digitizer
lj.waveform_digitizer.trigger().wait()
lj.waveform_digitizer.read()

# Same thing for the waveform generator
lj.waveform_generator.trigger().wait()

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class WaveformDigitizer(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: WaveformDigitizer

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of WaveformDigitizerTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

_device_tuple

alias of LabJackT8Tuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.WaveformDigitizer(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

A feature of the Labjack devices that allows waveform capture.

By itself, this device does not include any actual data. It should be sub-classed for the individual T-series devices to use make_digitizer_waveforms() to produce waveform signals based on the number of inputs, using the ophyd DynamicDeviceComponent.

class T7Digitizer(WaveformDigitizer):
    waveforms = DCpt(make_digitizer_waveforms(14), kind="normal")

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of WaveformDigitizerTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.labjack.WaveformGenerator(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

A feature of the Labjack devices that generates output waveforms.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of WaveformGeneratorTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

apstools.devices.labjack.make_digitizer_waveforms(num_ais: int)

Create a dictionary with volt waveforms for the digitizer.

For use with an ophyd DynamicDeviceComponent.

Each analog input on the labjack could be included here, and probably should be unless there is a specific reason not to.

Parameters

num_ais

How many analog inputs to include for this Labjack device.

Lakeshore temperature controllers

LakeShore336Device([prefix, kind, ...])	LakeShore 336 temperature controller.
LakeShore340Device([prefix, kind, ...])	LakeShore 340 temperature controller

class apstools.devices.lakeshore_controllers.LS340_LoopBase(*args, loop_number=None, timeout=36000, **kwargs)

Bases: PVPositionerSoftDoneWithStop

Base settings for both sample and control loops.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of LS340_LoopBaseTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(**kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_setup_move(position)

Move and do not wait until motion is complete (asynchronous)

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

cb_readback(*args, **kwargs)

Called when readback changes (EPICS CA monitor event) or on-demand.

Responsible for determining _if_ the positioner is done moving. Since soft positioners have no such direct indication, computes if the positioner is in position (if a move is active).

cb_setpoint(*args, **kwargs)

Called when setpoint changes (EPICS CA monitor event).

When the setpoint is changed, force`` done=False``. For any move, done must transition to != done_value, then back to done_value.

Without this response, a small move (within tolerance) will not return. The cb_readback() method will compute done.

Since other code will also call this method, check the keys in kwargs and do not react to the “wrong” signature.

check_value(pos)

Check that the position is within the soft limits

cleanup()

Clear subscriptions on exit.

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property inposition

Do readback and setpoint (both from cache) agree within tolerance?

Returns:

inposition = |readback - setpoint| <= tolerance

move(position, wait=True, timeout=None, moved_cb=None)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

If a done PV is specified, it will be read directly to get the motion status. If not, it determined from the internal state of PVPositioner.

Returns

bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause()

Change setpoint to current position.

property position

The current position of the motor in its engineering units

Returns

position : any

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Hold the current readback when stop() is called and not inposition().

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.lakeshore_controllers.LS340_LoopControl(*args, loop_number=None, timeout=36000, **kwargs)

Bases: LS340_LoopBase

Control specific

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of LS340_LoopControlTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(**kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_setup_move(position)

Move and do not wait until motion is complete (asynchronous)

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

cb_readback(*args, **kwargs)

Called when readback changes (EPICS CA monitor event) or on-demand.

Responsible for determining _if_ the positioner is done moving. Since soft positioners have no such direct indication, computes if the positioner is in position (if a move is active).

cb_setpoint(*args, **kwargs)

Called when setpoint changes (EPICS CA monitor event).

When the setpoint is changed, force`` done=False``. For any move, done must transition to != done_value, then back to done_value.

Without this response, a small move (within tolerance) will not return. The cb_readback() method will compute done.

Since other code will also call this method, check the keys in kwargs and do not react to the “wrong” signature.

check_value(pos)

Check that the position is within the soft limits

cleanup()

Clear subscriptions on exit.

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property inposition

Do readback and setpoint (both from cache) agree within tolerance?

Returns:

inposition = |readback - setpoint| <= tolerance

move(position, wait=True, timeout=None, moved_cb=None)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

If a done PV is specified, it will be read directly to get the motion status. If not, it determined from the internal state of PVPositioner.

Returns

bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause()

Change setpoint to current position.

property position

The current position of the motor in its engineering units

Returns

position : any

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Hold the current readback when stop() is called and not inposition().

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.lakeshore_controllers.LS340_LoopSample(*args, loop_number=None, timeout=36000, **kwargs)

Bases: LS340_LoopBase

Sample specific

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of LS340_LoopSampleTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(**kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_setup_move(position)

Move and do not wait until motion is complete (asynchronous)

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

cb_readback(*args, **kwargs)

Called when readback changes (EPICS CA monitor event) or on-demand.

Responsible for determining _if_ the positioner is done moving. Since soft positioners have no such direct indication, computes if the positioner is in position (if a move is active).

cb_setpoint(*args, **kwargs)

Called when setpoint changes (EPICS CA monitor event).

When the setpoint is changed, force`` done=False``. For any move, done must transition to != done_value, then back to done_value.

Without this response, a small move (within tolerance) will not return. The cb_readback() method will compute done.

Since other code will also call this method, check the keys in kwargs and do not react to the “wrong” signature.

check_value(pos)

Check that the position is within the soft limits

cleanup()

Clear subscriptions on exit.

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property inposition

Do readback and setpoint (both from cache) agree within tolerance?

Returns:

inposition = |readback - setpoint| <= tolerance

move(position, wait=True, timeout=None, moved_cb=None)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

If a done PV is specified, it will be read directly to get the motion status. If not, it determined from the internal state of PVPositioner.

Returns

bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause()

Change setpoint to current position.

property position

The current position of the motor in its engineering units

Returns

position : any

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Hold the current readback when stop() is called and not inposition().

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.lakeshore_controllers.LakeShore336Device(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

LakeShore 336 temperature controller.

• loop 1: temperature positioner AND heater, PID, & ramp controls

• loop 2: temperature positioner AND heater, PID, & ramp controls

• loop 3: temperature positioner

• loop 4: temperature positioner

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of LakeShore336DeviceTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.lakeshore_controllers.LakeShore336_LoopControl(*args, loop_number=None, timeout=36000, **kwargs)

Bases: PVPositionerSoftDoneWithStop

LakeShore 336 temperature controller – with heater control.

The LakeShore 336 accepts up to two heaters.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of LakeShore336_LoopControlTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(**kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_setup_move(position)

Move and do not wait until motion is complete (asynchronous)

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

cb_readback(*args, **kwargs)

Called when readback changes (EPICS CA monitor event) or on-demand.

Responsible for determining _if_ the positioner is done moving. Since soft positioners have no such direct indication, computes if the positioner is in position (if a move is active).

cb_setpoint(*args, **kwargs)

Called when setpoint changes (EPICS CA monitor event).

When the setpoint is changed, force`` done=False``. For any move, done must transition to != done_value, then back to done_value.

Without this response, a small move (within tolerance) will not return. The cb_readback() method will compute done.

Since other code will also call this method, check the keys in kwargs and do not react to the “wrong” signature.

check_value(pos)

Check that the position is within the soft limits

cleanup()

Clear subscriptions on exit.

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property inposition

Do readback and setpoint (both from cache) agree within tolerance?

Returns:

inposition = |readback - setpoint| <= tolerance

move(position, wait=True, timeout=None, moved_cb=None)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

If a done PV is specified, it will be read directly to get the motion status. If not, it determined from the internal state of PVPositioner.

Returns

bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause()

Change setpoint to current position.

property position

The current position of the motor in its engineering units

Returns

position : any

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Hold the current readback when stop() is called and not inposition().

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.lakeshore_controllers.LakeShore336_LoopRO(*args, loop_number=None, **kwargs)

Bases: Device

LakeShore 336 temperature controller – Read-only loop (no heaters).

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of LakeShore336_LoopROTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.lakeshore_controllers.LakeShore340Device(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

LakeShore 340 temperature controller

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of LakeShore340DeviceTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

Linkam temperature controllers

Linkam_CI94_Device(*args, **kwargs)	Linkam model CI94 temperature controller
Linkam_T96_Device(*args, **kwargs)	Linkam model T96 temperature controller

class apstools.devices.linkam_controllers.Linkam_CI94_Device(*args, **kwargs)

Bases: Device

Linkam model CI94 temperature controller

EXAMPLE:

ci94 = Linkam_CI94_Device("IOC:ci94:", name="ci94")

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Linkam_CI94_DeviceTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.linkam_controllers.Linkam_T96_Device(*args, **kwargs)

Bases: Device

Linkam model T96 temperature controller

EXAMPLE:

tc1 = Linkam_T96("IOC:tc1:", name="tc1")

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Linkam_T96_DeviceTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.linkam_controllers.T96Temperature(prefix='', *, readback_pv='', setpoint_pv='', tolerance=None, use_target=False, **kwargs)

Bases: PVPositionerSoftDoneWithStop

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of T96TemperatureTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_done_moving(**kwargs)

Call when motion has completed. Runs SUB_DONE subscription.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_pos_changed(timestamp=None, value=None, **kwargs)

Callback from EPICS, indicating a change in position

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_set_position(value, **kwargs)

Set the current internal position, run the readback subscription

_setup_move(position)

Move and do not wait until motion is complete (asynchronous)

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

cb_readback(*args, **kwargs)

Called when readback changes (EPICS CA monitor event) or on-demand.

Responsible for determining _if_ the positioner is done moving. Since soft positioners have no such direct indication, computes if the positioner is in position (if a move is active).

cb_setpoint(*args, **kwargs)

Called when setpoint changes (EPICS CA monitor event).

When the setpoint is changed, force`` done=False``. For any move, done must transition to != done_value, then back to done_value.

Without this response, a small move (within tolerance) will not return. The cb_readback() method will compute done.

Since other code will also call this method, check the keys in kwargs and do not react to the “wrong” signature.

check_value(pos)

Check that the position is within the soft limits

cleanup()

Clear subscriptions on exit.

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property egu

The engineering units (EGU) for a position

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property inposition

Do readback and setpoint (both from cache) agree within tolerance?

Returns:

inposition = |readback - setpoint| <= tolerance

move(position, wait=True, timeout=None, moved_cb=None)

Move to a specified position, optionally waiting for motion to complete.

Parameters

position

Position to move to

moved_cbcallable

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

timeoutfloat, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

Returns

status : MoveStatus

Raises

TimeoutError

When motion takes longer than timeout

ValueError

On invalid positions

RuntimeError

If motion fails other than timing out

property moving

Whether or not the motor is moving

If a done PV is specified, it will be read directly to get the motion status. If not, it determined from the internal state of PVPositioner.

Returns

bool

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

property position

The current position of the motor in its engineering units

Returns

position : any

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

set(new_position: Any, *, timeout: float = None, moved_cb: Callable = None, wait: bool = False) → StatusBase

Set a value and return a Status object

Parameters

new_position : object

The input here is whatever the device requires (this should be over-ridden by the implementation. For example a motor would take a float, a shutter the strings {‘Open’, ‘Close’}, and a goineometer (h, k, l) tuples

timeout : float, optional

Maximum time to wait for the motion. If None, the default timeout for this positioner is used.

moved_cbcallable, optional

Deprecated

Call this callback when movement has finished. This callback must accept one keyword argument: ‘obj’ which will be set to this positioner instance.

waitbool, optional

Deprecated

If the method should block until the Status object reports it is done.

Defaults to False

Returns

statusStatusBase

Status object to indicate when the motion / set is done.

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

property settle_time

Amount of time to wait after moves to report status completion

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Hold the current readback when stop() is called and not inposition().

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

property timeout

Amount of time to wait before to considering a motion as failed

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

Measurement Computing TC-32 Thermocouple reader

The TC-32 thermocouple module [4] is part of the EPICS measComp [5] module. The module documentation [6] shows a GUI screen with basic display of the 32 thermocouple channels and the various digital (binary) I/O bits.

[4]

http://www.mccdaq.com/usb-ethernet-data-acquisition/temperature/usb-ethernet-24-bit-thermocouple-daq/TC-32.aspx

[5]

epics-modules/measComp

[6]

https://epics-modules.github.io/measComp/measCompMultiFunctionDoc.html#tc-32

Public class(es)

MeasCompTc32([prefix, kind, read_attrs, ...])

Measurement Computing TC-32 32-channel Thermocouple reader.

Internal class(es)

_MC_TC32_BaseClass(prefix, R, **kwargs)	Base class for I/O interface classes below.
Tc32BinaryInput(prefix, R, **kwargs)	Binary input channel of a MeasComp TC-32 device.
Tc32BinaryOutput(prefix, R, **kwargs)	Binary output channel of a MeasComp TC-32 device.
Tc32ThermocoupleChannel(prefix, R, **kwargs)	Thermocouple channel of a MeasComp TC-32 device.
_channels(dev_class, channel_list)	Create the channels for the I/O interface.

class apstools.devices.measComp_tc32_support.MeasCompTc32(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Measurement Computing TC-32 32-channel Thermocouple reader.

Added in version 1.6.14.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of MeasCompTc32Tuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.measComp_tc32_support.Tc32BinaryInput(prefix, R, **kwargs)

Bases: _MC_TC32_BaseClass

Binary input channel of a MeasComp TC-32 device.

• EPICS support: measComp/Db/measCompBinaryIn.template

• Users will not need to call this class directly.

Added in version 1.6.14.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Tc32BinaryInputTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.measComp_tc32_support.Tc32BinaryOutput(prefix, R, **kwargs)

Bases: _MC_TC32_BaseClass

Binary output channel of a MeasComp TC-32 device.

• EPICS support: measComp/Db/measCompBinaryOut.template

• Users will not need to call this class directly.

Added in version 1.6.14.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Tc32BinaryOutputTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.measComp_tc32_support.Tc32ThermocoupleChannel(prefix, R, **kwargs)

Bases: _MC_TC32_BaseClass

Thermocouple channel of a MeasComp TC-32 device.

• EPICS support: measComp/Db/measCompTemperatureIn.template

• Users will not need to call this class directly.

Added in version 1.6.14.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of Tc32ThermocoupleChannelTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.measComp_tc32_support._MC_TC32_BaseClass(prefix, R, **kwargs)

Bases: Device

Base class for I/O interface classes below.

Enables a common apstools.devices.measComp_tc32_support._channels() function to work for all the interfaces.

Users will not need to call this class directly.

Added in version 1.6.14.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of _MC_TC32_BaseClassTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

apstools.devices.measComp_tc32_support._channels(dev_class, channel_list)

Create the channels for the I/O interface.

Measurement Computing USB-CTR 8-Channel Scaler

Measurement Computing CTR High-Speed Counter/Timer Device

https://www.farnell.com/datasheets/3795358.pdf

There is more to this device than just the 8-channel scaler. Underlying support: epics-modules/measComp

The EPICS support provides for an optional scaler, compatible with the EPICS scaler record.

Public class(es)

MeasCompCtr([prefix, kind, read_attrs, ...])	Measurement Computing USB CTR08 high-speed counter/timer.
MeasCompCtrMcs([prefix, kind, read_attrs, ...])	Measurement Computing USB CTR08 Multi-Channel Scaler Controls.

Internal class(es)

MeasCompCtrDeviceCounterChannel([prefix, ...])	Measurement Computing USB CTR08 Pulse Counter channel.
MeasCompCtrDevicePulseGenChannel([prefix, ...])	Measurement Computing USB CTR08 Pulse Generator channel.

class apstools.devices.measComp_usb_ctr_support.MeasCompCtr(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Measurement Computing USB CTR08 high-speed counter/timer.

Added in version 1.6.18.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of MeasCompCtrTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.measComp_usb_ctr_support.MeasCompCtrDeviceCounterChannel(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Measurement Computing USB CTR08 Pulse Counter channel.

Added in version 1.6.18.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of MeasCompCtrDeviceCounterChannelTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.

Raises

RuntimeError

If called after EpicsSignalBase has been instantiated for the first time.

stage() → List[object]

Stage the device for data collection.

This method is expected to put the device into a state where repeated calls to trigger() and read() will ‘do the right thing’.

Staging not idempotent and should raise RedundantStaging if staged twice without an intermediate unstage().

This method should be as fast as is feasible as it does not return a status object.

The return value of this is a list of all of the (sub) devices stage, including it’s self. This is used to ensure devices are not staged twice by the RunEngine.

This is an optional method, if the device does not need staging behavior it should not implement stage (or unstage).

Returns

deviceslist

list including self and all child devices staged

stop(*, success=False)

Stop the Device and all (instantiated) subdevices

subscribe(callback, event_type=None, run=True)

Subscribe to events this event_type generates.

The callback will be called as cb(*args, **kwargs) with the values passed to _run_subs with the following additional keys:

sub_type : the string value of the event_type obj : the host object, added if ‘obj’ not already in kwargs

if the key ‘timestamp’ is in kwargs _and_ is None, then it will be replaced with the current time before running the callback.

The *args, **kwargs passed to _run_subs will be cached as shallow copies, be aware of passing in mutable data.

Warning

If the callback raises any exceptions when run they will be silently ignored.

Parameters

callbackcallable

A callable function (that takes kwargs) to be run when the event is generated. The expected signature is

def cb(*args, obj: OphydObject, sub_type: str, **kwargs) -> None:

The exact args/kwargs passed are whatever are passed to _run_subs

event_typestr, optional

The name of the event to subscribe to (if None, defaults to the default sub for the instance - obj._default_sub)

This maps to the sub_type kwargs in _run_subs

runbool, optional

Run the callback now

See Also

clear_sub, _run_subs

Returns

cidint

id of callback, can be passed to unsubscribe to remove the callback

trigger() → StatusBase

Trigger the device and return status object.

This method is responsible for implementing ‘trigger’ or ‘acquire’ functionality of this device.

If there is an appreciable time between triggering the device and it being able to be read (via the read() method) then this method is also responsible for arranging that the StatusBase object returned by this method is notified when the device is ready to be read.

If there is no delay between triggering and being readable, then this method must return a StatusBase object which is already completed.

Returns

statusStatusBase

StatusBase object which will be marked as complete when the device is ready to be read.

unstage() → List[object]

Unstage the device.

This method returns the device to the state it was prior to the last stage call.

This method should be as fast as feasible as it does not return a status object.

This method must be idempotent, multiple calls (without a new call to ‘stage’) have no effect.

Returns

deviceslist

list including self and all child devices unstaged

unsubscribe(cid)

Remove a subscription

See also subscribe(), clear_sub()

Parameters

cidint

token return by subscribe()

wait_for_connection(all_signals=False, timeout=<object object>)

Wait for signals to connect

Parameters

all_signalsbool, optional

Wait for all signals to connect (including lazy ones)

timeoutfloat or None

Overall timeout

classmethod walk_components()

Walk all components in the Device hierarchy

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_components was called on.

walk_signals(*, include_lazy=False)

Walk all signals in the Device hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Parameters

include_lazybool, optional

Include not-yet-instantiated lazy signals

Yields

ComponentWalk

Where ancestors is all ancestors of the signal, including the top-level device walk_signals was called on.

classmethod walk_subdevice_classes()

Walk all sub-Devices classes in the Device hierarchy

Yields

(dotted_name, subdevice_class)

walk_subdevices(*, include_lazy=False)

Walk all sub-Devices in the hierarchy

EXPERIMENTAL: This method is experimental, and there are tentative plans to change its API in a way that may not be backward-compatible.

Yields

(dotted_name, subdevice_instance)

class apstools.devices.measComp_usb_ctr_support.MeasCompCtrDevicePulseGenChannel(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

Measurement Computing USB CTR08 Pulse Generator channel.

Added in version 1.6.18.

class OphydAttrList(device, kind, remove_kind, recurse_key)

Bases: MutableSequence

list proxy to migrate away from Device.read_attrs and Device.config_attrs

append(value)

S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(index, object)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

_device_tuple

alias of MeasCompCtrDevicePulseGenChannelTuple

_done_acquiring(**kwargs)

Call when acquisition has completed.

_get_components_of_kind(kind)

Get names of components that match a specific kind

_get_kind(name)

Get a Kind for a given Component

If the Component is instantiated, it will be retrieved directly from that object.

If the Component is lazy and not yet instantiated, the default value as specified by the Component class will be used. This is stashed away in _component_kinds.

classmethod _initialize_device()

Initializes the Device and all of its Components

Initializes the following attributes from the Components::

• _sig_attrs - dict of attribute name to Component

• component_names - a list of attribute names used for components

• _device_tuple - An auto-generated namedtuple based on all existing Components in the Device

• _sub_devices - a list of attributes which hold a Device

• _required_for_connection - a dictionary of object-to-description for additional things that block this from being reported as connected

_instantiate_component(attr)

Create a Component specifically for this Device

classmethod _mark_as_instantiated()

Update state indicated that this class has been instantiated.

_repr_info()

Yields pairs of (key, value) to generate the object repr

_reset_sub(event_type)

Remove all subscriptions in an event type

_run_subs(*args, sub_type, **kwargs)

Run a set of subscription callbacks

Only the kwarg sub_type is required, indicating the type of callback to perform. All other positional arguments and kwargs are passed directly to the callback function.

The host object will be injected into kwargs as ‘obj’ unless that key already exists.

If the timestamp is None, then it will be replaced by the current time.

No exceptions are raised if the callback functions fail.

_set_kind(name, kind)

Set the Kind for a given Component

_summary()

Return a string summarizing the structure of the Device.

classmethod add_instantiation_callback(callback, fail_if_late=False)

Register a callback which will receive each OphydObject instance.

Parameters

callbackcallable

Expected signature: f(ophydobj_instance)

fail_if_lateboolean

If True, verify that OphydObj has not yet been instantiated and raise RuntimeError if it has, as a way of verify that no instances will be “missed” by this registry. False by default.

check_value(value, **kwargs)

Check if the value is valid for this object

This function does no normalization, but may raise if the value is invalid.

Raises

ValueError

clear_sub(cb, event_type=None)

Remove a subscription, given the original callback function

See also subscribe(), unsubscribe()

Parameters

cbcallable

The callback

event_typestr, optional

The event to unsubscribe from (if None, removes it from all event types)

configure(d: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]

Configure the device for something during a run

This default implementation allows the user to change any of the configuration_attrs. Subclasses might override this to perform additional input validation, cleanup, etc.

Parameters

ddict

The configuration dictionary. To specify the order that the changes should be made, use an OrderedDict.

Returns

(old, new) tuple of dictionaries Where old and new are pre- and post-configure configuration states.

property connected

If the device is connected.

Subclasses should override this

describe() → OrderedDictType[str, Dict[str, Any]]

Provide schema and meta-data for read().

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

describe_configuration() → OrderedDictType[str, Dict[str, Any]]

Provide schema & meta-data for read_configuration()

This keys in the OrderedDict this method returns must match the keys in the OrderedDict return by read().

This provides schema related information, (ex shape, dtype), the source (ex PV name), and if available, units, limits, precision etc.

Returns

data_keysOrderedDict

The keys must be strings and the values must be dict-like with the event_model.event_descriptor.data_key schema.

destroy()

Disconnect and destroy all signals on the Device

property dotted_name: str

Return the dotted name

property event_types

Events that can be subscribed to via obj.subscribe

get(**kwargs)

Get the value of all components in the device

Keyword arguments are passed onto each signal.get(). Components beginning with an underscore will not be included.

classmethod get_device_tuple()

The device tuple type associated with an Device class

This is a tuple representing the full state of all components and dynamic device sub-components.

get_instantiated_signals(*, attr_prefix=None)

Yields all of the instantiated signals in a device hierarchy

Parameters

attr_prefixstring, optional

The attribute prefix. If None, defaults to self.name

Yields

(fully_qualified_attribute_name, signal_instance)

property name

name of the device

property parent

The parent of the ophyd object.

If at the top of its hierarchy, parent will be None

pause() → None

Attempt to ‘pause’ the device.

This is called when ever the RunEngine is interrupted.

A device may have internal state that means plans can not safely be re-wound. This method may: put the device in a ‘paused’ state and/or raise NoReplayAllowed to indicate that the plan can not be rewound.

Raises

bluesky.run_engine.NoReplayAllowed

put(dev_t, **kwargs)

Put a value to all components of the device

Keyword arguments are passed onto each signal.put()

Parameters

dev_tDeviceTuple or tuple

The device tuple with the value(s) to put (see get_device_tuple)

read() → OrderedDictType[str, Dict[str, Any]]

Read data from the device.

This method is expected to be as instantaneous as possible, with any substantial acquisition time taken care of in trigger().

The OrderedDict returned by this method must have identical keys (in the same order) as the OrderedDict returned by describe().

By convention, the first key in the return is the ‘primary’ key and maybe used by heuristics in bluesky.

The values in the ordered dictionary must be dict (-likes) with the keys {'value', 'timestamp'}. The 'value' may have any type, the timestamp must be a float UNIX epoch timestamp in UTC.

Returns

dataOrderedDict

The keys must be strings and the values must be dict-like with the keys {'value', 'timestamp'}

read_configuration() → OrderedDictType[str, Dict[str, Any]]

Dictionary mapping names to value dicts with keys: value, timestamp

To control which fields are included, change the Component kinds on the device, or modify the configuration_attrs list.

property report

A report on the object.

resume() → None

Resume a device from a ‘paused’ state.

This is called by the bluesky.run_engine.RunEngine when it resumes from an interruption and is responsible for ensuring that the device is ready to take data again.

property root

Walk parents to find ultimate ancestor (parent’s parent…).

classmethod set_defaults(*, connection_timeout=10.0)

Set class-wide defaults for device communications

This may be called only before any instances of Device are made.

This setting applies to the class it is called on and all its subclasses. For example,

>>> Device.set_defaults(...)

will apply to any Device subclass.

Parameters

connection_timeout: float, optional

Time (seconds) allocated for establishing a connection with the IOC.