Introduction

Reference Documents

[RD1]: Central Control System Development Standards;

ESO-366378 v1

Detector Control Software Interface

The DCS Interface, dcsif, defines the CII request/reponse interface for DCS type of applications.

This document serves merely to provide an overview of the DCS interface. The CII MAL generates the structures (classes) for the interface and are not described in this document.

In the following “JSON Serialisation Format” is referenced as “JSF” and “Simple Parameter Format” as “SPF”.

The DCS state machine is defined in this diagram.

In SCXML format, here.

Interfaces

class dcsif.DcsCmds

DCS Request/Response Interface.

Abort() → String.

Abort an on-going initialisation procedure or data acquisition.

Returns:: A string with information about the execution of the request.
Return type:: String
Raises:: dcsif::ExceptionErr – On error.

Execute(dcsif::Method) → String.

Execute an operation in the DCS application.

Parameters:: method (dcsif::Method) – Structure containing name and parameters for the method invocation.
Returns:: A string with information about the execution of the request.
Return type:: String
Raises:: dcsif::ExceptionErr – On error.

GetConfig(parameters) → String.

Query the entire or selected configuration parameters.

Parameters:: parameters (str) – Optional (may be empty). May be used to specify the parameters to query in JSF or SPF.
Returns:: The status of the parameters requested in JSF.
Return type:: String/JSF.
Raises:: dcsif::ExceptionErr – On error.

GetDiagnostics() → String.

Request to produce a status of the condition of the system for diagnostics purposes. The information provided is context specific. This is typically used by the system operators to retrieve the diagnostics to be submitted for troubleshooting purposes.

Returns:: Report with the diagnostics (status) of the system. Format is context specific.
Return type:: String.
Raises:: dcsif::ExceptionErr – On error.

GetDpData() → String.: Deprecated – will be removed from ICSV4.

GetSetup(parameters) → String.

Query the entire or selected setup parameters.

Parameters:: parameters (str) – Optional (may be empty). May be used to specify the parameters to query in JSF or SPF.
Returns:: The status of the parameters requested in JSF.
Return type:: String/JSF.
Raises:: dcsif::ExceptionErr – On error.

Ping() → String.

Request the DCS to send a reponse to indicate it is alive and functioning.

Returns:: Format: “OK:<ISO 8601 timestamp>”.
Return type:: String.
Raises:: dcsif::ExceptionErr – On error.

ReadPars(parameters) → String.

Query parameters of the associated camera or dectector contol electronics. Used for engineering purposes.

Parameters:: parameters (str) – Optional (may be empty). May be used to specify the parameters to query in JSF or SPF.
Returns:: The status of the parameters requested in JSF.
Return type:: String/JSF.
Raises:: dcsif::ExceptionErr – On error.

Recover() → String.

Request the DCS to attempt to recover when in Error State.

Returns:: Information about execution of the request.
Return type:: String.
Raises:: dcsif::ExceptionErr – On error.

Scan() → String.

Scan parameter name space of the associated camera or detector control electronics. Used for engineering purposes.

Returns:: The status of the parameters requested in JSF.
Return type:: String/JSF.
Raises:: dcsif::ExceptionErr – On error.

SetConfig(parameters) → String.

Set one or more configuration parameters.

Parameters:: parameters (str) – Parameters to set in JSF or SPF.
Returns:: Status of the execution of the request.
Return type:: String.
Raises:: dcsif::ExceptionErr – On error.

Setup(parameters) → String.

Set one or more setup parameters.

Parameters:: parameters (str) – Parameters to set in JSF or SPF.
Returns:: Status of the execution of the request.
Return type:: String.
Raises:: dcsif::ExceptionErr – On error.

Start(properties) → String.

Start the image acquisition of the associated camera or detector control electronics.

Parameters:: parameters (dcsif::StartProperties) – Properties for starting the image acquisition.
Returns:: Status of the execution of the request.
Return type:: String.
Raises:: dcsif::ExceptionErr – On error.

WritePars(parameters) → String.

Write one or more parameters. Used for engineering purposes.

Parameters:: parameters (str) – Parameters to set in JSF or SPF.
Returns:: Status of the execution of the request.
Return type:: String.
Raises:: dcsif::ExceptionErr – On error.

Data Structures

class dcsif.StartTriggerTypes

Possible options for trigger the start of the data acquisition. The values defined are:

Signal: Start acqusition based on a hardware signal, usually a TTL signal fed into the camera/detector electronics.
AbsTime: Start acquisition based on an absolute point in time.
Custom: Start acquisition based on a context specific method.
NotUsed: Start acquisition immediately upon receiving the Start Request.

class dcsif.ExceptionErr

DCS Exception class thrown in case an error is encountered while handling a request.

code: int: Exception (error) code allocated to the specific exception; 0 if no code is allocated.

desc: str: Description of the exception (diagnostics).

class dcsif.Method

DCS Exception class thrown in case an error is encountered while handling a request.

name: str: Name of method to execute.

parameters: str: Input parameters for the method invocation. suggested format is in JSF or SPF.

class dcsif.StartProperties

Defines the conditions for starting the image acquisition.

absTime: double: Absolute point in time given as seconds since epoch for when to start the image acquisition.

customTrigger: str: Name of context specific trigger (method) to trigger/start the image acquisition.

info: str: Free format information (context specific) to submit with the request.

trigger: StartTriggerTypes: Type of trigger (method) to apply.