.. _stdif:

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

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

[RD1]
    | Central Control System Development Standards;
    | `ESO-366378 v1 <https://pdm.eso.org/kronodoc/HQ/ESO-366378>`_
[RD2]
    | ELT - Technical note on Standard Application Interface and State Machine;
    | `ESO-321402 <https://pdm.eso.org/kronodoc/HQ/ESO-321402>`_


Standard Interface
##################

Standard interface, ``stdif``, is the interface to be used by all components
that implement the standard ELT interface and state machine [RD2].

This documentation provides an overview of the interface.  For data structures
only the data members are documented, not the accessors generated by MAL. Similarly names are not
fully qualified as it is different across the supported languages.


.. module:: stdif

Interfaces
==========

.. class:: StdCmds

    Standard interface.

    .. method:: Stop() -> String

        Stop any ongoing activity.

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

    .. method:: Init() -> String

        Command to request the initialization of the Application. After
        successful initialization, the Applicaiton will be NotOperational::Ready
        The Application cannot drive any movement, monitoring is available
        and it is ready to be Enabled.

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

    .. method:: Reset() -> String

        Command to perform a full reset of the Application and re-enter the
        NotOperational::NotReady state

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

    .. method:: Enable() -> String

        Command to request to enable the Application, i.e. to allow executing
        movements. After successful Enable, the Application will be
        Operational.

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

    .. method:: Disable() -> String

        Command to move back from Operational to NotOperational, stopping
        and disabling any movement.

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

    .. method:: GetState() -> String

        Command to request the state of the Application, i.e. the complete (for
        example composite if the state machine has multiple regions) state of
        the internal state machine

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

    .. method:: GetStatus() -> String

        Command to request the "System Status" (to be better
        defined and dependent on the specific application). For Supervisor 
        applications, the output format shall be:

                <aggregated state>;<aggregated substate>
        
        Applications shall report the same through the Status topic.

        :return: Format: "<state>;<substate>".
        :rtype: String
        :raises stdif::ExceptionErr: On error.

    .. method:: GetVersion() -> String

        Returns the Application's version string.

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

    .. method:: Exit() -> String

        Requests the Application to Exit. The Application shall stop any
        ongoing activity, go to safe conditions, cleanly shutdown and exit any
        process. At the end of the Exit, the State as published in the OLDB
        shall be OFF.

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

    .. method:: SetLogLevel(info) -> String

        Sets the logging level for the Application.

        :param info: structure including the level and the logger information.
        :return: A string with information about the execution of the request.
        :rtype: LogInfo
        :raises stdif::ExceptionErr: On error.

    .. method:: GetLogLevel(logger) -> Array<LogInfo>

        Requests log information for a particular logger, or the complete
        set of available loggers and their levels in the server application.

        :param logger: The name of the logger of which the information is
                       requested. If an empty string is used as argument, then
                       all the loggers will be used.
        :return: An array of LogInfo structures. Each containing a logger
                and its log level.
        :rtype: Array<LogInfo>
        :raises stdif::ExceptionErr: On error.


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


.. class:: ExceptionErr

     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:: State

     Provides the current state of the application state machine engine.

     .. attribute:: source
          :type: string

          Indicates the name of the application instance updating the topic.

     .. attribute:: state
          :type: string

          String having the format returned by the application state machine engine.


.. class:: Status

     Defines the topic that shall be used by subsystems to inform supervisors about theirs status.
     For Supervisor applications, the output format shall be:

                <aggregated state>;<aggregated substate>

     .. attribute:: source
          :type: string

          Indicates the name of the application instance updating the topic.

     .. attribute:: status
          :type: string

          String having the format <state>;<substate>


.. class:: LogInfo

     Carries Logger information, either to be set (see SetLogLevel), or as
     feedback (see GetLogLevel).

     .. attribute:: level 
          :type: string

          String specifying the log level.

     .. attribute:: logger
          :type: string

          String specifying the name of the logger.
