EPICS put completion¶
EpicsSignal supports EPICS put completion, which means EPICS reports back when the write request itself has completed.
This is an EPICS-specific detail that matters because it changes how set() decides that a write is finished.
Configuring put_complete¶
The relevant option is put_complete, which is configured on the signal definition. The default value is False.
from ophyd import Component as Cpt, Device, EpicsSignal
class MyDevice(Device):
my_signal = Cpt(EpicsSignal, "PV:NAME", put_complete=True)
How it changes set()¶
For EpicsSignal.set(), put_complete changes the completion condition:
| Configuration | Completion behavior | What the caller gets |
|---|---|---|
put_complete=False |
set() writes the value, then waits until the readback reaches the target. |
A Status that completes when the readback matches. |
put_complete=True |
set() calls put(..., use_complete=True) internally and finishes when EPICS reports put completion. |
A Status that completes on EPICS put completion. |
How put_complete changes set()
put_complete=False: "wait until the signal value reaches the requested target"put_complete=True: "wait until EPICS says the write request has completed"
This can be useful for EPICS signals where the EPICS put-completion callback is the right completion signal for the write.
Example: areaDetector acquisition¶
An areaDetector camera's Acquire PV illustrates the difference when its IOC sends the put-completion callback only after acquisition finishes. The following examples use direct ophyd signals on the device server. Replace the example PV name with your camera's Acquire PV and configure a finite acquisition before trying either example. Run them separately, starting with an idle camera each time.
from ophyd import EpicsSignal
acquire = EpicsSignal("CAMERA:cam1:Acquire", name="acquire", put_complete=False)
acquire.set(1, timeout=10).wait()
# Returns when the Acquire PV reaches 1; acquisition may still be running.
acquire = EpicsSignal("CAMERA:cam1:Acquire", name="acquire", put_complete=True)
acquire.set(1, timeout=10).wait()
# Waits for the IOC's put-completion callback, after acquisition finishes.
The timeout bounds the operation, and .wait() raises if the operation times out. Choose a timeout that allows for your configured acquisition duration. With put_complete=False, a very short acquisition can finish before readback polling observes 1, causing the operation to time out even though acquisition finished.
The difference is what completes the Status: observing the requested value (1) or receiving the IOC's callback. put_complete=True does not itself make the IOC wait for acquisition. The record and driver implementation determine when the callback is sent. If the IOC acknowledges the write as soon as acquisition starts, the second example also returns before acquisition finishes. Verify the callback behavior for your IOC before using it as an acquisition-completion signal.
What it does not change¶
put_complete changes how set() finishes, but it does not change the role of put().
Even when put_complete=True is enabled on the signal:
put()still performs a direct writeput()still returns immediatelyput()still does not return aStatus
That is why set() remains the normal ophyd API when the caller needs structured completion tracking.
What to remember
put_completeis anEpicsSignaloption that changes howset()decides the write is finished.- With
put_complete=False,set()waits for the readback to reach the target. - With
put_complete=True,set()finishes when EPICS reports put completion. put_completedoes not turnput()into a completion-tracked API:put()still writes directly and returns immediately.