Skip to content

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 write
  • put() still returns immediately
  • put() still does not return a Status

That is why set() remains the normal ophyd API when the caller needs structured completion tracking.

What to remember

  • put_complete is an EpicsSignal option that changes how set() 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_complete does not turn put() into a completion-tracked API: put() still writes directly and returns immediately.