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#
|
Get the APS cycle name from the APS Data Management system or a local file. |
|
Common operational parameters of the APS of general interest. |
|
APS PSS shutter |
|
APS PSS shutter with separate status PV |
|
Simulated APS PSS shutter |
Area Detector Support#
|
Create an area detector object from a custom class. |
|
Build an Area Detector class with specified plugins. |
|
Alternative to HDF5Plugin: EPICS area detector PV sets file name. |
|
Alternative to JPEGPlugin: EPICS area detector PV sets file name. |
|
Alternative to TIFFPlugin: EPICS area detector PV sets file name. |
|
Custom class to define image file name from EPICS. |
|
Custom class to define HDF5 image file name from EPICS PVs. |
|
intermediate class between AD_EpicsHdf5FileName and AD_EpicsFileNameHDF5Plugin |
|
Custom class to define JPEG image file name from EPICS PVs. |
|
intermediate class between AD_EpicsJPEGFileName and AD_EpicsFileNameJPEGPlugin |
|
Custom class to define TIFF image file name from EPICS PVs. |
|
intermediate class between AD_EpicsTIFFFileName and AD_EpicsFileNameTIFFPlugin |
|
configure so frames are identified & handled by type (dark, white, or image) |
|
ADCore NDBadPixel, new in AD 3.13. |
|
Update cam support to AD release 3.1.1. |
|
Update cam support to AD release 3.1.1. |
|
Variation of ophyd's SingleTrigger mixin supporting AcquireBusy. |
|
Return AD plugin's Last filename using local filesystem path. |
|
Has area detector pushed an NDarray to the file writer plugin? True or False |
|
Prime this area detector's file writer plugin. |
|
Ensure the AD file writing plugin is primed (warmed up), if allowed. |
Detector & Scaler Support#
|
Struck/SIS 3820 Multi-Channel Scaler (as used by USAXS) |
|
Measurement Computing USB CTR08 high-speed counter/timer. |
|
Measurement Computing USB CTR08 Multi-Channel Scaler Controls. |
|
configure scaler for only the channels with names assigned in EPICS |
|
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.
|
Create an area detector object from a custom class. |
|
Make recordable DictionaryDevice instance from dictionary. |
|
Create MotorBundle with any number of motors. |
Class Factories
Class factories create ophyd Device classes.
|
Build an Area Detector class with specified plugins. |
|
Create a DictionaryDevice class using the supplied dictionary. |
|
Create a custom MotorBundle (or as specified in 'class_bases') class. |
Fly Scan Support#
ScalerMotorFlyer()
support withdrawn pending issue #763.
Insertion Devices#
|
APS Planar Undulator. |
|
APS Revolver Insertion Device. |
|
APS Planar Undulator built by STI Optronics. |
|
APS 2M Undulator. |
|
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, …#
|
AcsMotionControl motor support. |
Exception during execution of AxisTunerBase subclass |
|
|
Mixin class to provide tuning capabilities for an axis |
|
add a record's description field to a Device, such as EpicsMotor |
|
Create a custom MotorBundle (or as specified in 'class_bases') class. |
|
Create MotorBundle with any number of motors. |
|
add motor record's dial coordinate fields to Device |
|
mixin providing access to motor enable/disable |
|
add motor record's raw coordinate fields to Device |
|
Add motor record's resolution fields to motor. |
|
add motor record's servo loop controls to Device |
|
PVPositioner that computes |
|
PVPositionerSoftDone with stop() and inposition. |
|
Shutter, implemented with an EPICS motor moved between two positions |
|
Shutter using a single EPICS PV moved between two positions |
|
Simulated process controller as positioner with EPICS swait record. |
Simulated process controller as positioner with EPICS transform record. |
Shutters#
|
APS PSS shutter |
|
APS PSS shutter with separate status PV |
|
Shutter, implemented with an EPICS motor moved between two positions |
|
Shutter using a single EPICS PV moved between two positions |
|
Shutter Device using one Signal for open and close. |
|
Base class for all shutter Devices. |
|
Simulated APS PSS shutter |
Slits#
|
High Heat Load Slit. |
|
EPICS synApps optics xia_slit.db 2D support: inb out bot top ... |
|
EPICS synApps optics 2slit.db 1D support: xn, xp, size, center, sync |
|
EPICS synApps optics 2slit.db 2D support: h.xn, h.xp, v.xn, v.xp |
|
EPICS synApps optics 2slit.db 2D support: inb, out, bot, top |
|
Slit size and center as a named tuple |
synApps Support#
See separate synApps section.
Temperature Support#
Controllers#
|
Eurotherm 2216e Temperature Controller |
|
LakeShore 336 temperature controller. |
|
LakeShore 340 temperature controller |
|
Linkam model CI94 temperature controller |
|
Linkam model T96 temperature controller |
|
SRS PTC10 AIO module |
|
SRS PTC10 RTD module channel |
|
SRS PTC10 Tc (thermocouple) module channel |
|
Mixin so SRS PTC10 can be used as a (temperature) positioner. |
|
Simulated process controller as positioner with EPICS swait record. |
Simulated process controller as positioner with EPICS transform record. |
Readers#
|
Measurement Computing TC-32 32-channel Thermocouple reader. |
Other Support#
|
Provide current experiment info from the APS BSS. |
|
Support for the APS Data Management tools. |
|
XIA PF4 Filter: one set of 4 filters (A). |
|
XIA PF4 Filter: two sets of 4 filters (A, B). |
|
XIA PF4 Filter: three sets of 4 filters (A, B, C). |
|
A single module of XIA PF4 filters (4-blades). |
|
XIA PF4 filters - common support. |
|
LEGACY (use Pf4FilterDual now): Dual (Al, Ti) Xia PF4 filter boxes |
|
add a record's description field to a Device, such as EpicsMotor |
|
Create a DictionaryDevice class using the supplied dictionary. |
|
Make recordable DictionaryDevice instance from dictionary. |
|
Use an EPICS PV as the source of the RunEngine's |
|
Measurement Computing USB CTR08 high-speed counter/timer. |
|
synApps Kohzu double-crystal monochromator sequence control program |
|
Simulated process controller as positioner with EPICS swait record. |
Simulated process controller as positioner with EPICS transform record. |
|
|
Ophyd support for Stanford Research Systems 570 preamplifier from synApps. |
|
Struck/SIS 3820 Multi-Channel Scaler (as used by USAXS) |
|
An SRS DG-645 digial delay/pulse generator. |
|
A labjack T-series data acquisition unit (DAQ). |
|
A labjack T-series data acquisition unit (DAQ). |
|
A labjack T-series data acquisition unit (DAQ). |
|
A labjack T-series data acquisition unit (DAQ). |
|
A labjack T-series data acquisition unit (DAQ). |
Internal Routines#
|
General messages from the APS main control room. |
|
Non-EPICS signal for use when coordinating Device actions. |
|
Base class for apstools Device mixin classes |
All Submodules#
ACS Motors#
AcsMotors
provides extra signals that are part of AcsMotionControl motor support.
|
Components used by EPICS database for ACS Motion Controller. |
|
Adds support for motor record resolution fields. |
|
Adds "servo" enable/disable (CNEN) field. |
|
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)[source]#
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 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.acs_motors.EpicsMotorWithRes(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, **kwargs)[source]#
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 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.acs_motors.EpicsMotorWithResAndCNEN(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, **kwargs)[source]#
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 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.acs_motors.EpicsMotorWithResAndCNENAndDial(prefix='', *, name, kind=None, read_attrs=None, configuration_attrs=None, parent=None, **kwargs)[source]#
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 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
APS User Proposal and ESAF Information#
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
APS cycles#
|
Get the APS cycle name from the APS Data Management system or a local file. |
- class apstools.devices.aps_cycle.ApsCycleDM(*args, **kwargs)[source]#
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
- 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[source]#
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()[source]#
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)[source]#
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)[source]#
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
)
|
Support for the APS Data Management tools. |
- class apstools.devices.aps_data_management.DM_WorkflowConnector(name=None, workflow=None, **kwargs)[source]#
Bases:
Device
Support for the APS Data Management tools.
The DM workflow dictionary of arguments (
workflow_args
) needs special attention. Python’sdict
structure is not compatible with MongoDB. In turn, ophyd does not support it. A custom plan can choose how to use theworkflow_args
dictionary:use with DM workflow, as planned
add
workflow_args
to the start metadatawrite 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" )
Local copy of DM Processing API object.
Is DM Processing idle?
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.
Return the list of workflows.
put_if_different
(signal, value)Put ophyd signal only if new value is different.
(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()[source]#
(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.
- 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)
- 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)[source]#
Print a table about each stage of the workflow process.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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)[source]#
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 theStatusBase
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
|
Common operational parameters of the APS of general interest. |
|
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)[source]#
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)
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
APS undulators (Insertion Devices)#
|
APS Planar Undulator. |
|
APS Revolver Insertion Device. |
|
APS Planar Undulator built by STI Optronics. |
|
APS 2M Undulator. |
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.aps_undulator.UndulatorPositioner(prefix='', *, limits=None, name=None, read_attrs=None, configuration_attrs=None, parent=None, egu='', **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
Area Detector Factory#
|
Create an area detector object from a custom class. |
|
Build an Area Detector class with specified plugins. |
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)[source]#
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)[source]#
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#
|
Alternative to HDF5Plugin: EPICS area detector PV sets file name. |
|
Alternative to JPEGPlugin: EPICS area detector PV sets file name. |
|
Custom class to define image file name from EPICS. |
|
Alternative to TIFFPlugin: EPICS area detector PV sets file name. |
|
Custom class to define HDF5 image file name from EPICS PVs. |
|
intermediate class between AD_EpicsHdf5FileName and AD_EpicsFileNameHDF5Plugin |
|
Custom class to define JPEG image file name from EPICS PVs. |
|
intermediate class between AD_EpicsJPEGFileName and AD_EpicsFileNameJPEGPlugin |
|
Custom class to define TIFF image file name from EPICS PVs. |
|
intermediate class between AD_EpicsTIFFFileName and AD_EpicsFileNameTIFFPlugin |
Naming schemes for area detector frame types. |
|
|
Return AD plugin's Last filename using local filesystem path. |
|
Has area detector pushed an NDarray to the file writer plugin? True or False |
|
Prime this area detector's file writer plugin. |
|
Prime this area detector's file writer plugin. |
|
configure so frames are identified & handled by type (dark, white, or image) |
|
ADCore NDBadPixel, new in AD 3.13. |
|
Update cam support to AD release 3.1.1. |
|
Update cam support to AD release 3.1.1. |
|
Add data acquisition methods to HDF5Plugin. |
|
Variation of ophyd's SingleTrigger mixin supporting AcquireBusy. |
|
Ensure the AD file writing plugin is primed (warmed up), if allowed. |
- class apstools.devices.area_detector_support.AD_EpicsFileNameHDF5Plugin(*args, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.area_detector_support.AD_EpicsFileNameMixin(*args, **kwargs)[source]#
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
overrides default behavior: Get info from EPICS file writer plugin.
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()
fromophyd.areadetector.filestore_mixins
. This is called (during device staging) fromFileStoreBase.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_
- 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.
- 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()[source]#
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 theStatusBase
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.area_detector_support.AD_EpicsHDF5IterativeWriter(*args, **kwargs)[source]#
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 theStatusBase
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)[source]#
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 theStatusBase
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)[source]#
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 theStatusBase
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)[source]#
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 theStatusBase
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)[source]#
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 theStatusBase
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)[source]#
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 theStatusBase
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)[source]#
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)[source]#
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)[source]#
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)[source]#
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')[source]#
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. TheFrameType
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 EPICSmbbo
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.area_detector_support.HDF5FileWriterPlugin(*args, **kwargs)[source]#
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 acquisitionunstage()
- restore device PVs after data acquisitiongenerate_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()[source]#
Stage the device for data collection.
This method is expected to put the device into a state where repeated calls to
trigger()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.area_detector_support.SingleTrigger_V34(*args, **kwargs)[source]#
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.
- trigger()#
Trigger one acquisition.
- apstools.devices.area_detector_support.ensure_AD_plugin_primed(plugin, allow=False)[source]#
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 (viaarea_detector_handlers
) checks if the area detector file writing plugin has been primed.See also
ophyd.areadetector.plugins.UnprimedPlugin
: bluesky/ophydAdded in version 1.6.16.
Axis Tuner#
Exception during execution of AxisTunerBase subclass |
|
|
Mixin class to provide tuning capabilities for an axis |
- exception apstools.devices.axis_tuner.AxisTunerException[source]#
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)[source]#
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
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
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)[source]#
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 channelschannel_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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
Mixin to add EPICS .DESC field#
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
DictionaryDevice#
Create an ophyd Device defined by a dictionary so that a simple dictionary can be recorded in a bluesky data stream.
|
Create a DictionaryDevice class using the supplied dictionary. |
|
Make recordable DictionaryDevice instance from dictionary. |
- apstools.devices.dict_device_support.dict_device_factory(data={})[source]#
Create a DictionaryDevice class using the supplied dictionary.
- apstools.devices.dict_device_support.make_dict_device(obj, name='ddev')[source]#
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)[source]#
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)[source]#
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
andEpicsSignal
, which are both subclasses ofEpicsSignalBase
.but
>>> EpicsSignal.set_defaults(...)
will not apply to
EpicsSignalRO
.Parameters#
- auto_monitor: bool, optional
If
True
, update cached value from EPICS CA monitor callbacks. IfFalse
, 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.
|
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]
- class apstools.devices.eurotherm_2216e.Eurotherm2216e(prefix='', *, tolerance=1, **kwargs)[source]#
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_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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
High Heat-Load Apertures#
|
Base class for HHLAperture classes, 2-axis slit. |
|
High Heat Load Aperture. |
|
High Heat Load Aperture for ACS motors. |
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.hhl_apertures.HHLApertureACS(prefix: str, pitch_motor: str, yaw_motor: str, horizontal_motor: str, diagonal_motor: str, *args, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.hhl_apertures.HHLApertureWBA(prefix: str, pitch_motor: str, yaw_motor: str, horizontal_motor: str, diagonal_motor: str, *args, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.hhl_slits.HHLSlits(prefix: str, pitch_motor: str, yaw_motor: str, horizontal_motor: str, diagonal_motor: str, *args, **kwargs)[source]#
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
Kohzu double-crystal monochromator#
|
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)[source]#
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.kohzu_monochromator.KohzuSoftPositioner(*args, **kwargs)[source]#
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
- _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)[source]#
Called when parent’s done signal changes (EPICS CA monitor event).
- cb_setpoint(*args, **kwargs)[source]#
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 todone_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.
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
LabJack Data Acquisition (DAQ)#
|
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
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.labjack.DigitalIO(*args, ch_num, **kwargs)[source]#
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 PVLabJackT7_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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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, likeLabJackT4
.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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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, likeLabJackT4
.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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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, likeLabJackT4
.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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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, likeLabJackT4
.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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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, likeLabJackT4
.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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- _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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- apstools.devices.labjack.make_digitizer_waveforms(num_ais: int)[source]#
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#
|
LakeShore 336 temperature controller. |
|
LakeShore 340 temperature controller |
- class apstools.devices.lakeshore_controllers.LS340_LoopBase(*args, loop_number=None, timeout=36000, **kwargs)[source]#
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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.lakeshore_controllers.LS340_LoopControl(*args, loop_number=None, timeout=36000, **kwargs)[source]#
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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.lakeshore_controllers.LS340_LoopSample(*args, loop_number=None, timeout=36000, **kwargs)[source]#
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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.lakeshore_controllers.LakeShore336_LoopControl(*args, loop_number=None, timeout=36000, **kwargs)[source]#
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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.lakeshore_controllers.LakeShore336_LoopRO(*args, loop_number=None, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
Linkam temperature controllers#
|
Linkam model CI94 temperature controller |
|
Linkam model T96 temperature controller |
- class apstools.devices.linkam_controllers.Linkam_CI94_Device(*args, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.linkam_controllers.Linkam_T96_Device(*args, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.linkam_controllers.T96Temperature(prefix='', *, readback_pv='', setpoint_pv='', tolerance=None, use_target=False, **kwargs)[source]#
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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
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.
https://epics-modules.github.io/measComp/measCompMultiFunctionDoc.html#tc-32
Public class(es)
|
Measurement Computing TC-32 32-channel Thermocouple reader. |
Internal class(es)
|
Base class for I/O interface classes below. |
|
Binary input channel of a MeasComp TC-32 device. |
|
Binary output channel of a MeasComp TC-32 device. |
|
Thermocouple channel of a MeasComp TC-32 device. |
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.measComp_tc32_support.Tc32BinaryInput(prefix, R, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.measComp_tc32_support.Tc32BinaryOutput(prefix, R, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.measComp_tc32_support.Tc32ThermocoupleChannel(prefix, R, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.measComp_tc32_support._MC_TC32_BaseClass(prefix, R, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- apstools.devices.measComp_tc32_support._channels(dev_class, channel_list)[source]#
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)
|
Measurement Computing USB CTR08 high-speed counter/timer. |
|
Measurement Computing USB CTR08 Multi-Channel Scaler Controls. |
Internal class(es)
|
Measurement Computing USB CTR08 Pulse Counter channel. |
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
Base class for Device Mixins#
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
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.
|
Return a Component with 'parms for this axis. |
|
Create a custom MotorBundle (or as specified in 'class_bases') class. |
|
Create MotorBundle with any number of motors. |
Quick Example
1xy_stage = mb_creator(
2 prefix="IOC:",
3 motors={"x": "m21", "y": "m22"},
4 name="xy_stage",
5)
See also
- apstools.devices.motor_factory.axis_component(parms: None | str | Mapping[str, Any]) Component [source]#
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] [source]#
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 [source]#
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#
|
add motor record's dial coordinate fields to Device |
|
mixin providing access to motor enable/disable |
|
add motor record's raw coordinate fields to Device |
|
Add motor record's resolution fields to motor. |
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.motor_mixins.EpicsMotorLimitsMixin(*args, **kwargs)[source]#
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)[source]#
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
PVPositioner that computes done
as a soft signal.
|
PVPositioner that computes |
|
PVPositionerSoftDone with stop() and inposition. |
- class apstools.devices.positioner_soft_done.PVPositionerSoftDone(prefix='', *, readback_pv='', setpoint_pv='', tolerance=None, use_target=False, **kwargs)[source]#
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)
, whereprecision = setpoint.precision
.- use_targetbool
True
when this object update thetarget
Component directly. UseFalse
if thetarget
Component will be updated externally, such as by the controller whentarget
is anEpicsSignal
. Defaults toFalse
.- 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 whilesetpoint
will be the current desired position.Otherwise, both
setpoint
andtarget
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
- _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)[source]#
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)[source]#
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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.positioner_soft_done.PVPositionerSoftDoneWithStop(prefix='', *, readback_pv='', setpoint_pv='', tolerance=None, use_target=False, **kwargs)[source]#
Bases:
PVPositionerSoftDone
PVPositionerSoftDone with stop() and inposition.
The
stop()
method sets the setpoint to the immediate readback value (only wheninposition
isTrue
). 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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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)[source]#
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 theStatusBase
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.
Generalized ophyd Device base class for preamplifiers.
|
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)[source]#
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 isSRS570_PreAmplifier
.- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
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.
|
SRS PTC10 AIO module |
|
SRS PTC10 RTD module channel |
|
SRS PTC10 Tc (thermocouple) module channel |
|
Mixin so SRS PTC10 can be used as a (temperature) positioner. |
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.ptc10_controller.PTC10PositionerMixin(*args, **kwargs)[source]#
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).
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_setpoint(*args, **kwargs)[source]#
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 todone_value (True)
. Without this response, a small move (within tolerance) will not return. Next update of readback will computeself.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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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)[source]#
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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
Scaler support#
|
configure scaler for only the channels with names assigned in EPICS |
- apstools.devices.scaler_support.use_EPICS_scaler_channels(scaler)[source]#
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#
|
APS PSS shutter |
|
APS PSS shutter with separate status PV |
|
Shutter, implemented with an EPICS motor moved between two positions |
|
Shutter using a single EPICS PV moved between two positions |
|
Shutter Device using one Signal for open and close. |
|
Base class for all shutter Devices. |
|
Simulated APS PSS shutter |
- class apstools.devices.shutters.ApsPssShutter(prefix, *args, close_pv=None, open_pv=None, **kwargs)[source]#
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 theisOpen
andisClosed
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)
- 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
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.shutters.ApsPssShutterWithStatus(prefix, state_pv, *args, **kwargs)[source]#
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)
- 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
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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)[source]#
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 to10
.- 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_
. IfNone
, defaults to0.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.
- class apstools.devices.shutters.EpicsMotorShutter(*args, **kwargs)[source]#
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)
- 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
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.shutters.EpicsOnOffShutter(*args, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.shutters.OneSignalShutter(*args, **kwargs)[source]#
Bases:
ShutterBase
Shutter Device using one Signal for open and close.
PARAMETERS
- signal
EpicsSignal
orSignal
: (override in subclass) Thesignal
is the comunication to the hardware. In a subclass, the hardware may have more than one communication channel to use. See theApsPssShutter
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)
- 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
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.shutters.ShutterBase(*args, **kwargs)[source]#
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.
- 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()[source]#
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)
- property isClosed#
is the shutter closed?
- property isOpen#
is the shutter open?
- property name#
name of the device
- open()[source]#
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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
, orunknown
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 theStatusBase
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)[source]#
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.
- class apstools.devices.shutters.SimulatedApsPssShutterWithStatus(*args, **kwargs)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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)[source]#
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.
Simulate process controllers as positioners using EPICS records.
|
Simulated process controller as positioner with EPICS swait record. |
Simulated process controller as positioner with EPICS transform record. |
- class apstools.devices.simulated_controllers.SimulatedSwaitControllerPositioner(*args, loop_pv='', **kwargs)[source]#
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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.simulated_controllers.SimulatedTransformControllerPositioner(*args, loop_pv='', **kwargs)[source]#
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 todone_value
.Without this response, a small move (within tolerance) will not return. The
cb_readback()
method will computedone
.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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
Ophyd support for Stanford Research Systems 570 preamplifier from synApps
Public Structures
|
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:
- class apstools.devices.srs570_preamplifier.GainSignal(read_pv, write_pv=None, *, put_complete=False, string=False, limits=False, name=None, **kwargs)[source]#
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')[source]#
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
andEpicsSignal
, which are both subclasses ofEpicsSignalBase
.but
>>> EpicsSignal.set_defaults(...)
will not apply to
EpicsSignalRO
.Parameters#
- auto_monitor: bool, optional
If
True
, update cached value from EPICS CA monitor callbacks. IfFalse
, 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)[source]#
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.
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- apstools.devices.srs570_preamplifier.calculate_settle_time(gain_value: int, gain_unit: int, gain_mode: str)[source]#
Determine the best settle time for a given combination of parameters.
Parameters can be strings of indexes.
Struck 3820#
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
Synthetic pseudo-Voigt function#
EXAMPLES:
1from apstools.devices import SynPseudoVoigt
2from ophyd.sim import motor
3det = SynPseudoVoigt('det', motor, 'motor',
4 center=0, eta=0.5, scale=1, sigma=1, bkg=0)
5
6# scan the "det" peak with the "motor" positioner
7# RE(bp.scan([det], motor, -2, 2, 41))
1import numpy as np
2from apstools.devices import SynPseudoVoigt
3synthetic_pseudovoigt = SynPseudoVoigt(
4 'synthetic_pseudovoigt', m1, 'm1',
5 center=-1.5 + 0.5*np.random.uniform(),
6 eta=0.2 + 0.5*np.random.uniform(),
7 sigma=0.001 + 0.05*np.random.uniform(),
8 scale=1e5,
9 bkg=0.01*np.random.uniform())
10
11# scan the "synthetic_pseudovoigt" peak with the "m1" positioner
12# RE(bp.scan([synthetic_pseudovoigt], m1, -2, 0, 219))
|
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)[source]#
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.
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"
orNone
: 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)[source]#
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#
|
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='')[source]#
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.
- 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#
|
XIA PF4 Filter: one set of 4 filters (A). |
|
XIA PF4 Filter: two sets of 4 filters (A, B). |
|
XIA PF4 Filter: three sets of 4 filters (A, B, C). |
|
XIA PF4 filters - common support. |
|
A single module of XIA PF4 filters (4-blades). |
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- class apstools.devices.xia_pf4.Pf4FilterBank(prefix, bank=None, **kwargs)[source]#
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:
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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:
- 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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
- 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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.
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
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)
|
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)[source]#
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()
andread()
will ‘do the right thing’.Staging not idempotent and should raise
RedundantStaging
if staged twice without an intermediateunstage()
.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 theStatusBase
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.