OCM Data Acquisition Control¶

Note

daqOcmServer hosts the Data Acquisition control interface daqif.OcmDaqControl under URI path /daq.

class daqif.OcmDaqControl¶

StartDaq(id, file_prefix, prim_sources, meta_sources, properties) → DaqReply ¶

Create and start new data acquisition with v1 merge-heuristics. If id is not provided (left empty) daqOcmServer will create a unique identifer automatically.

Heuristics

The following heuristics is used to determine how results are merged together. For more control use StartDaqV2().

If a single primary data source produce a single FITS file this will selected as the in-place merge target. - Otherwise data sources produce multi-extension FITS files with no data in primary HDU. - Data sources have the following relative priority:

Note

Order determines merge order of keywords and extensions.
1. Primary data sources in the order user specified in prim_sources.
2. Metadata sources in the order user specified to meta_sources.
Each data source produce keywords that will be merged to Data Product primary HDU returned via metadaqif or with FITS file primary HDU.
There is currently no way to provide keyword rules that select and transforms keywords. All keywords in user class will be merged.

Arguments

The format for prim_sources and meta_sources is a space separated list of sources in the format: <name>@<rr-uri>, e.g. meta-source@zpb.rr://example:1234/daq.

There must be at least 1 data source.

Fail-fast

If any source fails to start the command will fail.

Parameters

id (str) – Optional unique identifier of data acquisition.
file_prefix (str) – Optional file name prefix.
prim_sources (str) – List of primary data sources (e.g. detectors).
meta_sources (str) – List of metadata sources (e.g. FCF Device Manager or CCS).
properties (str) – JSON properties (see StartDaqV1Properties {JSON}).

Returns

If id was provided that is returned as an acknowledgement, otherwise the id generated by daqOcmServer is returned.

Return type

DaqReply

Raises

DaqException – On fatal error.

StartDaqV2(specification) → DaqReply ¶

New in version 2.1.0.

Create and start new data acquisition from JSON specification.

StartDaqV2() was introduced in to enable the capabilities of daqDpmMerge that was not possible to express using StartDaq(). The decision was also made to use JSON to express the specification to allow more flexible extensibility.

See Start DAQ v2 for detailed documentation of the JSON schema.

Note

This version is strictly more capable than StartDaq() and is required when additional control of the outcome is required. Unlike StartDaq() it also supports specifying how to merge FITS files that already exist.

Fail-fast

If any source fails to start the command will fail.

Parameters: specification (str) – Serialized JSON document. See StartDaqV2Specification {JSON} for details.
Returns: If id was provided that is returned as an acknowledgement, otherwise the id generated by daqOcmServer is returned.
Return type: DaqReply
Raises: DaqException – On fatal error.

StopDaq(id) → DaqReply ¶

Stops data acquisition and keep any data acquired.

Fail-Fast

If all data sources fail the command will report error by throwing DaqException. A partially successful execution is reported using normal status reply (which includes information about any partial failure). This is done because it is prioritized to create a partially complete data product over discarding all acquired data.

Parameters: id (str) – Id of data acquisition to stop.
Return type: DaqReply
Raises: DaqException – On fatal error.

ForceStopDaq(id) → DaqReply ¶

Like StopDaq() the command stops data acquisition and keeps any data acquired. The only difference is that if non-fatal error occurs the Data Acquisition is marked as stopped whereas StopDaq() would not.

Fail-slow

The command is resilient to non-fatal errors. If any non-fatal errors occur the error flag in the reply is set but no exception is thrown. If fatal error occur DaqException is thrown.

Warning

Any data source that failed to stop properly will not be able to provide data to the Data Acquisition or the final Data Product.

Although daqOcmServer is always left in a consistent state, any data source that failed to stop may not. Manual intervention my be necessary to restore a problematic data source to a functional state.

Parameters: id (str) – Id of data acquisition to forcibly stop.
Return type: DaqReply
Raises: DaqException – On fatal error.

AbortDaq(id) → DaqReply ¶

Aborts data acquisition and discards any data acquired.

Fail-fast

If any error occur DaqException is thrown and the DAQ state remains in Aborting.

Parameters: id (str) – Id of data acquisition to abort.
Return type: DaqReply
Raises: DaqException – On fatal error.

ForceAbortDaq(id) → DaqReply ¶

Like AbortDaq() the command aborts data acquisition and discards any data acquired. The only difference is that if non-fatal error occurs the Data Acquisition is marked as aborted whereas AbortDaq() would not.

Fail-slow

The command is resilient to non-fatal errors. If any non-fatal errors occur the error flag in the reply is set but no exception is thrown. If fatal error occur DaqException is thrown.

Warning

Although daqOcmServer is always left in a consistent state, any data source that failed to abort may not. Manual intervention may be necessary to restore a problematic data source to a functional state.

Parameters: id (str) – Id of data acquisition to forcibly abort.
Return type: DaqReply
Raises: DaqException – On fatal error.

UpdateKeywords(id: str, keywords: str) → DaqReply ¶

Update keywords for specified Data Acquisition. For each keyword:

If it already exist 1, it is updated with the provided value,
otherwise it is added.

1: OCM will compare keyword name as provided, while considering if it’s an ESO hiearchical keyword or standard FITS keyword.

Fail-fast

Command will not make any attempt to be robust against errors. Failures are treated as fatal and DaqException will be thrown.

Parameters

id (str) – Id of data acquisition to update.
keywords (str) – JSON encoded set of keywords. Refer to JSON keywords schema for details.

Return type

DaqReply

Raises

DaqException – On fatal error.

AwaitDaqState(id, state, substate, timeout) → AwaitDaqReply ¶

Await a particular Data Acquisition state. This is mainly used to support sequencing of higher level coordination activities.

The command will reply when condition is fulfilled or times out. When it times out this is indicated in the reply with AwaitDaqReply.timeout set to true.

Condition is fulfilled whenever the requested state and substate is either achieved or no longer possible to achieve. Awaiting e.g. the condition. DaqState.StateMerging/ DaqSubState.Scheduled will be fulfilled also for DaqState.StateCompleted/DaqSubState.Aborted. Perhaps a more likely scenario is that multiple state transitions occurred before request was handled, such that a subsequent state is reported instead of the requested state/substate.

Note

OCM v1.0.0 implements all substates in DaqState.StateAcquiring and py:attr:DaqState.StateCompleted/DaqSubState.Aborted. As such it is not possible to await other states.

Parameters

id (str) – Id of Data Acquisition to await.
state (DaqState) – State of Data Acquisition to await.
substate (DaqSubState) – Substate of Data Acquisition to await.
timeout (float) – Duration in seconds to wait for condition to be fulfilled. Must be > 0.

Returns

Current Data Acquisition status and indication if operation timed out.

Return type

AwaitDaqReply

Raises

DaqException – On fatal error (e.g. invalid arguments).

GetDaqStatus(id) → DaqStatus ¶

Get Data Acquisition status.

Parameters: id (str) – Id of data acquisition to get status for.
Return type: DaqStatus
Raises: DaqException – On fatal error.

GetActiveList() → List[DaqStatus]¶

Get list of active Data Acquisitions (i.e. not in daqif.DaqState.StateCompleted).

Returns: List of active Data Acquisitions.
Return type: List[DaqStatus]
Raises: DaqException – On fatal error.