.. _dcsif:

Introduction
############

Reference Documents
===================

[RD1]
    | Central Control System Development Standards;
    | `ESO-366378 v1 <https://pdm.eso.org/kronodoc/HQ/ESO-366378>`_


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 <https://gitlab.eso.org/ecos/dcsif/-/blob/master/dcs/if/resource/config/dcs/dcs_sm.png>`_.

In SCXML format, `here <https://gitlab.eso.org/ecos/dcsif/-/blob/master/dcs/if/resource/config/dcs/dcssm.xml>`_.

.. module:: dcsif

Interfaces
==========

.. class:: DcsCmds

    DCS Request/Response Interface.

    .. method:: Abort() -> String.

        Abort an on-going initialisation procedure or data acquisition.

        :return: A string with information about the execution of the request.
        :rtype: String
        :raises dcsif::ExceptionErr: On error.

    .. method:: Execute(dcsif::Method) -> String.

        Execute an operation in the DCS application.

        :param dcsif::Method method: Structure containing name and parameters for the method invocation.
        :return: A string with information about the execution of the request.
        :rtype: String
        :raises dcsif::ExceptionErr: On error.

    .. method:: GetConfig(parameters) -> String.

        Query the entire or selected configuration parameters.

        :param str parameters: Optional (may be empty). May be used to specify the parameters to query in JSF or SPF.
        :return: The status of the parameters requested in JSF.
        :rtype: String/JSF.
        :raises dcsif::ExceptionErr: On error.

    .. method:: 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.

        :return: Report with the diagnostics (status) of the system. Format is context specific.
        :rtype: String.
        :raises dcsif::ExceptionErr: On error.

    .. method:: GetDpData() -> String.

        Deprecated -- will be removed from ICSV4.

    .. method:: GetSetup(parameters) -> String.

        Query the entire or selected setup parameters.

        :param str parameters: Optional (may be empty). May be used to specify the parameters to query in JSF or SPF.
        :return: The status of the parameters requested in JSF.
        :rtype: String/JSF.
        :raises dcsif::ExceptionErr: On error.

    .. method:: Ping() -> String.

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

        :return: Format: "OK:<ISO 8601 timestamp>".
        :rtype: String.
        :raises dcsif::ExceptionErr: On error.

    .. method:: ReadPars(parameters) -> String.

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

        :param str parameters: Optional (may be empty). May be used to specify the parameters to query in JSF or SPF.
        :return: The status of the parameters requested in JSF.
        :rtype: String/JSF.
        :raises dcsif::ExceptionErr: On error.

    .. method:: Recover() -> String.

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

        :return: Information about execution of the request.
        :rtype: String.
        :raises dcsif::ExceptionErr: On error.

    .. method:: Scan() -> String.

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

        :return: The status of the parameters requested in JSF.
        :rtype: String/JSF.
        :raises dcsif::ExceptionErr: On error.

    .. method:: SetConfig(parameters) -> String.

        Set one or more configuration parameters.

        :param str parameters: Parameters to set in JSF or SPF.
        :return: Status of the execution of the request.
        :rtype: String.
        :raises dcsif::ExceptionErr: On error.

    .. method:: Setup(parameters) -> String.

        Set one or more setup parameters.

        :param str parameters: Parameters to set in JSF or SPF.
        :return: Status of the execution of the request.
        :rtype: String.
        :raises dcsif::ExceptionErr: On error.

    .. method:: Start(properties) -> String.

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

        :param dcsif::StartProperties parameters: Properties for starting the image acquisition.
        :return: Status of the execution of the request.
        :rtype: String.
        :raises dcsif::ExceptionErr: On error.

    .. method:: WritePars(parameters) -> String.

        Write one or more parameters. Used for engineering purposes.

        :param str parameters: Parameters to set in JSF or SPF.
        :return: Status of the execution of the request.
        :rtype: String.
        :raises dcsif::ExceptionErr: On error.

Data Structures
===============

.. class:: 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:: ExceptionErr

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

    .. attribute:: code
        :type: int

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

    .. attribute:: desc
        :type: str

        Description of the exception (diagnostics).

.. class:: Method

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

    .. attribute:: name
        :type: str

        Name of method to execute.

    .. attribute:: parameters
        :type: str

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


.. class:: StartProperties

    Defines the conditions for starting the image acquisition.
    
    .. attribute:: absTime
        :type: double
    
        Absolute point in time given as seconds since epoch for when to start the image acquisition.
    
    .. attribute:: customTrigger
        :type: str
    
        Name of context specific trigger (method) to trigger/start the image acquisition.

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

    .. attribute:: trigger
        :type: StartTriggerTypes
    
        Type of trigger (method) to apply.
