beamline settings...

Author: Kay Kasemir (ky9)

doc/getting_started.rst

@@ -243,7 +243,35 @@ need to be configured on the scan server.
 Default Device Settings
 -----------------------
 
-TODO
+A command to turn a power supply on or set a voltage may be instantaneous::
+
+    commands = [ Set('PS42:Voltage', 12.0), Comment("PS is now on at 12 Volts")]
+
+But this device behavior tends to be the exception.
+When controlling a motor, the EPICS motor support allows using a "put-callback"
+to the device which waits until the motor reaches the desired location.
+This mechanism is also referred to as "completion".
+A temperature controller might support completion on its temperature
+setpoint PV.
+On devices that do not support completion, it may be possible
+to read the current device state from a separate readback PV and wait until
+it agrees with the commanded value.
+
+Based on the device at hand, we want to use the appropriate :class:`.Set` command::
+
+   Set('SomePV', 42.3, completion=True, timeout=30)
+   Set('SomePV', 42.3, completion=True, timeout=3000)
+   Set('SomePV', 42.3, completion=True, timeout=3000, readback="SomePV.RBV", tolerance=0.1)
+   Set('SomePV', 42.3, readback="OtherPV", tolerance=10, timeout=15)
+   
+Unfortunately, the "correct" way to set a PV is not discernible from the outside.
+It requires knowledge about the implementation of a PV in the IOC.
+And even if the correct way to set a PV is known, having to type
+all parameters for each `Set` command can be cumbersone.
+The PyScanClient library offers :ref:`scan_settings` where the ideal
+parameters for each PV can be configured once, and wrappers for the
+basic `Set` and `Wait` commands will then automatically use them as a default.
+
 
 Table Scan
 ----------

example/beamline_setup.py

@@ -31,10 +31,12 @@ def __init__(self):
         self.loggable = [ "signal" ]
 
     def getReadbackName(self, device_name):
-        # Prime example would be a motor:
-        #if "motor" in device_name:
-        #    return device_name + ".RBV"
-        return device_name
+        # Anything that looks like a motor very likely has a .RBV.
+        # But that does not apply to the simulated motor_x, motor_y
+        if device_name in ( 'motor_x', 'motor_y' ):
+            return device_name
+        if "motor" in device_name:
+           return device_name + ".RBV"
 
 scan_settings = BeamlineScanSettings()
 # Install beam line specific scan settings

scan/commands/set.py

@@ -42,7 +42,8 @@ class Set(Command):
     we wait for up to `timeout` seconds for the readback to be within tolerance.    
 
     *Note use of completion:*
-    EPICS Channel Access does not communicate if completion ('put-callback') is actually
+    The EPICS network protocol, be it Channel Access or PV Access,
+    does not communicate if completion ('put-callback') is actually
     supported. When writing to a PV that does not support completion, the call is returned
     right away, just as it would for a PV that supports completion and happens to complete
     quickly.
@@ -67,9 +68,9 @@ class Set(Command):
     but can be problematic for a device where the readback will
     take time to settle. Examples include PID-controlled devices
     with overshoot and settling time, or motors with backlash compensation
-    and retries where the readback might early on be close to the setpoint,
-    but it has not settled, so we consider it 'done' when in fact the
-    device is actively changing its value.
+    and retries. The readback can be close to the setpoint,
+    but the device might not have settled. We can then erroneously consider it 'done'
+    while the device is in fact still actively changing its value.
 
     **Use case 3: Enable completion but no readback**
 

scan/util/scan_settings.py

@@ -1,4 +1,6 @@
 """
+.. _scan_settings:
+
 Scan settings
 =============