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 the APS Data Management system or a local file.
ApsMachineParametersDevice([prefix, kind, ...])	Common operational parameters of the APS of general interest.
ApsPssShutter(prefix, *args[, close_pv, open_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, **kwargs)	Shutter, implemented with an EPICS motor moved between two positions
EpicsOnOffShutter(*args, **kwargs)	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, open_pv])	APS PSS shutter
ApsPssShutterWithStatus(prefix, state_pv, ...)	APS PSS shutter with separate status PV
EpicsMotorShutter(*args, **kwargs)	Shutter, implemented with an EPICS motor moved between two positions
EpicsOnOffShutter(*args, **kwargs)	Shutter using a single EPICS PV moved between two positions
OneSignalShutter(*args, **kwargs)	Shutter Device using one Signal for open and close.
ShutterBase(*args, **kwargs)	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 the APS Data Management system or a local file.

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

Bases: SynSignalRO

Get the APS cycle name from the APS Data Management system or a local file.

This signal is read-only.

_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)
version_hpmu	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.

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.

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.MeasCompCtrMcs(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 Multi-Channel Scaler Controls.

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 MeasCompCtrMcsTuple

_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)

Base class for Device Mixins

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

Base class for apstools Device mixin classes

class apstools.devices.mixin_base.DeviceMixinBase(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 apstools Device mixin classes

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 DeviceMixinBaseTuple

_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)

Motor Bundle Factory

Factory for creating bundles with any number of positioners.

• Use mb_creator() to quickly group motors (axes) into a single ophyd device.

• Supports different axes types including EpicsMotor, simulated (SoftPositioner), and other positioners.

• Advanced axis configuration is possible via per-axis dictionaries.

• Custom base classes, class names, labels, and factories are supported.

axis_component(parms)	Return a Component with 'parms for this axis.
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.

Quick Example

xy_stage = mb_creator(
    prefix="IOC:",
    motors={"x": "m21", "y": "m22"},
    name="xy_stage",
)

See also

• Quick Start

• How to use ‘mb_creator()’

apstools.devices.motor_factory.axis_component(parms: None | str | Mapping[str, Any]) → Component

Return a Component with ‘parms for this axis.

PARAMETERS

parms:

Parameters for the axis, either as a string (prefix) or a mapping.

RETURNS

Component:

An ophyd Component for the axis.

apstools.devices.motor_factory.mb_class_factory(motors: ~collections.abc.Sequence[str] | ~collections.abc.Mapping[str, str | ~collections.abc.Mapping | None] | None = None, class_bases: ~collections.abc.Sequence[str | ~typing.Type] = [<class 'ophyd.epics_motor.MotorBundle'>], class_name: str = 'MB_Device') → Type[Device]

Create a custom MotorBundle (or as specified in ‘class_bases’) class.

PARAMETERS

motors:

Dictionary or list of motors to include in the bundle.

class_bases:

List of base classes (as Python objects or import strings).

class_name:

Name of the generated class.

RETURNS:

The dynamically-created class (a subclass of ophyd.Device).

Added in version 1.7.4.

apstools.devices.motor_factory.mb_creator(*, prefix: str = '', name: str | None = None, motors: ~collections.abc.Sequence[str] | ~collections.abc.Mapping[str, str | ~collections.abc.Mapping | None] = {}, class_bases: ~collections.abc.Sequence[~typing.Type] = [<class 'ophyd.epics_motor.MotorBundle'>], class_name: str = 'MB_Device', labels: ~collections.abc.Sequence[str] = ['motor_device']) → Device

Create MotorBundle with any number of motors.

PARAMETERS

prefix str:

The prefix for the device.

name str:

The name of the device (required).

motors list | dict:

List or dictionary of motor specifications to include in the bundle.

class_bases:

List of base classes for the bundle.

class_name str:

Name of the generated class.

labels list:

List of labels for the device.

RETURNS

An instance of the generated MotorBundle (or other, as directed) class.

Added in version 1.7.4.

Mixin classes for Motor Devices

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

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

Bases: DeviceMixinBase

add motor record’s dial coordinate fields to Device

EXAMPLE:

from ophyd import EpicsMotor
from apstools.devices import EpicsMotorDialMixin

class myEpicsMotor(EpicsMotorDialMixin, EpicsMotor): pass
m1 = myEpicsMotor('xxx:m1', name='m1')
print(m1.dial.read())

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 EpicsMotorDialMixinTuple

_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.motor_mixins.EpicsMotorEnableMixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: DeviceMixinBase

mixin providing access to motor enable/disable

EXAMPLE:

from ophyd import EpicsMotor
from apstools.devices import EpicsMotorEnableMixin

class MyEpicsMotor(EpicsMotorEnableMixin, EpicsMotor): ...

m1 = MyEpicsMotor('xxx:m1', name='m1')
print(m1.enabled)

In a bluesky plan:

yield from bps.mv(m1.enable_disable, m1.MOTOR_DISABLE)
# ... other activities
yield from bps.mv(m1.enable_disable, m1.MOTOR_ENABLE)

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 EpicsMotorEnableMixinTuple

_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

disable_motor()

BLOCKING call to disable motor axis

property dotted_name: str

Return the dotted name

enable_motor()

BLOCKING call to enable motor axis

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.motor_mixins.EpicsMotorLimitsMixin(*args, **kwargs)

Bases: DeviceMixinBase

Deprecated Add motor record HLM & LLM fields & compatibility get_lim() and set_lim()

Caution

Deprecated. Now part of ‘ophyd.EpicsMotor’ class. Will be removed in a future release of apstools.

Deprecated since version 1.7.1: Now part of ophyd.EpicsMotor

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 EpicsMotorLimitsMixinTuple

_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)

get_lim(flag)

Returns the user limit of motor

• flag > 0: returns high limit

• flag < 0: returns low limit

• flag == 0: returns None

Similar with SPEC command

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.

set_lim(low, high)

Sets the low and high 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)

Similar with SPEC command

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.motor_mixins.EpicsMotorRawMixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: DeviceMixinBase

add motor record’s raw coordinate fields to Device

EXAMPLE:

from ophyd import EpicsMotor
from apstools.devices import EpicsMotorRawMixin

class myEpicsMotor(EpicsMotorRawMixin, EpicsMotor): pass
m1 = myEpicsMotor('xxx:m1', name='m1')
print(m1.raw.read())

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 EpicsMotorRawMixinTuple

_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.motor_mixins.EpicsMotorResolutionMixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: DeviceMixinBase

Add motor record’s resolution fields to motor.

Usually, a facility will not provide such high-level access to calibration parameters since these are associated with fixed parameters of hardware. For simulators, it is convenient to provide access so that default settings (typically low-resolution) from the IOC can be changed as part of the device setup in bluesky.

EXAMPLE:

from ophyd import EpicsMotor
from apstools.devices import EpicsMotorResolutionMixin

class myEpicsMotor(EpicsMotorResolutionMixin, EpicsMotor): pass
m1 = myEpicsMotor('xxx:m1', name='m1')
print(f"resolution={m1.resolution.read()}")
print(f"steps_per_rev={m1.steps_per_rev.read()}")
print(f"units_per_rev={m1.units_per_rev.read()}")

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 EpicsMotorResolutionMixinTuple

_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.motor_mixins.EpicsMotorServoMixin(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: DeviceMixinBase

add motor record’s servo loop controls to Device

EXAMPLE:

from ophyd import EpicsMotor
from apstools.devices import EpicsMotorServoMixin

class myEpicsMotor(EpicsMotorServoMixin, EpicsMotor): pass
m1 = myEpicsMotor('xxx:m1', name='m1')
print(m1.servo.read())

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 EpicsMotorServoMixinTuple

_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)

PVPositioner that computes done as a soft signal.

PVPositionerSoftDone([prefix, readback_pv, ...])	PVPositioner that computes done as a soft signal.
PVPositionerSoftDoneWithStop([prefix, ...])	PVPositionerSoftDone with stop() and inposition.

class apstools.devices.positioner_soft_done.PVPositionerSoftDone(prefix='', *, readback_pv='', setpoint_pv='', tolerance=None, use_target=False, **kwargs)

Bases: PVPositioner

PVPositioner that computes done as a soft signal.

PARAMETERS

prefixstr, optional

The device prefix used for all sub-positioners. This is optional as it may be desirable to specify full PV names for PVPositioners.

readback_pvstr, optional

PV prefix of the readback signal. Disregarded if readback attribute is created.

setpoint_pvstr, optional

PV prefix of the setpoint signal. Disregarded if setpoint attribute is created.

tolerancefloat, optional

Motion tolerance. The motion is considered done when:

abs(readback-setpoint) <= tolerance

Defaults to 10^(-1*precision), where precision = setpoint.precision.

use_targetbool

True when this object update the target Component directly. Use False if the target Component will be updated externally, such as by the controller when target is an EpicsSignal. Defaults to False.

kwargs :

Passed to ophyd.PVPositioner

ATTRIBUTES

setpointSignal

The setpoint (request) signal

readbackSignal or None

The readback PV (e.g., encoder position PV)

actuateSignal or None

The actuation PV to set when movement is requested

actuate_valueany, optional

The actuation value, sent to the actuate signal when motion is requested

stop_signalSignal or None

The stop PV to set when motion should be stopped

stop_valueany, optional

The value sent to stop_signal when a stop is requested

targetSignal

The target value of a move request.

Override (in subclass) with EpicsSignal to connect with a PV.

In some controllers (such as temperature controllers), the setpoint may be changed incrementally towards this target value (such as a ramp or controlled trajectory). In such cases, the target will be final value while setpoint will be the current desired position.

Otherwise, both setpoint and target will be set to the same value.

Added in version 1.5.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 PVPositionerSoftDoneTuple

_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)

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.positioner_soft_done.PVPositionerSoftDoneWithStop(prefix='', *, readback_pv='', setpoint_pv='', tolerance=None, use_target=False, **kwargs)

Bases: PVPositionerSoftDone

PVPositionerSoftDone with stop() and inposition.

The stop() method sets the setpoint to the immediate readback value (only when inposition is True). This stops the positioner at the current position.

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 PVPositionerSoftDoneWithStopTuple

_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)

Generalized ophyd Device base class for preamplifiers.

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

Generalized interface (base class) for preamplifiers.

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

Bases: Device

Generalized interface (base class) for preamplifiers.

All subclasses of PreamplifierBaseDevice must define how to update the gain with the correct value from the amplifier. An example is SRS570_PreAmplifier.

See:

BCDA-APS/apstools#544

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 PreamplifierBaseDeviceTuple

_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)

PTC10 Programmable Temperature Controller

The PTC10 is a programmable temperature controller from SRS (Stanford Research Systems). The PTC10 is a modular system consisting of a base unit and provision for addition of add-on boards.

A single, complete ophyd.Device subclass will not describe all variations that could be installed. But the add-on boards each allow standardization. Each installation must build a custom class that matches their hardware configuration. The APS USAXS instrument has created a custom class based on the ophyd.PVPositioner to use their PTC10 as a temperature positioner.

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.

see:

https://www.thinksrs.com/products/ptc10.html

EXAMPLE:

from ophyd import PVPositioner

class MyPTC10(PTC10PositionerMixin, PVPositioner):
    readback = Component(EpicsSignalRO, "2A:temperature", kind="hinted")
    setpoint = Component(EpicsSignalWithRBV, "5A:setPoint", kind="hinted")

    rtd = Component(PTC10RtdChannel, "3A:")
    pid = Component(PTC10AioChannel, "5A:")

ptc10 = MyPTC10("IOC_PREFIX:ptc10:", name="ptc10")
ptc10.report_dmov_changes.put(True)  # a diagnostic
ptc10.tolerance.put(1.0)  # done when |readback-setpoint|<=tolerance

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

Bases: Device

SRS PTC10 AIO module

Added in version 1.5.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 PTC10AioChannelTuple

_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.ptc10_controller.PTC10PositionerMixin(*args, **kwargs)

Bases: Device

Mixin so SRS PTC10 can be used as a (temperature) positioner.

cb_readback(*args, **kwargs)	Called when readback changes (EPICS CA monitor event).
cb_setpoint(*args, **kwargs)	Called when setpoint changes (EPICS CA monitor event).
inposition	Report (boolean) if positioner is done.
stop(*[, success])	Hold the current readback when the stop() method is called and not done.

Added in version 1.5.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 PTC10PositionerMixinTuple

_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.

cb_readback(*args, **kwargs)

Called when readback 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 change to != done_value, then change back to done_value (True). Without this response, a small move (within tolerance) will not return. Next update of readback will compute self.done.

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 inposition

Report (boolean) if positioner is done.

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)

Hold the current readback when the stop() method is called and not done.

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.ptc10_controller.PTC10RtdChannel(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

SRS PTC10 RTD module channel

Added in version 1.5.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 PTC10RtdChannelTuple

_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.ptc10_controller.PTC10TcChannel(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

SRS PTC10 Tc (thermocouple) module channel

Added in version 1.5.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 PTC10TcChannelTuple

_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)

Scaler support

use_EPICS_scaler_channels(scaler)

configure scaler for only the channels with names assigned in EPICS

apstools.devices.scaler_support.use_EPICS_scaler_channels(scaler)

configure scaler for only the channels with names assigned in EPICS

Note: For ScalerCH, use scaler.select_channels(None) instead of this code. (Applies only to ophyd.scaler.ScalerCH in releases after 2019-02-27.)

Shutters

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

class apstools.devices.shutters.ApsPssShutter(prefix, *args, close_pv=None, open_pv=None, **kwargs)

Bases: ShutterBase

APS PSS shutter

• APS PSS shutters have separate bit PVs for open and close

• set either bit, the shutter moves, and the bit resets a short time later

• no indication that the shutter has actually moved from the bits (see ApsPssShutterWithStatus() for alternative)

Since there is no direct indication that a shutter has moved, the state property will always return unknown and the isOpen and isClosed properties will always return False.

A consequence of the unknown state is that the shutter will always be commanded to move (and wait the delay_s time), even if it is already at that position. This device could keep track of the last commanded position, but that is not guaranteed to be true since the shutter could be moved from other software.

The default delay_s has been set at 1.2 s to allow for shutter motion. Change this as desired. Advise if this default should be changed.

PARAMETERS

prefix

str : EPICS PV prefix

name

str : (kwarg, required) object’s canonical name

close_pv

str : (kwarg, optional) Name of EPICS PV to close the shutter. If None, defaults to "{prefix}Close".

open_pv

str : (kwarg, optional) Name of EPICS PV to open the shutter. If None, defaults to "{prefix}Open".

EXAMPLE:

shutter_a = ApsPssShutter("2bma:A_shutter:", name="shutter")
shutter_a.wait_for_connection()

shutter_a.open()
shutter_a.close()

shutter_a.set("open")
shutter_a.set("close")

When using the shutter in a plan, be sure to use yield from, such as:

def in_a_plan(shutter):
    yield from abs_set(shutter, "open", wait=True)
    # do something
    yield from abs_set(shutter, "close", wait=True)

RE(in_a_plan(shutter_a))

The strings accepted by set() are defined in two lists: valid_open_values and valid_close_values. These lists are treated (internally to set()) as lower case strings.

Example, add “o” & “x” as aliases for “open” & “close”:

shutter_a.addOpenValue(“o”) shutter_a.addCloseValue(“x”) shutter_a.set(“o”) shutter_a.set(“x”)

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 ApsPssShutterTuple

_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.

addCloseValue(text)

a synonym to close the shutter, use with set()

addOpenValue(text)

a synonym to open the shutter, use with set()

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

property choices

return list of acceptable choices for set()

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)

close(timeout=10)

request the shutter to close (timeout is ignored)

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)

inPosition(target)

is the shutter at the target position?

property isClosed

is the shutter closed?

property isOpen

is the shutter open?

lowerCaseString(value)

ensure any given value is a lower-case string

property name

name of the device

open(timeout=10)

request the shutter to open (timeout is ignored)

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…).

set(value, **kwargs)

plan: request the shutter to open or close

PARAMETERS

value

str : any from self.choices (typically “open” or “close”)

kwargs

dict : ignored at this time

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

property state

is shutter “open”, “close”, or “unknown”?

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()

validTarget(target, should_raise=True)

return whether (or not) target value is acceptable for self.set()

raise ValueError if not acceptable (default)

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.shutters.ApsPssShutterWithStatus(prefix, state_pv, *args, **kwargs)

Bases: ApsPssShutter

APS PSS shutter with separate status PV

• APS PSS shutters have separate bit PVs for open and close

• set either bit, the shutter moves, and the bit resets a short time later

• a separate status PV tells if the shutter is open or closed (see ApsPssShutter() for alternative)

PARAMETERS

prefix

str : EPICS PV prefix

state_pv

str : Name of EPICS PV that provides shutter’s current state.

name

str : (kwarg, required) object’s canonical name

EXAMPLE:

A_shutter = ApsPssShutterWithStatus(
    "2bma:A_shutter:",
    "PA:02BM:STA_A_FES_OPEN_PL",
    name="A_shutter")
B_shutter = ApsPssShutterWithStatus(
    "2bma:B_shutter:",
    "PA:02BM:STA_B_SBS_OPEN_PL",
    name="B_shutter")
A_shutter.wait_for_connection()
B_shutter.wait_for_connection()

A_shutter.open()
A_shutter.close()

or

A_shutter.set("open")
A_shutter.set("close")

When using the shutter in a plan, be sure to use yield from.

def in_a_plan(shutter):

yield from abs_set(shutter, “open”, wait=True) # do something yield from abs_set(shutter, “close”, wait=True)

RE(in_a_plan(A_shutter))

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 ApsPssShutterWithStatusTuple

_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.

addCloseValue(text)

a synonym to close the shutter, use with set()

addOpenValue(text)

a synonym to open the shutter, use with set()

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

property choices

return list of acceptable choices for set()

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)

close(timeout=10)

request the shutter to close

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)

inPosition(target)

is the shutter at the target position?

property isClosed

is the shutter closed?

property isOpen

is the shutter open?

lowerCaseString(value)

ensure any given value is a lower-case string

property name

name of the device

open(timeout=10)

request the shutter to open

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…).

set(value, **kwargs)

plan: request the shutter to open or close

PARAMETERS

value

str : any from self.choices (typically “open” or “close”)

kwargs

dict : ignored at this time

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

property state

is shutter “open”, “close”, or “unknown”?

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()

validTarget(target, should_raise=True)

return whether (or not) target value is acceptable for self.set()

raise ValueError if not acceptable (default)

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

wait_for_state(target, timeout=10, poll_s=0.01)

wait for the PSS state to reach a desired target

PARAMETERS

(kwarg, optional) Name of EPICS PV to close the shutter. If None, defaults to "{prefix}Close".

target

[str] : list of strings containing acceptable values

timeout

non-negative number : (kwarg, optional) Maximum amount of time (seconds) to wait for PSS state to reach target. If None, defaults to 10.

poll_s

non-negative number : (kwarg, optional) Time to wait (seconds) in first polling cycle. After first poll, this will be increased by _poll_factor_ up to a maximum time of _poll_s_max_. If None, defaults to 0.01.

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.shutters.EpicsMotorShutter(*args, **kwargs)

Bases: OneSignalShutter

Shutter, implemented with an EPICS motor moved between two positions

PARAMETERS

prefix

str : EPICS PV prefix

name

str : (kwarg, required) object’s canonical name

EXAMPLE:

tomo_shutter = EpicsMotorShutter("2bma:m23", name="tomo_shutter")
tomo_shutter.wait_for_connection()
tomo_shutter.close_value = 1.0      # default
tomo_shutter.open_value = 0.0       # default
tomo_shutter.tolerance = 0.01       # default
tomo_shutter.open()
tomo_shutter.close()

# or, when used in a plan
def planA():
    yield from abs_set(tomo_shutter, "open", group="O")
    yield from wait("O")
    yield from abs_set(tomo_shutter, "close", group="X")
    yield from wait("X")
def planA():
    yield from abs_set(tomo_shutter, "open", wait=True)
    yield from abs_set(tomo_shutter, "close", wait=True)
def planA():
    yield from mv(tomo_shutter, "open")
    yield from mv(tomo_shutter, "close")

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 EpicsMotorShutterTuple

_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.

addCloseValue(text)

a synonym to close the shutter, use with set()

addOpenValue(text)

a synonym to open the shutter, use with set()

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

property choices

return list of acceptable choices for set()

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)

close()

move motor to BEAM BLOCKED position, interactive use

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)

inPosition(target)

is the shutter at the target position?

property isClosed

is the shutter closed?

property isOpen

is the shutter open?

lowerCaseString(value)

ensure any given value is a lower-case string

property name

name of the device

open()

move motor to BEAM NOT BLOCKED position, interactive use

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…).

set(value, **kwargs)

plan: request the shutter to open or close

PARAMETERS

value

str : any from self.choices (typically “open” or “close”)

kwargs

dict : ignored at this time

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

property state

is shutter “open”, “close”, or “unknown”?

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()

validTarget(target, should_raise=True)

return whether (or not) target value is acceptable for self.set()

raise ValueError if not acceptable (default)

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.shutters.EpicsOnOffShutter(*args, **kwargs)

Bases: OneSignalShutter

Shutter using a single EPICS PV moved between two positions

Use for a shutter controlled by a single PV which takes a value for the close command and a different value for the open command. The current position is determined by comparing the value of the control with the expected open and close values.

PARAMETERS

prefix

str : EPICS PV prefix

name

str : (kwarg, required) object’s canonical name

EXAMPLE:

bit_shutter = EpicsOnOffShutter("2bma:bit1", name="bit_shutter")
bit_shutter.wait_for_connection()
bit_shutter.close_value = 0      # default
bit_shutter.open_value = 1       # default
bit_shutter.open()
bit_shutter.close()

# or, when used in a plan
def planA():
    yield from mv(bit_shutter, "open")
    yield from mv(bit_shutter, "close")

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 EpicsOnOffShutterTuple

_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.

addCloseValue(text)

a synonym to close the shutter, use with set()

addOpenValue(text)

a synonym to open the shutter, use with set()

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

property choices

return list of acceptable choices for set()

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)

close()

BLOCKING: request shutter to close, called by set()

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)

inPosition(target)

is the shutter at the target position?

property isClosed

is the shutter closed?

property isOpen

is the shutter open?

lowerCaseString(value)

ensure any given value is a lower-case string

property name

name of the device

open()

BLOCKING: request shutter to open, called by set()

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…).

set(value, **kwargs)

plan: request the shutter to open or close

PARAMETERS

value

str : any from self.choices (typically “open” or “close”)

kwargs

dict : ignored at this time

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

property state

is shutter “open”, “close”, or “unknown”?

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()

validTarget(target, should_raise=True)

return whether (or not) target value is acceptable for self.set()

raise ValueError if not acceptable (default)

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.shutters.OneSignalShutter(*args, **kwargs)

Bases: ShutterBase

Shutter Device using one Signal for open and close.

PARAMETERS

signal

EpicsSignal or Signal : (override in subclass) The signal is the comunication to the hardware. In a subclass, the hardware may have more than one communication channel to use. See the ApsPssShutter as an example.

name

str : (kwarg, required) object’s canonical name

See ShutterBase for more parameters.

EXAMPLE

Create a simulated shutter:

shutter = OneSignalShutter(name=”shutter”)

open the shutter (interactively):

shutter.open()

Check the shutter is open:

In [144]: shutter.isOpen Out[144]: True

Use the shutter in a Bluesky plan. Set a post-move delay time of 1.0 seconds. Be sure to use yield from, such as:

def in_a_plan(shutter):
    shutter.delay_s = 1.0
    t0 = time.time()
    print("Shutter state: " + shutter.state, time.time()-t0)
    yield from bps.abs_set(shutter, "open", wait=True)    # wait for completion is optional
    print("Shutter state: " + shutter.state, time.time()-t0)
    yield from bps.mv(shutter, "open")    # do it again
    print("Shutter state: " + shutter.state, time.time()-t0)
    yield from bps.mv(shutter, "close")    # ALWAYS waits for completion
    print("Shutter state: " + shutter.state, time.time()-t0)

RE(in_a_plan(shutter))

which gives this output:

Shutter state: close 1.7642974853515625e-05 Shutter state: open 1.0032124519348145 Shutter state: open 1.0057861804962158 Shutter state: close 2.009695529937744

The strings accepted by set() are defined in two lists: valid_open_values and valid_close_values. These lists are treated (internally to set()) as lower case strings.

Example, add “o” & “x” as aliases for “open” & “close”:

shutter.addOpenValue(“o”) shutter.addCloseValue(“x”) shutter.set(“o”) shutter.set(“x”)

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 OneSignalShutterTuple

_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.

addCloseValue(text)

a synonym to close the shutter, use with set()

addOpenValue(text)

a synonym to open the shutter, use with set()

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

property choices

return list of acceptable choices for set()

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)

close()

BLOCKING: request shutter to close, called by set()

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)

inPosition(target)

is the shutter at the target position?

property isClosed

is the shutter closed?

property isOpen

is the shutter open?

lowerCaseString(value)

ensure any given value is a lower-case string

property name

name of the device

open()

BLOCKING: request shutter to open, called by set()

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…).

set(value, **kwargs)

plan: request the shutter to open or close

PARAMETERS

value

str : any from self.choices (typically “open” or “close”)

kwargs

dict : ignored at this time

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

property state

is shutter “open”, “close”, or “unknown”?

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()

validTarget(target, should_raise=True)

return whether (or not) target value is acceptable for self.set()

raise ValueError if not acceptable (default)

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.shutters.ShutterBase(*args, **kwargs)

Bases: Device

Base class for all shutter Devices.

PARAMETERS

value

str : any from self.choices (typically “open” or “close”)

valid_open_values

[str] : A list of lower-case text values that are acceptable for use with the set() command to open the shutter.

valid_close_values

[str] : A list of lower-case text values that are acceptable for use with the set() command to close the shutter.

open_value

number : The actual value to send to open signal to open the shutter. (default = 1)

close_value

number : The actual value to send to close signal to close the shutter. (default = 0)

delay_s

float : time to wait (s) after move is complete, does not wait if shutter already in position (default = 0)

busy

Signal : (internal) tells if a move is in progress

unknown_state

str : (constant) Text reported by state when not open or closed. cannot move to this position (default = “unknown”)

name

str : (kwarg, required) object’s canonical name

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 ShutterBaseTuple

_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.

addCloseValue(text)

a synonym to close the shutter, use with set()

addOpenValue(text)

a synonym to open the shutter, use with set()

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

property choices

return list of acceptable choices for set()

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)

close()

BLOCKING: request shutter to close, called by set().

Must implement in subclass of ShutterBase()

EXAMPLE:

if not self.isClosed:
    self.signal.put(self.close_value)
    if self.delay_s > 0:
        time.sleep(self.delay_s)    # blocking call OK here

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)

inPosition(target)

is the shutter at the target position?

property isClosed

is the shutter closed?

property isOpen

is the shutter open?

lowerCaseString(value)

ensure any given value is a lower-case string

property name

name of the device

open()

BLOCKING: request shutter to open, called by set().

Must implement in subclass of ShutterBase()

EXAMPLE:

if not self.isOpen:
    self.signal.put(self.open_value)
    if self.delay_s > 0:
        time.sleep(self.delay_s)    # blocking call OK here

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…).

set(value, **kwargs)

plan: request the shutter to open or close

PARAMETERS

value

str : any from self.choices (typically “open” or “close”)

kwargs

dict : ignored at this time

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

property state

returns open, close, or unknown

Must implement in subclass of ShutterBase()

EXAMPLE:

if self.signal.get() == self.open_value:
    result = self.valid_open_values[0]
elif self.signal.get() == self.close_value:
    result = self.valid_close_values[0]
else:
    result = self.unknown_state
return result

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()

validTarget(target, should_raise=True)

return whether (or not) target value is acceptable for self.set()

raise ValueError if not acceptable (default)

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.shutters.SimulatedApsPssShutterWithStatus(*args, **kwargs)

Bases: ApsPssShutterWithStatus

Simulated APS PSS shutter

PARAMETERS

prefix

str : EPICS PV prefix

name

str : (kwarg, required) object’s canonical name

EXAMPLE:

sim = SimulatedApsPssShutterWithStatus(name="sim")

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 SimulatedApsPssShutterWithStatusTuple

_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.

addCloseValue(text)

a synonym to close the shutter, use with set()

addOpenValue(text)

a synonym to open the shutter, use with set()

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

property choices

return list of acceptable choices for set()

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)

close(timeout=10)

request the shutter to close

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)

inPosition(target)

is the shutter at the target position?

property isClosed

is the shutter closed?

property isOpen

is the shutter open?

lowerCaseString(value)

ensure any given value is a lower-case string

property name

name of the device

open(timeout=10)

request the shutter to open

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…).

set(value, **kwargs)

plan: request the shutter to open or close

PARAMETERS

value

str : any from self.choices (typically “open” or “close”)

kwargs

dict : ignored at this time

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

property state

is shutter “open”, “close”, or “unknown”?

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()

validTarget(target, should_raise=True)

return whether (or not) target value is acceptable for self.set()

raise ValueError if not acceptable (default)

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

wait_for_state(target, timeout=10, poll_s=0.01)

wait for the PSS state to reach a desired target

PARAMETERS

target

[str] : list of strings containing acceptable values

timeout

non-negative number : Ignored in the simulation.

poll_s

non-negative number : Ignored in the simulation.

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)

Simulate process controllers as positioners using EPICS records.

SimulatedSwaitControllerPositioner(*args[, ...])	Simulated process controller as positioner with EPICS swait record.
SimulatedTransformControllerPositioner(*args)	Simulated process controller as positioner with EPICS transform record.

class apstools.devices.simulated_controllers.SimulatedSwaitControllerPositioner(*args, loop_pv='', **kwargs)

Bases: PVPositionerSoftDoneWithStop

Simulated process controller as positioner with EPICS swait record.

The swait record completes the feedback loop, computing the next simulated controller reading.

Example with swait record:

controller = SimulatedSwaitControllerPositioner(
    "",
    name="controller",
    loop_pv="gp:userCalc1",
)
controller.wait_for_connection()
controller.setup(25)

setup(setpoint[, label, noise, period, ...])

Configure the swait record as a process 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 SimulatedSwaitControllerPositionerTuple

_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

setup(setpoint, label='controller', noise=1, period='1 second', max_change=1, tolerance=1)

Configure the swait record as a process controller.

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.simulated_controllers.SimulatedTransformControllerPositioner(*args, loop_pv='', **kwargs)

Bases: PVPositionerSoftDoneWithStop

Simulated process controller as positioner with EPICS transform record.

The transform record completes the feedback loop, computing the next simulated controller reading and reporting if the readback is “in position”.

Example with transform record:

controller = SimulatedTransformControllerPositioner(
    "", name="controller", loop_pv="gp:userTran1",
)
controller.wait_for_connection()
controller.setup(25)

setup(setpoint[, label, noise, period, ...])

Configure the transform record as a process 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 SimulatedTransformControllerPositionerTuple

_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

setup(setpoint, label='controller', noise=2, period='1 second', max_change=2, tolerance=1)

Configure the transform record as a process controller.

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)

Ophyd support for Stanford Research Systems 570 preamplifier from synApps

Public Structures

SRS570_PreAmplifier(*args, **kwargs)

Ophyd support for Stanford Research Systems 570 preamplifier from synApps.

This device connects with the SRS570 support from synApps. (epics-modules/ip)

The SRS570 synApps support is part of the ip module: https://htmlpreview.github.io/?https://raw.githubusercontent.com/epics-modules/ip/R3-6-1/documentation/swaitRecord.html

see:

epics-modules/ip

class apstools.devices.srs570_preamplifier.GainSignal(read_pv, write_pv=None, *, put_complete=False, string=False, limits=False, name=None, **kwargs)

Bases: EpicsSignal

A signal where the settling time depends on the pre-amp gain.

Used to introduce a specific settle time when setting to account for the amp’s RC relaxation time when changing gain.

_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

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='auto')

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

valueany

The gain value.

timeoutfloat, optional

Maximum time to wait.

settle_time: float, optional

Delay after set() has completed to indicate completion to the caller. If "auto" (default), a reasonable settle time will be chosen based on the gain mode of the pre-amp.

Returns

st : Status

See also

• Signal.set

• EpicsSignal.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?

class apstools.devices.srs570_preamplifier.SRS570_PreAmplifier(*args, **kwargs)

Bases: PreamplifierBaseDevice

Ophyd support for Stanford Research Systems 570 preamplifier from synApps.

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 SRS570_PreAmplifierTuple

_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.

cb_gain(*args, **kwargs)

Called when sensitivity changes (EPICS CA monitor event).

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 computed_gain

Amplifier gain (A/V), as floating-point number.

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.srs570_preamplifier.calculate_settle_time(gain_value: int, gain_unit: int, gain_mode: str)

Determine the best settle time for a given combination of parameters.

Parameters can be strings of indexes.

Struck 3820

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

Struck/SIS 3820 Multi-Channel Scaler (as used by USAXS)

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

Bases: Device

Struck/SIS 3820 Multi-Channel Scaler (as used by USAXS)

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 Struck3820Tuple

_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)

Synthetic pseudo-Voigt function

EXAMPLES:

Simple example of SynPseudoVoigt().

from apstools.devices import SynPseudoVoigt
from ophyd.sim import motor
det = SynPseudoVoigt('det', motor, 'motor',
    center=0, eta=0.5, scale=1, sigma=1, bkg=0)

# scan the "det" peak with the "motor" positioner
# RE(bp.scan([det], motor, -2, 2, 41))

Example of SynPseudoVoigt() with randomized values.

import numpy as np
from apstools.devices import SynPseudoVoigt
synthetic_pseudovoigt = SynPseudoVoigt(
    'synthetic_pseudovoigt', m1, 'm1',
    center=-1.5 + 0.5*np.random.uniform(),
    eta=0.2 + 0.5*np.random.uniform(),
    sigma=0.001 + 0.05*np.random.uniform(),
    scale=1e5,
    bkg=0.01*np.random.uniform())

# scan the "synthetic_pseudovoigt" peak with the "m1" positioner
# RE(bp.scan([synthetic_pseudovoigt], m1, -2, 0, 219))

SynPseudoVoigt(name, motor, motor_field[, ...])

Evaluate a point on a pseudo-Voigt based on the value of a motor.

class apstools.devices.synth_pseudo_voigt.SynPseudoVoigt(name, motor, motor_field, center=0, eta=0.5, scale=1, sigma=1, bkg=0, noise=None, noise_multiplier=1, **kwargs)

Bases: SynSignal

Evaluate a point on a pseudo-Voigt based on the value of a motor.

Provides a signal to be measured. Acts like a detector.

See:

https://en.wikipedia.org/wiki/Voigt_profile

PARAMETERS

name str :

name of detector signal

motor positioner :

The independent coordinate

motor_field str :

name of motor

center float :

(optional) location of maximum value, default=0

eta float :

(optional) 0 <= eta < 1.0: Lorentzian fraction, default=0.5

scale float :

(optional) scale >= 1 : scale factor, default=1

sigma float :

(optional) sigma > 0 : width, default=1

bkg float :

(optional) bkg >= 0 : constant background, default=0

noise "poisson" or "uniform" or None :

Add noise to the result.

noise_multiplier float :

Only relevant for ‘uniform’ noise. Multiply the random amount of noise by ‘noise_multiplier’

_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(**kwargs)

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, metadata=None, timeout=<object object>, **kwargs)

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

randomize_parameters(scale=100000, bkg=0.01)

Set random parameters. -1 <= center < 1, 0.001 <= sigma < 0.051, 95k <= scale <= 105k

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=None, settle_time=None, **kwargs)

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?

Tracking Signal for Device coordination

TrackingSignal(*, name[, value, dtype, ...])

Non-EPICS signal for use when coordinating Device actions.

class apstools.devices.tracking_signal.TrackingSignal(*, name, value=0.0, dtype=None, shape=None, timestamp=None, parent=None, labels=None, kind=<Kind.hinted: 5>, tolerance=None, rtolerance=None, metadata=None, cl=None, attr_name='')

Bases: Signal

Non-EPICS signal for use when coordinating Device actions.

Signal to decide if undulator will be tracked while changing the monochromator energy.

_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)

Check if the value is a boolean.

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(**kwargs)

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, metadata=None, timeout=<object object>, **kwargs)

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, *, timeout=None, settle_time=None, **kwargs)

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

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?

XIA PF4 Filters

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).
Pf4FilterCommon([prefix, kind, read_attrs, ...])	XIA PF4 filters - common support.
Pf4FilterBank(prefix[, bank])	A single module of XIA PF4 filters (4-blades).
DualPf4FilterBox([prefix, kind, read_attrs, ...])	LEGACY (use Pf4FilterDual now): Dual (Al, Ti) Xia PF4 filter boxes

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

Bases: Device

LEGACY (use Pf4FilterDual now): Dual (Al, Ti) Xia PF4 filter boxes

Support from synApps (using Al, Ti foils)

EXAMPLE:

pf4 = DualPf4FilterBox("2bmb:pf4:", name="pf4")
pf4_AlTi = DualPf4FilterBox("9idcRIO:pf4:", name="pf4_AlTi")

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 DualPf4FilterBoxTuple

_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.xia_pf4.Pf4FilterBank(prefix, bank=None, **kwargs)

Bases: Device

A single module of XIA PF4 filters (4-blades).

EXAMPLES:

pf4B = Pf4FilterBank("ioc:pf4:", name="pf4B", bank="B")

# -or-

class MyTriplePf4(Pf4FilterCommon):
    A = Component(Pf4FilterBank, "", bank="A")
    B = Component(Pf4FilterBank, "", bank="B")
    C = Component(Pf4FilterBank, "", bank="C")

pf4 = MyTriplePf4("ioc:pf4:", name="pf4")

See:

epics-modules/optics

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 Pf4FilterBankTuple

_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.xia_pf4.Pf4FilterCommon(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Device

XIA PF4 filters - common support.

Use Pf4FilterCommon to build support for a configuration of PF4 filters (such as 3 or 4 filter banks).

EXAMPLE:

class MyTriplePf4(Pf4FilterCommon):
    A = Component(Pf4FilterBank, "", bank="A")
    B = Component(Pf4FilterBank, "", bank="B")
    C = Component(Pf4FilterBank, "", bank="C")

pf4 = MyTriplePf4("ioc:pf4:", name="pf4")

See:

epics-modules/optics

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 Pf4FilterCommonTuple

_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.xia_pf4.Pf4FilterDual(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Pf4FilterSingle

XIA PF4 Filter: two sets of 4 filters (A, B).

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 Pf4FilterDualTuple

_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.xia_pf4.Pf4FilterSingle(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Pf4FilterCommon

XIA PF4 Filter: one set of 4 filters (A).

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 Pf4FilterSingleTuple

_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.xia_pf4.Pf4FilterTriple(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, child_name_separator='_', connection_timeout=<object object>, **kwargs)

Bases: Pf4FilterDual

XIA PF4 Filter: three sets of 4 filters (A, B, C).

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 Pf4FilterTripleTuple

_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)

XIA Slit from EPICS synApps optics: xia_slit.db

Coordinates (viewing from detector towards source):

    top
inb     out
    bot

Each blade [7] (in the XIA slit controller) travels in a _cylindrical_ coordinate system. Positive motion moves a blade outwards from the center with a backlash correction. No backlash correction is applied for negative motion (as the blades close). Size and center are computed by the underlying EPICS support.

hsize = inb + out vsize = top + bot

[7]

Note that the blade names here are different than the EPICS support. The difference is to make the names of the blades consistent with other slits with the Bluesky framework.

USAGE:

slit = XiaSlitController(“IOC:hsc1:”, name=”slit”) print(slit.geometry)

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

EPICS synApps optics xia_slit.db 2D support: inb out bot top ...

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

Bases: Device

EPICS synApps optics xia_slit.db 2D support: inb out bot top …

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 XiaSlit2DTuple

_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

property geometry

Return the slit 2D size and center as a namedtuple.

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)