1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
|
================================
Devices: collections of PVs
================================
Overview
===========
.. module:: device
:synopsis: collections of related PVs
The :mod:`device` module provides a simple interface to a collection of
PVs. Here an epics :class:`device.Device` is an object holding a set of
PVs, all sharing a prefix, but having many *attributes*. Many PVs will
have names made up of *prefix+attribute*, with a common prefix for several
related PVs. This almost describes an Epics Record, but as it is concerned
only with PV names, the mapping to an Epics Record is not exact. On the
other hand, the concept of a *device* is more flexible than a predefined
Epics Record as it can actually hold PVs from several different records.::
motor1 = epics.Device('XXX:motor1.', attrs=('VAL', 'RBV', 'DESC', 'RVAL',
'LVIO', 'HLS', 'LLS'))
motor1.put('VAL', 1)
print 'Motor %s = %f' % ( motor1.get('DESC'), motor1.get('RBV'))
motor1.VAL = 0
print 'Motor %s = %f' % ( motor1.DESC, motor1.RBV )
While useful on its own like this, the real point of a *device* is as a
base class, to be inherited and extended. In fact, there is a more
sophisticated Motor device described below at :ref:`device-motor-label`
.. class:: Device(prefix=None[, delim=''[, attrs=None]])
The attribute PVs are built as needed and held in an internal buffer
:data:`self._pvs`. This class is kept intentionally simple so that it may
be subclassed.
To pre-load attribute names on initialization, provide a list or tuple of
attributes with the `attr` option.
Note that *prefix* is actually optional. When left off, this class can be
used as an arbitrary container of PVs, or to turn any subclass into an
epics Device.
In general, PV names will be mapped as prefix+delim+attr. See
:meth:`add_pv` for details of how to override this.
.. method:: PV(attr[, connect=True[, **kw]]])
returns the `PV` object for a device attribute. The connect argument
and any other keyword arguments are passed to :meth:`epics.PV`.
.. method:: put(attr, value[, wait=False[, timeout=10.0]])
put an attribute value, optionally wait for completion or up to a
supplied timeout value
.. method:: get(attr[, as_string=False])
get an attribute value, option as_string returns a string
representation
.. method:: add_callback(attr, callback)
add a callback function to an attribute PV, so that the callback
function will be run when the at tribute's value changes
.. method:: add_pv(pvname[, attr=None,[ **kw]])
adds an explicitly names :meth:`epics.PV` to the device even though it
may violate the normal naming rules (in which `attr` is mapped to
`epics.PV(prefix+delim+attr)`. That is, one can say::
import epics
m1 = epics.Device('XXX:m1', delim='.')
m1.add_pv('XXX:m2.VAL', attr='other')
print m1.VAL # print value of XXX:m1.VAL
print m1.other # prints value of XXX:m2.VAL
.. method:: save_state()
return a dictionary of all current values -- the ''current state''.
.. method:: restore_state(state)
restores a saved state, as saved with :meth:`save_state`
.. method:: write_state(fname[, state=None])
write a saved state to a file. If no state is provide, the current state is written.
.. method:: read_state(fname[, restore=False])
reads a state from a file, as written with :meth:`write_state`, and returns it.
If ''restore'' is ``True``, the read state will be restored.
.. data:: _pvs
a dictionary of PVs making up the device.
.. _device-motor-label:
Epics Motor Device
===========================
.. module:: motor
The Epics Motor record has over 100 fields associated with it. Of course,
it is often preferable to think of 1 Motor with many attributes than 100
or so separate PVs. Many of the fields of the Motor record are
interrelated and influence other settings, including limits on the range of
motion which need to be respected, and which may send notifications when
they are violated. Thus, there is a fair amount of functionality for a
Motor. Typically, the user just wants to move the motor by setting its
drive position, but a fully enabled Motor should allow the use to change
and read many of the Motor parameters.
The :class:`Motor` class helps the user create and use Epics motors.
A simple example use would be::
import epics
m1 = epics.Motor('XXX:m1')
print 'Motor: ', m1.DESC , ' Currently at ', m1.RBV
m1.tweak_val = 0.10
m1.move(0.0, dial=True, wait=True)
for i in range(10):
m1.tweak(direction='forward', wait=True)
time.sleep(1.0)
print 'Motor: ', m1.DESC , ' Currently at ', m1.RBV
Which will step the motor through a set of positions. You'll notice a
few features for Motor:
1. Motors can use English-name aliases for attributes for fields of the
motor record. Thus 'VAL' can be spelled 'drive' and 'DESC' can be
'description'. The :ref:`Table of Motor Attributes <motorattr_table>`
give the list of names that can be used.
2. The methods for setting positions can use the User, Dial, or Step
coordinate system, and can wait for completion.
The :class:`epics.Motor` class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. class:: Motor(pvname[, timeout=30.])
create a Motor object for a named Epics Process Variable.
:param pvname: prefix name (no '.VAL' needed!) of Epics Process Variable for a Motor
:type pvname: string
:param timeout: time (in seconds) to wait before giving up trying to connect.
:type timeout: float
Once created, a Motor should be ready to use.
>>> from epics import Motor
>>> m = Motor('XX:m1')
>>> print m.drive, m.description, m.slew_speed
1.030 Fine X 5.0
>>> print m.get('device_type', as_string=True)
'asynMotor'
A Motor has very many fields. Only a few of them are created on
initialization -- the rest are retrieved as needed. The motor fields can
be retrieved either with an attribute or with the :meth:`get` method.
A full list of Motor attributes and their aliases for the motor
record is given in :ref:`Table of Motor Attributes <motorattr_table>`.
.. _motorattr_table:
Table of Aliases for attributes for the epics :class:`Motor` class, and the
corresponding attribute name of the Motor Record field.
+--------------------+--------------------------+---+--------------------+--------------------------+
| **alias** | *Motor Record field* | | **alias** | *Motor Record field* |
+====================+==========================+===+====================+==========================+
| disabled | _able.VAL | | moving | MOVN |
+--------------------+--------------------------+---+--------------------+--------------------------+
| acceleration | ACCL | | resolution | MRES |
+--------------------+--------------------------+---+--------------------+--------------------------+
| back_accel | BACC | | motor_status | MSTA |
+--------------------+--------------------------+---+--------------------+--------------------------+
| backlash | BDST | | offset | OFF |
+--------------------+--------------------------+---+--------------------+--------------------------+
| back_speed | BVEL | | output_mode | OMSL |
+--------------------+--------------------------+---+--------------------+--------------------------+
| card | CARD | | output | OUT |
+--------------------+--------------------------+---+--------------------+--------------------------+
| dial_high_limit | DHLM | | prop_gain | PCOF |
+--------------------+--------------------------+---+--------------------+--------------------------+
| direction | DIR | | precision | PREC |
+--------------------+--------------------------+---+--------------------+--------------------------+
| dial_low_limit | DLLM | | readback | RBV |
+--------------------+--------------------------+---+--------------------+--------------------------+
| settle_time | DLY | | retry_max | RTRY |
+--------------------+--------------------------+---+--------------------+--------------------------+
| done_moving | DMOV | | retry_count | RCNT |
+--------------------+--------------------------+---+--------------------+--------------------------+
| dial_readback | DRBV | | retry_deadband | RDBD |
+--------------------+--------------------------+---+--------------------+--------------------------+
| description | DESC | | dial_difference | RDIF |
+--------------------+--------------------------+---+--------------------+--------------------------+
| dial_drive | DVAL | | raw_encoder_pos | REP |
+--------------------+--------------------------+---+--------------------+--------------------------+
| units | EGU | | raw_high_limit | RHLS |
+--------------------+--------------------------+---+--------------------+--------------------------+
| encoder_step | ERES | | raw_low_limit | RLLS |
+--------------------+--------------------------+---+--------------------+--------------------------+
| freeze_offset | FOFF | | relative_value | RLV |
+--------------------+--------------------------+---+--------------------+--------------------------+
| move_fraction | FRAC | | raw_motor_pos | RMP |
+--------------------+--------------------------+---+--------------------+--------------------------+
| hi_severity | HHSV | | raw_readback | RRBV |
+--------------------+--------------------------+---+--------------------+--------------------------+
| hi_alarm | HIGH | | readback_res | RRES |
+--------------------+--------------------------+---+--------------------+--------------------------+
| hihi_alarm | HIHI | | raw_drive | RVAL |
+--------------------+--------------------------+---+--------------------+--------------------------+
| high_limit | HLM | | dial_speed | RVEL |
+--------------------+--------------------------+---+--------------------+--------------------------+
| high_limit_set | HLS | | s_speed | S |
+--------------------+--------------------------+---+--------------------+--------------------------+
| hw_limit | HLSV | | s_back_speed | SBAK |
+--------------------+--------------------------+---+--------------------+--------------------------+
| home_forward | HOMF | | s_base_speed | SBAS |
+--------------------+--------------------------+---+--------------------+--------------------------+
| home_reverse | HOMR | | s_max_speed | SMAX |
+--------------------+--------------------------+---+--------------------+--------------------------+
| high_op_range | HOPR | | set | SET |
+--------------------+--------------------------+---+--------------------+--------------------------+
| high_severity | HSV | | stop_go | SPMG |
+--------------------+--------------------------+---+--------------------+--------------------------+
| integral_gain | ICOF | | s_revolutions | SREV |
+--------------------+--------------------------+---+--------------------+--------------------------+
| jog_accel | JAR | | stop | STOP |
+--------------------+--------------------------+---+--------------------+--------------------------+
| jog_forward | JOGF | | t_direction | TDIR |
+--------------------+--------------------------+---+--------------------+--------------------------+
| jog_reverse | JOGR | | tweak_forward | TWF |
+--------------------+--------------------------+---+--------------------+--------------------------+
| jog_speed | JVEL | | tweak_reverse | TWR |
+--------------------+--------------------------+---+--------------------+--------------------------+
| last_dial_val | LDVL | | tweak_val | TWV |
+--------------------+--------------------------+---+--------------------+--------------------------+
| low_limit | LLM | | use_encoder | UEIP |
+--------------------+--------------------------+---+--------------------+--------------------------+
| low_limit_set | LLS | | u_revolutions | UREV |
+--------------------+--------------------------+---+--------------------+--------------------------+
| lo_severity | LLSV | | use_rdbl | URIP |
+--------------------+--------------------------+---+--------------------+--------------------------+
| lolo_alarm | LOLO | | drive | VAL |
+--------------------+--------------------------+---+--------------------+--------------------------+
| low_op_range | LOPR | | base_speed | VBAS |
+--------------------+--------------------------+---+--------------------+--------------------------+
| low_alarm | LOW | | slew_speed | VELO |
+--------------------+--------------------------+---+--------------------+--------------------------+
| last_rel_val | LRLV | | version | VERS |
+--------------------+--------------------------+---+--------------------+--------------------------+
| last_dial_drive | LRVL | | max_speed | VMAX |
+--------------------+--------------------------+---+--------------------+--------------------------+
| last_SPMG | LSPG | | use_home | ATHM |
+--------------------+--------------------------+---+--------------------+--------------------------+
| low_severity | LSV | | deriv_gain | DCOF |
+--------------------+--------------------------+---+--------------------+--------------------------+
methods for :class:`epics.Motor`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. method:: get(attr[, as_string=False])
sets a field attribute for the motor.
:param attr: attribute name
:type attr: string (from table above)
:param as_string: whether to return string value.
:type as_string: ``True``/ ``False``
Note that :meth:`get` can return the string value, while fetching the
attribute cannot do so::
>>> m = epics.Motor('XXX:m1')
>>> print m.device_type
0
>>> print m.get('device_type', as_string=True)
'asynMotor'
.. method:: put(attr, value[, wait=False[, timeout=30]])
sets a field attribute for the motor.
:param attr: attribute name
:type attr: string (from table above)
:param value: value for attribute
:param wait: whether to wait for completion.
:type wait: ``True``/``False``
:param timeout: time (in seconds) to wait before giving up trying to connect.
:type timeout: float
.. method:: check_limits()
checks whether the current motor position is causing a motor limit
violation, and raises a MotorLimitException if it is.
returns ``None`` if there is no limit violation.
.. method:: within_limits(value[, limits='user'])
checks whether a target value **would be** a limit violation.
:param value: target value
:param limits: one of 'user', 'dial', or 'raw' for which limits to consider
:type limits: string
:rtype: ``True``/``False``
.. method:: move(val=None[, relative=None[, wait=False[, timeout=300.0[, dial=False[, raw=False[, ignore_limits=False, [confirm_move=False]]]]]]])
moves motor to specified drive position.
:param val: value to move to (float) [Must be provided]
:param relative: move relative to current position (T/F) [F]
:param wait: whether to wait for move to complete (T/F) [F]
:param timeout: max time for move to complete (in seconds) [300]
:param dial: use dial coordinates (T/F) [F]
:param raw: use raw coordinates (T/F) [F]
:param ignore_limits: try move without regard to limits (T/F) [F]
:param confirm_move: try to confirm that move has begun (when wait=False) (T/F) [F]
:rtype: integer
Returns an integer value, according the table below. Note that a return
value of 0 with `wait=False` does not really guarantee a successful
move, just that a move request was issued. If you're interested in
checking that a requested move really did start without waiting for the
move to complete, you may want to use the `confirm_move=True` option.
.. _motor_move_return_vals_table:
Table of return values from :func:`move`.
+---------------+----------------------------------------------------------------+
| return value | meaning |
+===============+================================================================+
| -13 | invalid value (cannot convert to float). Move not attempted. |
+---------------+----------------------------------------------------------------+
| -12 | target value outside soft limits. Move not attempted. |
+---------------+----------------------------------------------------------------+
| -11 | drive PV is not connected: Move not attempted. |
+---------------+----------------------------------------------------------------+
| -8 | move started, but timed-out. |
+---------------+----------------------------------------------------------------+
| -7 | move started, timed-out, but appears done. |
+---------------+----------------------------------------------------------------+
| -5 | move started, unexpected return value from :func:`put` |
+---------------+----------------------------------------------------------------+
| -4 | move-with-wait finished, soft limit violation seen. |
+---------------+----------------------------------------------------------------+
| -3 | move-with-wait finished, hard limit violation seen. |
+---------------+----------------------------------------------------------------+
| 0 | move-with-wait finish OK. |
+---------------+----------------------------------------------------------------+
| 0 | move-without-wait executed, not confirmed. |
+---------------+----------------------------------------------------------------+
| 1 | move-without-wait executed, move confirmed. |
+---------------+----------------------------------------------------------------+
| 3 | move-without-wait finished, hard limit violation seen. |
+---------------+----------------------------------------------------------------+
| 4 | move-without-wait finished, soft limit violation seen. |
+---------------+----------------------------------------------------------------+
.. method:: tweak(direction='forward'[, wait=False[, timeout=300.]])
move the motor by the current *tweak value*
:param direction: direction of motion
:type direction: string: 'forward' (default) or 'reverse'
:param wait: whether to wait for completion
:type wait: ``True``/``False``
:param timeout: max time for move to complete (in seconds) [default=300]
:type timeout: float
.. method:: get_position(readback=False[, dial=False[, raw=False]])
Returns the motor position in user, dial or raw coordinates.
:param readback: whether to return the readback position in the
desired coordinate system. The default is to return the
drive position of the motor.
:param dial: whether to return the position in dial coordinates.
The default is user coordinates.
:param raw: whether to return the raw position.
The default is user coordinates.
The "raw" and "dial" keywords are mutually exclusive.
The "readback" keyword can be used in user, dial or raw coordinates.
.. method:: set_position(position[ dial=False[, raw=False]])
set (that is, redefine) the current position to supplied value.
:param position: The new motor position
:param dial: whether to set in dial coordinates. The default is user coordinates.
:param raw: whether to set in raw coordinates. The default is user coordinates.
The 'raw' and 'dial' keywords are mutually exclusive.
.. method:: get_pv(attr)
returns the `PV` for the corresponding attribute.
.. method:: set_callback(attr='drive'[, callback=None[, kw=None]])
sets a callback on the `PV` for a particular attribute.
.. method:: clear_callback(attr='drive')
clears a callback on the `PV` for a particular attribute.
.. method:: show_info()
prints out a table of attributes and their current values.
Other Device Examples
===========================
An epics Device provides a general way to group together a set of PVs. The
examples below show how to build on this generality, and may inspire you to
build your own device classes.
A basic Device without a prefix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here, we define a very simple device that does not even define a prefix.
This is not much more than a collection of PVs. Since there is no prefix
given, all PVs in the device must be *fully qualified*. Note that there is
no requirement to share a common prefix in such a collection of PVs::
from epics import Device
dev = Device()
p1 = dev.PV('13IDC:m1.VAL')
p2 = dev.PV('13IDC:m2.VAL')
dev.put('13IDC:m1.VAL', 2.8)
dev.put('13IDC:m2.VAL', 3.0)
print dev.PV('13IDC:m3.DIR').get(as_string=True)
Note that this device cannot use the attributes based on field names.
This may not look very interesting -- why not just use a bunch of PVs? If
ou consider `Device` to be a starting point for building more complicated
objects by subclassing `Device` and adding specialized methods, then it can
start to get interesting.
Epics ai record as Device
~~~~~~~~~~~~~~~~~~~~~~~~~~~
For a slightly more useful and typical example, the pyepics distribution
includes a Device for an Epics ai (analog input record). The full
implementation of this device is:
.. literalinclude:: ../epics/devices/ai.py
The code simply pre-defines the fields that are the *suffixes* of an Epics ai
input record, and subclasses :class:`Device` with these fields to create the
corresponding PVs. For most record suffixes, these will be available as
attributes of the Device object. For example, the :class:`ai` class above can
be used simply and cleanly as::
from epics.devices import ai
This_ai = ai('XXX.PRES')
print 'Value: ', This_ai.VAL
print 'Units: ', This_ai.EGU
Of course, you can also use the :meth:`get`, :meth:`put` methods above for a
basic :class:`Device`::
This_ai.put('DESC', 'My Pump')
Several of the other standard Epics records can easily be exposed as Devices in
this way, and the pyepics distribution includes such simple wrappings for the
Epics ao, bi, and bo records, as well as several more complex records from
synApps.
Epics Scaler Record as Device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For a slightly more complicated example: an incomplete, but very useful mapping
of the Scaler Record from synApps, including methods for changing modes, and
reading and writing data.
.. literalinclude:: ../epics/devices/scaler.py
Note that we can then create a :class:`scaler` object from its base PV
prefix, and use methods like :meth:`Count` and :meth:`Read` without
directly invoking epics calls::
s1 = Scaler('XXX:scaler1')
s1.setCalc(2, '(B-2000*A/10000000.)')
s1.enableCalcs()
s1.OneShotMode()
s1.Count(t=5.0, wait=True)
print 'Names: ', s1.getNames()
print 'Raw values: ', s1.Read(use_calc=False)
print 'Calc values: ', s1.Read(use_calc=True)
Other Devices included in PyEpics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Several other Epics Records have been exposed as Devices, and included in
PyEpics distribution. These vary some in how complete and feature-rich they
are, and are definitely skewed toward data collection at synchrotron beamlines.
A table of current Devices are listed in the :ref:`Table of Included Epics
Devices <devices_table>` table below. For further details, consult the source
code for these modules.
.. _devices_table:
Table of Epics Devices Included in the PyEpics distribution. For those
described as "pretty basic", there are generally only PV suffixes to
attributes mapped. Many of the others include one or more methods for
specific use of that Device.
+----------------+-----------------+------------------------------------------------+
| **module** | **class** | description |
+================+=================+================================================+
| ad_base | AD_Camera | areaDetector Camera, pretty basic |
+----------------+-----------------+------------------------------------------------+
| ad_fileplugin | AD_FilePlugin | areaDetector File Plugin, many methods |
+----------------+-----------------+------------------------------------------------+
| ad_image | AD_ImagePlugin | areaDetector Image, with ArrayData attribute |
+----------------+-----------------+------------------------------------------------+
| ad_overlay | AD_OverlayPlugin| areaDetector Overlay, pretty basic |
+----------------+-----------------+------------------------------------------------+
| ad_perkinelmer | AD_PerkinElmer | PerkinElmer(xrd1600) detector, several methods |
+----------------+-----------------+------------------------------------------------+
| ai | ai | analog input, pretty basic (as above) |
+----------------+-----------------+------------------------------------------------+
| ao | ao | analog output, pretty basic |
+----------------+-----------------+------------------------------------------------+
| bi | bi | binary input, pretty basic |
+----------------+-----------------+------------------------------------------------+
| bo | bo | binary output, pretty basic |
+----------------+-----------------+------------------------------------------------+
| mca | MCA | epics DXP record, pretty basic |
+----------------+-----------------+------------------------------------------------+
| mca | DXP | epics MCA record, get_rois()/get_calib() |
+----------------+-----------------+------------------------------------------------+
| mca | MultiXMAP | Multiple XIA XMaps, several methods |
+----------------+-----------------+------------------------------------------------+
| scaler | Scaler | epics Scaler record, many methods |
+----------------+-----------------+------------------------------------------------+
| scan | Scan | epics SScan record, some methods |
+----------------+-----------------+------------------------------------------------+
| srs570 | SRS570 | SRS570 Amplifier |
+----------------+-----------------+------------------------------------------------+
| struck | Struck | SIS Multichannel Scaler, many methods |
+----------------+-----------------+------------------------------------------------+
| transform | Transform | epics userTransform record |
+----------------+-----------------+------------------------------------------------+
| xspress3 | Xspress3 | Quantum Electronics Xspress3 Multi-MCA |
+----------------+-----------------+------------------------------------------------+
|
